collection.h File Reference

Functions for collection data structures such as set and array . More...

#include <glib.h>

Go to the source code of this file.

Data Structures
struct	HashSet
	HashSet: A set which backed by Hash Table. More...
Defines
#define	G_PTR_ARRAY_REMOVE_ALL(array)   if (array->len>0) g_ptr_array_remove_range(array,0,array->len)
	Remove all elements of a GPTRArray.
#define	G_ARRAY_CONCAT(dest, src)   g_array_append_vals(dest,src->data,src->len)
	Concatenate two GArrays.
#define	G_ARRAY_REMOVE_ALL(array)   if (array->len>0) g_array_remove_range(array,0,array->len)
	Remove all elements of a GArray.
Typedefs
typedef gboolean(*	ForeachCallbackFunc )(gpointer data, gpointer userdata)
	Foreach callback function prototype.
Enumerations
enum	ElementType { ELEMENTS_TYPE_INTEGER, ELEMENTS_TYPE_STRING, ELEMENTS_TYPE_POINTER, ELEMENTS_TYPE_CUSTOM }
	Enumeration of element types which the collection stores. More...
Functions
HashSet *	hashSet_new_default (ElementType type)
	New a HashSet instance with default handling functions.
HashSet *	hashSet_new (ElementType type, GHashFunc hash_func, GEqualFunc element_equal_func)
	New a HashSet instance.
HashSet *	hashSet_new_full (ElementType type, GHashFunc hash_func, GEqualFunc element_equal_func, GDestroyNotify element_destroy_func)
	New a HashSet instance, while specifying element destroy function.
void	hashSet_copy (HashSet *dest, HashSet *src)
	Copy from another HashSet.
guint	hashSet_get_size (HashSet *hashSet)
	Get the number of elements in the HashSet.
gboolean	hashSet_has_element (HashSet *hashSet, gconstpointer element)
	Whether a element is in the HashSet.
gboolean	hashSet_add_element (HashSet *hashSet, gpointer element)
	Add an element to the HashSet.
void	hashSet_remove_all (HashSet *hashSet)
	Remove all elements in the set.
gboolean	hashSet_remove_element (HashSet *hashSet, gconstpointer element)
	Remove an element to the HashSet.
void	hashSet_steal_all (HashSet *hashSet)
	Steal all elements in the set.
gboolean	hashSet_steal_element (HashSet *hashSet, gconstpointer element)
	Steal an element to the HashSet.
char *	hashSet_to_string (HashSet *hashSet)
	New a string representation for the content of the HashSet.
void	hashSet_destroy (HashSet *hashSet)
	Free the hashSet instance.
int	integer_compareFunc (gconstpointer a, gconstpointer b)
	GCompareFunc that compares two intergers.
int	g_array_find (GArray *array, gpointer element, gint elementSize, GCompareFunc func)
	Find an element in a GArray.
GArray *	g_array_copy (GArray *dest, GArray *src)
	Copy from another GArray.
Set operations.
Set operation functions such as union and interset.
void	hashSet_union (HashSet *result, HashSet *hashSet1, HashSet *hashSet2)
	Union two sets.
void	hashSet_intersect (HashSet *result, HashSet *hashSet1, HashSet *hashSet2)
	Intersect two sets.

---

Detailed Description

This header file lists functions for collection data structures such as set and array.

---

Define Documentation

#define G_ARRAY_CONCAT	(	dest,
		src		)	g_array_append_vals(dest,src->data,src->len)

This macro appends GArray src to dest . The results is stored in dest.

Parameters:

	dest	The GArray to be append to.
	src	The GArray to be appended from.

Returns:

The GArray dest.

#define G_ARRAY_REMOVE_ALL

(

array

)

if (array->len>0) g_array_remove_range(array,0,array->len)

This macro removes all elements in array.

Parameters:

array

GArray to be processed.

#define G_PTR_ARRAY_REMOVE_ALL

(

array

)

if (array->len>0) g_ptr_array_remove_range(array,0,array->len)

This macro removes all elements in array.

Parameters:

array

GPtrArray to be processed.

---

Typedef Documentation

typedef gboolean(* ForeachCallbackFunc)(gpointer data, gpointer userdata)

Parameters:

	data	The collection to be process.
	userdata	The other options for the callback function. Can be NULL.

Returns:

TRUE to continue; FALSE to break.

A prototype for callback functions that used with foreach functions.

---

Enumeration Type Documentation

enum ElementType

Specifying the element types of for collection has following benefits:

1. Easier type checking
2. Automatically assign the corresponding comparison functions.

See also:

HashSet

Enumerator:

ELEMENTS_TYPE_INTEGER	Specify that collection elements are integers.
ELEMENTS_TYPE_STRING	Specify that collection elements are strings.
ELEMENTS_TYPE_POINTER	Specify that collection elements are pointers.
ELEMENTS_TYPE_CUSTOM	Specify that collection elements are user-defined type.

---

Function Documentation

GArray* g_array_copy	(	GArray *	dest,
		GArray *	src
	)

This function copies the elements from src to dest. The old elements in dest will be removed by G_ARRAY_REMOVE_ALL(). Note that if src is NULL, content of dest will be freed.

Parameters:

	dest	GArray to be copied to.
	src	GArray to be copied to.

Returns:

The GArray dest.

int g_array_find	(	GArray *	array,
		gpointer	element,
		gint	elementSize,
		GCompareFunc	func
	)

This function uses func, A GCompareFunc to compare and find an element in array. The prototype of GCompareFunc is: int (*GCompareFunc) (gconstpointer a, gconstpointer b)

Note that it finds whether the content of element is in the array .

Parameters:

	array	The array to be processed.
	element	The element to be found.
	elementSize	The number of bytes which the content of element occupies.
	func	The GCompareFunc that compar

Returns:

index of the element in the array; -1 if such element cannot be found.

gboolean hashSet_add_element	(	HashSet *	hashSet,
		gpointer	element
	)

Add an element to hashSet, if it does not yet have an identical element. Note that this function only copies the pointer of element, not the content. So try not free the space that the element points to until element is removed from hashSet.

Parameters:

	hashSet	The HashSet to be processed.
	element	The element to be added.

Returns:

TRUE if the element has been added, FALSE if element has not been added because an identical element exists.

void hashSet_copy	(	HashSet *	dest,
		HashSet *	src
	)

This function copies the elements from src to dest. The old elements in dest will be removed by hashSet_remove_all().

Parameters:

	dest	The HashSet to be copied to.
	src	The HashSet to be copied from.

void hashSet_destroy

(

HashSet *

hashSet

)

Parameters:

hashSet

The HashSet to be processed.

guint hashSet_get_size

(

HashSet *

hashSet

)

This function gets the number of elements in the HashSet.

Parameters:

hashSet

The HashSet to be processed.

Returns:

Number of elements in the HashSet.

gboolean hashSet_has_element	(	HashSet *	hashSet,
		gconstpointer	element
	)

This function determines whether a element is in the HashSet.

Parameters:

	hashSet	The HashSet to be processed.
	element	The element to be found.

Returns:

TRUE if element is in hashSet ; FALSE otherwise.

void hashSet_intersect	(	HashSet *	result,
		HashSet *	hashSet1,
		HashSet *	hashSet2
	)

This function performs a set intersect operation on hashSet1 and hashSet2, and put the result set in result. The set result can be either hashSet1, hashSet2 or another HashSet, but cannot be NULL.

Parameters:

	hashSet1	The HashSet to be processed.
	hashSet2	The HashSet to be processed.
	result	The HashSet that holds the result.

HashSet* hashSet_new	(	ElementType	type,
		GHashFunc	hash_func,
		GEqualFunc	element_equal_func
	)

This function returns a new HashSet. It is actually hashSet_new_full(type,hash_func,element_equal_func,NULL).

Parameters:

	type	ElementType.
	hash_func	GHashFunc callback function for computing hash.
	element_equal_func	GEqualFunc callback function for comparing two keys.

Returns:

a new HashSet instance.

See also:

hashSet_new_default()

hashSet_new_full()

HashSet* hashSet_new_default

(

ElementType

type

)

This function returns a new HashSet with default handling functions. Specifically:

ElementType	hash_func	element_equal_func	element_destroy_func	value_destroy_func
ELEMENTS_TYPE_INTEGER	g_int_hash()	g_int_equal()	NULL	NULL
ELEMENTS_TYPE_STRING	g_str_hash()	g_str_equal()	NULL	NULL
ELEMENTS_TYPE_POINTER	g_direct_hash()	g_direct_equal()	NULL	NULL
ELEMENTS_TYPE_CUSTOM	NULL	NULL	NULL	NULL

Note that no default handler functions are associated with element type ELEMENTS_TYPE_CUSTOM, please use hashSet_new() or hashSet_new_full() instead.

Parameters:

type

ElementType.

Returns:

a new HashSet instance.

See also:

hashSet_new()

hashSet_new_full()

HashSet* hashSet_new_full	(	ElementType	type,
		GHashFunc	hash_func,
		GEqualFunc	element_equal_func,
		GDestroyNotify	element_destroy_func
	)

This function returns a new HashSet, while specifying element destroy function. It passes to GHashTable as g_hash_table_new_full(hash_func,element_equal_func,element_destroy_func,NULL).

Parameters:

	type	ElementType.
	hash_func	GHashFunc callback function for computing hash.
	element_equal_func	GEqualFunc callback function for comparing two keys.
	element_destroy_func	GGDestroyNotify callback function that free the element storage.

Returns:

a new HashSet instance.

See also:

hashSet_new_default()

hashSet_new()

void hashSet_remove_all

(

HashSet *

hashSet

)

This function removes all elements in hashSet. If element_destroy_func is supplied when s is created, it will be executed to free the elements.

Parameters:

hashSet

The HashSet to be processed.

See also:

hashSet_remove_element()

hashSet_steal_all()

hashSet_steal_element()

gboolean hashSet_remove_element	(	HashSet *	hashSet,
		gconstpointer	element
	)

Remove an element from hashSet. Note that the element_destroy_func will be executed if it was given when constructing hashSet, otherwise, only the pointer element will be removed, not the content.

Parameters:

	hashSet	The HashSet to be processed.
	element	The element to be removed.

Returns:

TRUE if the element was found and removed. FALSE otherwise.

See also:

hashSet_remove_all()

hashSet_steal_all()

hashSet_steal_element()

void hashSet_steal_all

(

HashSet *

hashSet

)

This function "steals" all elements from hashSet by removing all the element from it, but not free the content that the elements point to, in spite of whether the element_destroy_func is given or not.

Parameters:

hashSet

The HashSet to be processed.

See also:

hashSet_remove_all()

hashSet_remove_element()

hashSet_steal_element()

gboolean hashSet_steal_element	(	HashSet *	hashSet,
		gconstpointer	element
	)

This function "steals" an element from hashSet by removing element from it, but not free the content that element points to, in spite of whether the element_destroy_func is given or not.

Parameters:

	hashSet	The HashSet to be processed.
	element	The element to be removed.

Returns:

TRUE if the element was found and removed. FALSE otherwise.

See also:

hashSet_remove_all()

hashSet_remove_element()

hashSet_steal_all()

char* hashSet_to_string

(

HashSet *

hashSet

)

This function produces a string representation of the HashSet. The output formats are like (in printf() format):

• ELEMENTS_TYPE_INTEGER: [ d d d ... ]
• ELEMENTS_TYPE_STRING: [ s s s ... ]
• ELEMENTS_TYPE_POINTER: [ p p p ... ]
• ELEMENTS_TYPE_CUSTOM: [ p p p ... ]

The return string is new allocated, use free() or g_free() to free it.

Parameters:

hashSet

The HashSet to be processed.

Returns:

a newly allocated string which represents the content of result The HashSet that holds the result.

void hashSet_union	(	HashSet *	result,
		HashSet *	hashSet1,
		HashSet *	hashSet2
	)

This function performs a set union operation on hashSet1 and hashSet2, and put the result set in result. The set result can be either hashSet1, hashSet2 or another HashSet, but cannot be NULL.

Parameters:

	hashSet1	The HashSet to be processed.
	hashSet2	The HashSet to be processed.
	result	The HashSet that holds the result.

int integer_compareFunc	(	gconstpointer	a,
		gconstpointer	b
	)

Parameters:

	a	pointer to an integer.
	b	pointer to another integer.

Returns:

negative value if value of a < b; zero if value of a = b; positive value if value of a > b.