Modules | |
Comparison flags | |
Comparison results flags | |
Disposition constants | |
Flags used in insert item functions | |
Item modification wrappers | |
Functions | |
const char * | col_get_item_property (struct collection_item *ci, int *property_len) |
Get item property. | |
int | col_get_item_type (struct collection_item *ci) |
Get item type. | |
int | col_get_item_length (struct collection_item *ci) |
Get value length from the item. | |
void * | col_get_item_data (struct collection_item *ci) |
Get property value from the item. | |
uint64_t | col_get_item_hash (struct collection_item *ci) |
Get hash value from the item. | |
uint64_t | col_make_hash (const char *string, int sub_len, int *length) |
Calculate hash value for a string. | |
int | col_compare_items (struct collection_item *first, struct collection_item *second, unsigned in_flags, unsigned *out_flags) |
Compare two items. | |
int | col_modify_item (struct collection_item *item, const char *property, int type, const void *data, int length) |
Modify any item element. | |
int | col_extract_item (struct collection_item *ci, const char *subcollection, int disposition, const char *refprop, int idx, int type, struct collection_item **ret_ref) |
Extract item from the collection. | |
int | col_extract_item_from_current (struct collection_item *ci, int disposition, const char *refprop, int idx, int type, struct collection_item **ret_ref) |
Extract item from the current collection. | |
int | col_remove_item (struct collection_item *ci, const char *subcollection, int disposition, const char *refprop, int idx, int type) |
Remove item from the collection. | |
int | col_remove_item_from_current (struct collection_item *ci, int disposition, const char *refprop, int idx, int type) |
Remove item from the current collection. | |
int | col_insert_item (struct collection_item *ci, const char *subcollection, struct collection_item *item, int disposition, const char *refprop, int idx, unsigned flags) |
Insert item to the collection. | |
int | col_insert_item_into_current (struct collection_item *ci, struct collection_item *item, int disposition, const char *refprop, int idx, unsigned flags) |
Insert item to the current collection. | |
void | col_delete_item (struct collection_item *item) |
Delete extracted item. |
Group of functions that allows retrieving individual elements of the collection_item hiding the internal implementation.
int col_compare_items | ( | struct collection_item * | first, | |
struct collection_item * | second, | |||
unsigned | in_flags, | |||
unsigned * | out_flags | |||
) |
Compare two items.
The second item is evaluated against the first. Function returns 0 if two items are the same and non-zero otherwise. The in_flags is a bit mask that defines how the items should be compared.
If items are different they might be sorted following some order. For example one can order items by name but not by type. If the result of the function is non-zero the out_flags (if provided) will be set to indicate if the second item is greater then the first.
[in] | first | First item to compare. |
[in] | second | Second item to compare. |
[in] | in_flags | See comparison flags. |
[out] | out_flags | See output flags. |
void col_delete_item | ( | struct collection_item * | item | ) |
Delete extracted item.
NEVER use this function to delete an item that was not previously extracted from the collection.
There is currently no function to create an item aside and then insert it into the collection so the col_delete_item has only one use. In future this may change.
[in] | item | Item to delete. |
int col_extract_item | ( | struct collection_item * | ci, | |
const char * | subcollection, | |||
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
int | type, | |||
struct collection_item ** | ret_ref | |||
) |
Extract item from the collection.
Function to find and remove an item from the collection. Function does not destroy the item instead it returns a reference to the item so it can be used later and inserted back into this or other collection. The function assumes that the caller knows the collection the property is stored in. The header of the collection can't be extracted with this function but the reference to the collection can.
Function allows specifying relative position of the item in the collection. One can specify that he wants to extract an item that is first in the collection or last, or after other item in the collection. For more details see parameter definitions.
After extracting the item from the collection the caller has to either insert it back into some collection using col_insert_item or delete it using col_delete_item.
[in] | ci | Collection object. |
[in] | subcollection | Name of the sub collection to extract item from. If NULL, the top level collection is used. One can use "foo!bar!baz" notation to identify the sub collection. |
[in] | disposition | Constant that controls how the relative position of the item to extract is determined. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should extract next item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to extract. Useful for multi-value properties where several properties have same name in a row. |
[in] | type | Type filter. Only the item of the matching type will be used. It can be a bit mask of more than one type. Use 0 if you do not need to filter by type. |
[out] | ret_ref | Variable will receive the value of the pointer to the extracted item. |
int col_extract_item_from_current | ( | struct collection_item * | ci, | |
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
int | type, | |||
struct collection_item ** | ret_ref | |||
) |
Extract item from the current collection.
Function is similar to the col_extract_item. It acts exactly the same as col_extract_item when the subcollection parameter of the col_extract_item is set to NULL.
[in] | ci | Collection object. |
[in] | disposition | Constant that controls how the relative position of the item to extract is determined. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should extract next item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to extract. Useful for multi-value properties where several properties have same name in a row. |
[in] | type | Type filter. Only the item of the matching type will be used. It can be a bit mask of more than one type. Use 0 if you do not need to filter by type. |
[out] | ret_ref | Variable will receive the value of the pointer to the extracted item. |
void* col_get_item_data | ( | struct collection_item * | ci | ) |
Get property value from the item.
Get property value from the item.
[in] | ci | Item to get value from. If item is invalid the function will cause a segment violation. |
uint64_t col_get_item_hash | ( | struct collection_item * | ci | ) |
Get hash value from the item.
Get hash value from the item. The hash value is 64-bit hash created from the property name. It is done to optimize the searches.
This function is exposed for some corner cases that require low level operations, for example for custom search callbacks to take advantage of the internal hashes.
[in] | ci | Item to get hash from. If item is invalid the function will cause a segment violation. |
int col_get_item_length | ( | struct collection_item * | ci | ) |
Get value length from the item.
Get value length from the item. For strings this includes NULL terminating zero.
[in] | ci | Item to get value length from. If item is invalid the function will cause a segment violation. |
const char* col_get_item_property | ( | struct collection_item * | ci, | |
int * | property_len | |||
) |
Get item property.
Get name of the property from the item. If the item is a header the name of the property is the name of the collection. The element that denotes the collection header has type COL_TYPE_COLLECTION. Optionally the property length can be retrieved too.
[in] | ci | Item to get property from. If item is invalid the function will cause a segment violation. |
[out] | property_len | If not NULL the variable will receive the length of the property not counting terminating 0. |
int col_get_item_type | ( | struct collection_item * | ci | ) |
Get item type.
Get type from the item.
[in] | ci | Item to get type from. If item is invalid the function will cause a segment violation. |
int col_insert_item | ( | struct collection_item * | ci, | |
const char * | subcollection, | |||
struct collection_item * | item, | |||
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
unsigned | flags | |||
) |
Insert item to the collection.
WARNING: Only use this function to insert items that were extracted using col_extract_item or col_extract_item_from_current. NEVER use it with items that were returned by:
The fundamental difference is that when you extracted item using col_extract_item() it stops to be managed by a collection. With such item you can:
You are required to do either a) or c) with such item.
[in] | ci | Collection object. |
[in] | subcollection | Name of the sub collection to insert item into. If NULL, the top level collection is used. One can use "foo!bar!baz" notation to identify the sub collection. |
[in] | item | Item to insert. |
[in] | disposition | Constant that controls where to insert the item. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should insert the item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to insert. Useful for multi-value properties where several properties have same name in a row. |
[in] | flags | Flags that control naming issues. See insert flags for more details. |
int col_insert_item_into_current | ( | struct collection_item * | ci, | |
struct collection_item * | item, | |||
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
unsigned | flags | |||
) |
Insert item to the current collection.
Function is equivalent to col_insert_item with subcollection parameter equal NULL.
[in] | ci | Collection object. |
[in] | item | Item to insert. |
[in] | disposition | Constant that controls where to insert the item. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should insert the item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to insert. Useful for multi-value properties where several properties have same name in a row. |
[in] | flags | Flags that control naming issues. See insert flags for more details. |
uint64_t col_make_hash | ( | const char * | string, | |
int | sub_len, | |||
int * | length | |||
) |
Calculate hash value for a string.
Calculates hash value of the string using internal hashing algorithm. Populates "length" with length of the string not counting 0.
This function is useful if you want to build a custom search or collection sorting function.
[in] | string | String to hash. If NULL hash is 0. |
[in] | sub_len | If it is greater than zero it is used to count how many characters from string should be included into hash calculation. If 0 the actual length of the string is determined and used. |
[out] | length | Will receive the calculated length of the provided string. Length argument can be NULL. |
int col_modify_item | ( | struct collection_item * | item, | |
const char * | property, | |||
int | type, | |||
const void * | data, | |||
int | length | |||
) |
Modify any item element.
This function is useful if you want to modify the item that you got as a result of iterating through collection or by calling col_get_item. Previous type and data of the item is destroyed.
If you want to rename an item provide a new name in the property argument otherwise keep it NULL.
If you want the data to remain unchanged use 0 as a length parameter.
If item is a reference or a collection the call will return an error.
The are several convenience function that are wrappers around this function. For more information see item modification wrappers.
[in] | item | Item to modify. |
[in] | property | Property name. Use NULL to leave the property unchanged. |
[in] | type | See types for more information. |
[in] | data | New value. |
[in] | length | New value. Use 0 to leave the value and its type unchanged. |
int col_remove_item | ( | struct collection_item * | ci, | |
const char * | subcollection, | |||
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
int | type | |||
) |
Remove item from the collection.
Function internally calls col_extract_item and then col_delete_item for the extracted item.
Function is similar to col_delete_property function but allows more specific information about what item (property) to remove.
The header will not be considered for deletion.
[in] | ci | Collection object. |
[in] | subcollection | Name of the sub collection to remove item from. If NULL, the top level collection is used. One can use "foo!bar!baz" notation to identify the sub collection. |
[in] | disposition | Constant that controls how the relative position of the item to remove is determined. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should remove next item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to remove. Useful for multi-value properties where several properties have same name in a row. |
[in] | type | Type filter. Only the item of the matching type will be used. It can be a bit mask of more than one type. Use 0 if you do not need to filter by type. |
int col_remove_item_from_current | ( | struct collection_item * | ci, | |
int | disposition, | |||
const char * | refprop, | |||
int | idx, | |||
int | type | |||
) |
Remove item from the current collection.
Function is similar to the col_remove_item. It acts exactly the same as col_remove_item when the subcollection parameter of the col_remove_item is set to NULL.
[in] | ci | Collection object. |
[in] | disposition | Constant that controls how the relative position of the item to remove is determined. For more information see disposition constants. |
[in] | refprop | Name of the property to relate to. This can be used to specify that function should remove next item after the item with this name. Leave NULL if the disposition you are using does not relate to an item in the collection. |
[in] | idx | Index of the property to remove. Useful for multi-value properties where several properties have same name in a row. |
[in] | type | Type filter. Only the item of the matching type will be used. It can be a bit mask of more than one type. Use 0 if you do not need to filter by type. |