cgul_multimap_node.h File Reference

multimap node More...

#include "cgul_common.h"
#include "cgul_exception.h"
#include "cgul_multimap_node.h"

Include dependency graph for cgul_multimap_node.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_multimap_node *	cgul_multimap_node_t

Functions
CGUL_EXPORT void *	cgul_multimap_node__get_key (cgul_exception_t *cex, cgul_multimap_node_t n)
CGUL_EXPORT void *	cgul_multimap_node__get_value (cgul_exception_t *cex, cgul_multimap_node_t n)
CGUL_EXPORT void	cgul_multimap_node__set_value (cgul_exception_t *cex, cgul_multimap_node_t n, const void *value)
CGUL_EXPORT cgul_multimap_node_t	cgul_multimap_node__get_prev (cgul_exception_t *cex, cgul_multimap_node_t n, int older_is_greater)
CGUL_EXPORT cgul_multimap_node_t	cgul_multimap_node__get_next (cgul_exception_t *cex, cgul_multimap_node_t n, int older_is_greater)
CGUL_EXPORT cgul_multimap_node_t	cgul_multimap_node__get_older (cgul_exception_t *cex, cgul_multimap_node_t n)
CGUL_EXPORT cgul_multimap_node_t	cgul_multimap_node__get_younger (cgul_exception_t *cex, cgul_multimap_node_t n)

Detailed Description

This class implements a multimap node which holds one key/value pair and enough information to find the next node.

Author

Paul Serice

Typedef Documentation

cgul_multimap_node_t

typedef typedefCGUL_BEGIN_C struct cgul_multimap_node* cgul_multimap_node_t

Opaque pointer to a cgul_multimap_node instance.

Function Documentation

cgul_multimap_node__get_key()

CGUL_EXPORT void* cgul_multimap_node__get_key	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n
	)

Return the key stored in this node. The key is used to determine the sort order of the node. If you want to set the value of the key, there is no method to do so because changing the value of a key requires changing the node's position in the cgul_multimap. Thus, if you need to change the value of a key, you should delete the node from the cgul_multimap and insert a new node with the new value for the key.

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance

Returns

key

Referenced by cgul_multimap_cxx::foldl_pairs(), cgul_multimap_cxx::foldr_pairs(), and cgul_multimap_node_cxx::get_key().

cgul_multimap_node__get_value()

CGUL_EXPORT void* cgul_multimap_node__get_value	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n
	)

Return the value stored in this node.

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance

Returns

value

Referenced by cgul_multimap_cxx::foldl_pairs(), cgul_multimap_cxx::foldl_values(), cgul_multimap_cxx::foldr_pairs(), cgul_multimap_cxx::foldr_values(), and cgul_multimap_node_cxx::get_value().

cgul_multimap_node__set_value()

CGUL_EXPORT void cgul_multimap_node__set_value	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n,
		const void *	value
	)

Set the value stored in this node.

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance
[in]	value

Referenced by cgul_multimap_node_cxx::set_value().

cgul_multimap_node__get_prev()

CGUL_EXPORT cgul_multimap_node_t cgul_multimap_node__get_prev	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n,
		int	older_is_greater
	)

Return the previous node. You can use this method to iterate over the multimap. When there are no more nodes, NULL is returned. You can use cgul_multimap__get_back() to get the last node in a cgul_multimap in order to start iterating.

The primary sort criterion is the user's compare function, of course, but the older_is_greater boolean is used as a secondary sort criterion. When a key maps to many values, the older_is_greater boolean determines how to sort the older nodes relative to the newer nodes.

The way the older_is_greater boolean works in this implementation is that each key maps to a linked list of values. The compare function only determines the relative order of the keys. To order the values, this implementation always pushes newer values onto the front of the list. Thus, the newest value is always at the front of the list, and the oldest value is always at the back of the list. If older_is_greater is true, the sort order is from front to back. If older_is_greater is false, the sort order is from back to front.

For example, if you want to iterate over the values for a particular key in the same order they were inserted, you would call this method with older_is_greater set to 0. This way, the older values are considered to be less than the newer values.

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance
[in]	older_is_greater	whether older nodes are greater than newer nodes

Returns

previous node

Referenced by cgul_multimap_cxx::foldr_pairs(), cgul_multimap_cxx::foldr_values(), and cgul_multimap_node_cxx::get_prev().

cgul_multimap_node__get_next()

CGUL_EXPORT cgul_multimap_node_t cgul_multimap_node__get_next	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n,
		int	older_is_greater
	)

Return the next node. You can use this method to iterate over the multimap. When there are no more nodes, NULL is returned. You can use cgul_multimap__get_front() to get the first node in a cgul_multimap in order to start iterating.

The primary sort criterion is the user's compare function, of course, but the older_is_greater boolean is used as a secondary sort criterion. When a key maps to many values, the older_is_greater boolean determines how to sort the older nodes relative to the newer nodes.

The way the older_is_greater boolean works in this implementation is that each key maps to a linked list of values. The compare function only determines the relative order of the keys. To order the values, this implementation always pushes newer values onto the front of the list. Thus, the newest value is always at the front of the list, and the oldest value is always at the back of the list. If older_is_greater is true, the sort order is from front to back. If older_is_greater is false, the sort order is from back to front.

For example, if you want to iterate over the values for a particular key in the same order they were inserted, you would call this method with older_is_greater set to 0. This way, the older values are considered to be less than the newer values.

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance
[in]	older_is_greater	whether older nodes are greater than newer nodes

Returns

next node

Referenced by cgul_multimap_cxx::foldl_pairs(), cgul_multimap_cxx::foldl_values(), cgul_multimap_node_cxx::get_next(), and cgul_multimap_cxx::traverse_range().

cgul_multimap_node__get_older()

CGUL_EXPORT cgul_multimap_node_t cgul_multimap_node__get_older	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n
	)

Return the next older node. Together with cgul_multimap_node__get_younger(), this method lets you traverse the multimap in chronological order. If there is no older node, this method returns NULL.

The following example shows how to iterate over the entire multimap in reverse chronological order. Notice that you have to start with the youngest node when calling cgul_multimap_node__get_older():

    cgul_multimap_node_t n = cgul_multimap__get_youngest(cex, mm);
    for ( ; n ; n = cgul_multimap_node__get_older(cex, n)) {
        ...
    }

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance

Returns

older node

Referenced by cgul_multimap_node_cxx::get_older().

cgul_multimap_node__get_younger()

CGUL_EXPORT cgul_multimap_node_t cgul_multimap_node__get_younger	(	cgul_exception_t *	cex,
		cgul_multimap_node_t	n
	)

Return the next younger node. Together with cgul_multimap_node__get_older(), this method lets you traverse the multimap in chronological order. If there is no younger node, this method returns NULL.

The following example shows how to iterate over the entire multimap in chronological order. Notice that you have to start with the oldest node when calling cgul_multimap_node__get_younger():

    cgul_multimap_node_t n = cgul_multimap__get_oldest(cex, mm);
    for ( ; n ; n = cgul_multimap_node__get_younger(cex, n)) {
        ...
    }

Parameters

[in]	cex	c-style exception
[in]	n	cgul_multimap_node instance

Returns

younger node

Referenced by cgul_multimap_node_cxx::get_younger().