libcollection
0.6.1
|
Data Structures | |
struct | collection_item |
Opaque structure that holds one property. More... | |
struct | collection_iterator |
Opaque iterator structure. More... | |
Macros | |
#define | COL_CLASS_DEFAULT 0 |
Default class for a free form collection. | |
#define | COL_NOMATCH 0 |
Value indicates that property is not found. More... | |
#define | COL_MATCH 1 |
Value indicates that property is found. More... | |
Typedefs | |
typedef void(* | col_item_cleanup_fn) (const char *property, int property_len, int type, void *data, int length, void *custom_data) |
Cleanup Callback. More... | |
typedef int(* | col_copy_cb) (struct collection_item *item, void *ext_data, int *skip) |
Copy item callback. More... | |
typedef int(* | col_item_fn) (const char *property, int property_len, int type, void *data, int length, void *custom_data, int *stop) |
Search Callback. More... | |
Functions | |
int | col_create_collection (struct collection_item **ci, const char *name, unsigned cclass) |
Create a collection. More... | |
void | col_destroy_collection (struct collection_item *ci) |
Destroy a collection. More... | |
void | col_destroy_collection_with_cb (struct collection_item *ci, col_item_cleanup_fn cb, void *custom_data) |
Destroy a collection with callback. More... | |
int | col_copy_collection_with_cb (struct collection_item **col_copy, struct collection_item *col_to_copy, const char *name_to_use, int copy_mode, col_copy_cb copy_cb, void *ext_data) |
Copy collection with data modification. More... | |
int | col_copy_collection (struct collection_item **col_copy, struct collection_item *col_to_copy, const char *name_to_use, int copy_mode) |
Copy collection without data modification. More... | |
int | col_add_collection_to_collection (struct collection_item *ci, const char *subcollection, const char *as_property, struct collection_item *ci_to_add, int mode) |
Add collection to collection. More... | |
int | col_traverse_collection (struct collection_item *ci, int mode_flags, col_item_fn item_handler, void *custom_data) |
Traverse collection. More... | |
int | col_get_item_and_do (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, col_item_fn item_handler, void *custom_data) |
Search and do function. More... | |
int | col_get_item (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, struct collection_item **item) |
Search function to get an item. More... | |
int | col_get_dup_item (struct collection_item *ci, const char *subcollection, const char *property_to_find, int type, int idx, int exact, struct collection_item **item) |
Search function to get one of the duplicate items. More... | |
int | col_sort_collection (struct collection_item *col, unsigned cmp_flags, unsigned sort_flags) |
Sort collection. More... | |
int | col_delete_property (struct collection_item *ci, const char *property_to_find, int type, int mode_flags) |
Delete property. More... | |
int | col_is_item_in_collection (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, int *found) |
Is property in the collection? More... | |
int | col_get_collection_reference (struct collection_item *ci, struct collection_item **acceptor, const char *col_to_find) |
Get a reference to a collection. More... | |
int | col_get_reference_from_item (struct collection_item *item, struct collection_item **acceptor) |
Get a reference from the item. More... | |
int | col_get_collection_class (struct collection_item *ci, unsigned *cclass) |
Get collection class. More... | |
int | col_set_collection_class (struct collection_item *ci, unsigned cclass) |
Set collection class. More... | |
int | col_get_collection_count (struct collection_item *ci, unsigned *count) |
Get count of the elements. More... | |
int | col_is_of_class (struct collection_item *ci, unsigned cclass) |
Check the class of collection. More... | |
#define COL_NOMATCH 0 |
Value indicates that property is not found.
Used in search functions.
#define COL_MATCH 1 |
Value indicates that property is found.
Used in search functions.
typedef void(* col_item_cleanup_fn) (const char *property, int property_len, int type, void *data, int length, void *custom_data) |
Cleanup Callback.
Signature of the callback that needs to be used when the collection is destroyed and a special cleanup operation is required for items in the collection.
[in] | property | The name of the property will be passed in this parameter. |
[in] | property_len | Length of the property name will be passed in this parameter. |
[in] | type | Type of the data will be passed in this parameter. |
[in] | data | Pointer to the data will be passed in this parameter. |
[in] | length | Length of data will be passed in this parameter. |
[in] | custom_data | Custom data will be passed in this parameter. |
typedef int(* col_copy_cb) (struct collection_item *item, void *ext_data, int *skip) |
Copy item callback.
Callback is used by the col_copy_collection_with_cb function. Function is called after the new item is created but not yet inserted into the target collection. The implementer of the callback can alter the item data or indicate to the caller that the item should be skipped.
[in] | item | Newly allocated item that will be inserted into the new collection. |
[in] | ext_data | Data the application might want to pass to the callback. |
[out] | skip | Pointer to a variable that indicates if the item should be skipped or not. Set this variable to any nonzero value and the item will be skipped. |
typedef int(* col_item_fn) (const char *property, int property_len, int type, void *data, int length, void *custom_data, int *stop) |
Search Callback.
Signature of the callback that needs to be used when traversing a collection or looking for a specific item.
[in] | property | The name of the property will be passed in this parameter. |
[in] | property_len | Length of the property name will be passed in this parameter. |
[in] | type | Type of the data will be passed in this parameter. |
[in] | data | Pointer to the data will be passed in this parameter. |
[in] | length | Length of data will be passed in this parameter. |
[in] | custom_data | Custom data will be passed in this parameter. |
[out] | stop | Pointer to a variable where the handler can put nonzero to stop traversing of the collection. |
int col_create_collection | ( | struct collection_item ** | ci, |
const char * | name, | ||
unsigned | cclass | ||
) |
Create a collection.
The function will create a collection. Each collection should have name and class.
[out] | ci | Newly allocated collection object. |
[in] | name | The name is supposed to be a unique identifier of the collection. This is useful when the collections are stored within other collections or inside other aggregation objects. Caller is free to use any name. Name should consist of the ASCII characters with codes non less than space. Exclamation mark character is a special character and can't be used in name of collection or property. Maximum allowed length is defined at compile time. The default value is 64k. |
[in] | cclass | Class is used to relate the collection to a specific group of the collections of the same structure. This is very useful when you try to represent objects using collections and you want to check if the objects have same structure or not. There is no predefined name space for the collection classes. Defining classes is left to the application developers. NOTE: If you decide to build an interface using collection library pick a range for the classes you are going to use and make sure that they do not collide with other interfaces built on top of the collection. |
void col_destroy_collection | ( | struct collection_item * | ci | ) |
Destroy a collection.
The function will destroy a collection.
[in] | ci | Collection object. |
void col_destroy_collection_with_cb | ( | struct collection_item * | ci, |
col_item_cleanup_fn | cb, | ||
void * | custom_data | ||
) |
Destroy a collection with callback.
Execute a provided callback for each item in the collection or subcollection immediately before freeing item. The callback is executed for each element including the collection header. It is the responsibility of the callback implementor to properly handle gifferent collection elements depending upon whether it is a header, reference to an embedded or external collection or a normal data element.
The function will destroy a collection.
[in] | ci | Collection object. |
[in] | cb | Cleanup callback. |
[in] | custom_data | Application data passed into the cleanup callback. |
int col_copy_collection_with_cb | ( | struct collection_item ** | col_copy, |
struct collection_item * | col_to_copy, | ||
const char * | name_to_use, | ||
int | copy_mode, | ||
col_copy_cb | copy_cb, | ||
void * | ext_data | ||
) |
Copy collection with data modification.
Function create a deep copy of the current collection. Calls caller provided callback before copying each item's data. This is useful if the data needs to be resolved in some way. The best use is when the template is copied and the values in the template are resolved to the actual values. The acceptable modes are defined here.
[out] | col_copy | Newly created collection object. |
[in] | col_to_copy | Collection object that will be copied. |
[in] | name_to_use | Name of the new collection. |
[in] | copy_mode | How to copy. |
[in] | copy_cb | Pointer to a callback col_copy_cb. Can be NULL. In this case data is copied without modification. |
[in] | ext_data | Data the application might want to pass to the callback. |
int col_copy_collection | ( | struct collection_item ** | col_copy, |
struct collection_item * | col_to_copy, | ||
const char * | name_to_use, | ||
int | copy_mode | ||
) |
Copy collection without data modification.
Function creates a deep copy of the current collection. It wraps the col_copy_collection_with_cb function. The acceptable modes are defined here.
[out] | col_copy | Newly created collection object. |
[in] | col_to_copy | Collection object that will be copied. |
[in] | name_to_use | Name of the new collection. |
[in] | copy_mode | How to copy. |
int col_add_collection_to_collection | ( | struct collection_item * | ci, |
const char * | subcollection, | ||
const char * | as_property, | ||
struct collection_item * | ci_to_add, | ||
int | mode | ||
) |
Add collection to collection.
Function adds one collection into another depending upon a specified mode.
[in] | ci | Root collection object. |
[in] | subcollection | Name of the inner collection to add collection to. If NULL the collection is added to the root collection. |
[in] | as_property | Name of the property that will constitute the reference. If NULL the name of the collection being added will be used. If specified the restrictions to the name characters and length apply. For more details about the name related restrictions see col_add_xxx_property functions. |
[in] | ci_to_add | Collection to add. |
[in] | mode | Specifies how the collection should be added. |
int col_traverse_collection | ( | struct collection_item * | ci, |
int | mode_flags, | ||
col_item_fn | item_handler, | ||
void * | custom_data | ||
) |
Traverse collection.
Function to traverse the entire collection including (optionally) sub collections.
[in] | ci | Collection object to traverse. |
[in] | mode_flags | How to traverse. See details here. |
[in] | item_handler | Application supplied callback. It will be called for each item in the collection including headers. |
[in] | custom_data | Custom data that application might want to pass to the callback. |
int col_get_item_and_do | ( | struct collection_item * | ci, |
const char * | property_to_find, | ||
int | type, | ||
int | mode_flags, | ||
col_item_fn | item_handler, | ||
void * | custom_data | ||
) |
Search and do function.
Looks up an item in the collection based on the property and type. Actually it is a traverse function with special traversing logic. It traverses the whole collection but calls the supplied callback only for the items that match the search criteria. It is the responsibility of the caller to define how the callback is going to indicate that the item it was looking for is found. Function will not return error if the item is not found. It is the responsibility of the calling application to check the data passed in custom_data and see if the item was found and that the action was performed.
[in] | ci | Collection object to traverse. |
[in] | property_to_find | Name of the property to find. Parameter supports "x!y" notation. |
[in] | type | Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated. |
[in] | mode_flags | How to traverse the collection. See details here. |
[in] | item_handler | Function to call when the item is found. |
[in] | custom_data | Custom data passed to the callback. |
int col_get_item | ( | struct collection_item * | ci, |
const char * | property_to_find, | ||
int | type, | ||
int | mode_flags, | ||
struct collection_item ** | item | ||
) |
Search function to get an item.
Convenience function to get individual item. Caller should be aware that this is not a copy of the item but the pointer to actual item stored in the collection. The returned pointer should never be altered or freed by caller of the function. The caller should be sure that the collection does not go out of scope while the pointer to its data is in use. Working with the internals of the collection item structure directly may cause problems in future if the internal implementation changes. The caller needs to be aware that function does not return error if item is not found. The caller needs to check if item is not NULL to determine whether something was found. Internally function is a wrapper around the col_get_item_and_do function.
Use item management functions to work with the item.
[in] | ci | Collection object to traverse. |
[in] | property_to_find | Name of the property to find. Parameter supports "x!y" notation. |
[in] | type | Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated. |
[in] | mode_flags | How to traverse the collection. See details here. |
[in] | item | Pointer to found item or NULL if item is not found. |
int col_get_dup_item | ( | struct collection_item * | ci, |
const char * | subcollection, | ||
const char * | property_to_find, | ||
int | type, | ||
int | idx, | ||
int | exact, | ||
struct collection_item ** | item | ||
) |
Search function to get one of the duplicate items.
Convenience function to get an individual item out of the list of duplicates. Caller should be aware that this is not a copy of the item but the pointer to actual item stored in the collection. The returned pointer should never be altered or freed by caller of the function. The caller should be sure that the collection does not go out of scope while the pointer to its data is in use. Working with the internals of the collection item structure directly may cause problems in future if the internal implementation changes. If collection to search or property to find is NULL function returns NULL.
Use item management functions to work with the item.
[in] | ci | Collection object to traverse. |
[in] | subcollection | Name of the sub collection to find item in. If NULL, the top level collection is used. One can use "foo!bar!baz" notation to identify the sub collection. |
[in] | property_to_find | Name of the property to find. |
[in] | type | Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated. |
[in] | idx | Index of the duplicate to find. 0 - any first instance positive - N-th instance (index is 0-based) negative - last instance |
[in] | exact | If 0 then if index above is greater than actual number of duplicates the last duplicate if be returned. If non-zero the funtion will return ENOENT in case the index is greater than actual number of duplicates. |
[out] | item | Pointer to found item or NULL if item is not found. |
int col_sort_collection | ( | struct collection_item * | col, |
unsigned | cmp_flags, | ||
unsigned | sort_flags | ||
) |
Sort collection.
If the sub collections are included in sorting each collection is sorted separately (this is not a global sort). It might be dangerous to sort sub collections if sub collection is not owned by the current collection. If it is a reference to an external collection there might be an issue. To skip the collections that externally referenced use COL_SORT_MYSUB flag. Keep in mind that if a collection is referenced more than once by other collection and that collection is sorted with sub collections the referenced collection will be sorted more than once.
NOTE: Current implementation of the sorting function is very simple and alternative implementations might be provided later.
[in] | col | Collection to sort. |
[in] | cmp_flags | For more information see comparison flags. |
[in] | sort_flags | For more information see sort flags. |
int col_delete_property | ( | struct collection_item * | ci, |
const char * | property_to_find, | ||
int | type, | ||
int | mode_flags | ||
) |
Delete property.
Delete property from the collection. It is recommended to use a more efficient function col_remove_item for the same purpose if the property is unique or if the collection has a known structure. The col_delete_property function has some advantage only if it is not known where property resides and what is the structure of the collection. In this case "foo!bar!baz" notation can be used in the property_to_find argument to find and delete the property "baz" that is in a sub collection "bar" which is in turn a part of a collection "foo".
[in] | ci | Collection to delete property from. |
[in] | property_to_find | Property to delete. |
[in] | type | Use type if names are not unique and you know the type of the value you want to delete. Otherwise set to 0. |
[in] | mode_flags | The flags define how the collection should be searched. For more information see traverse constants. |
int col_is_item_in_collection | ( | struct collection_item * | ci, |
const char * | property_to_find, | ||
int | type, | ||
int | mode_flags, | ||
int * | found | ||
) |
Is property in the collection?
Convenience function to check if the property is indeed in the collection.
[in] | ci | Collection to search. |
[in] | property_to_find | Property to find. |
[in] | type | Use type if names are not unique and you know the type of the value you want to check. Otherwise set to 0. |
[in] | mode_flags | The flags define how the collection should be searched. For more information see traverse constants. |
[out] | found | The variable that will receive the result of the search. COL_NOMATCH - if not found COL_MATCH if found |
int col_get_collection_reference | ( | struct collection_item * | ci, |
struct collection_item ** | acceptor, | ||
const char * | col_to_find | ||
) |
Get a reference to a collection.
Get a pointer to a collection included into another collection. If the col_to_find is NULL function returns a reference to the top level collection. Delete extracted collection after use to decrease reference count.
[in] | ci | Collection to search. |
[out] | acceptor | Variable that accepts pointer to an extracted collection. Use col_destroy_collection to free returned object reference after use. |
[in] | col_to_find | Collection to find. "foo!bar!baz" notation can be used. |
int col_get_reference_from_item | ( | struct collection_item * | item, |
struct collection_item ** | acceptor | ||
) |
Get a reference from the item.
Get a pointer to a collection from a current item if current item is a reference to the collection. If current item is not a reference to a collection an error will be returned. Delete extracted collection after use to decrease reference count.
[in] | item | Item to extract the reference from. |
[out] | acceptor | Variable that accepts pointer to an extracted collection. Use col_destroy_collection to free returned object reference after use. |
int col_get_collection_class | ( | struct collection_item * | ci, |
unsigned * | cclass | ||
) |
Get collection class.
The classes of the collections can be used to convey information about the collection's internal structure. Some interfaces built on top of the collection might impose restrictions on the collection structure. For example the interface can decide that it is going to deal with the collections that do not have sub collections and elements of the collections are always only strings. So the interface will define a class of the collection and create a function that would take the strings and create such a collection. Then other functions of that interface would check if the provided collection is of the specified class. If not the interface would reject the collection right away. If the collection is of the valid class the interface might call the validation function to make sure that this is really the case however it needs to validate it only once and lower level functions can rely on the class value of the collection without performing duplicate validation.
[in] | ci | Collection object. |
[out] | cclass | Variable that will receive the value of the class. |
int col_set_collection_class | ( | struct collection_item * | ci, |
unsigned | cclass | ||
) |
Set collection class.
Sometimes as a result of the collection modification the class of the collection can change.
[in] | ci | Collection object. |
[in] | cclass | New class value. |
int col_get_collection_count | ( | struct collection_item * | ci, |
unsigned * | count | ||
) |
Get count of the elements.
It is useful to know how many items are there in the collection.
[in] | ci | Collection object. |
[out] | count | Variable will receive the value of the number of the items in the collection. Collection header or references to external collections are counted as well. This means that every collection has at least one item - the header. |
int col_is_of_class | ( | struct collection_item * | ci, |
unsigned | cclass | ||
) |
Check the class of collection.
Convenience function to check if the collection is of the specific class. In case of internal error assumes that collection is not of the right class.
[in] | ci | Collection object. |
[in] | cclass | Class value to compare to to. |