libcollection  0.6.0
Modules | Functions
Item management

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. More...
 
int col_get_item_type (struct collection_item *ci)
 Get item type. More...
 
int col_get_item_length (struct collection_item *ci)
 Get value length from the item. More...
 
void * col_get_item_data (struct collection_item *ci)
 Get value from the item. More...
 
uint64_t col_get_item_hash (struct collection_item *ci)
 Get hash value from the item. More...
 
uint64_t col_make_hash (const char *string, int sub_len, int *length)
 Calculate hash value for a string. More...
 
int col_compare_items (struct collection_item *first, struct collection_item *second, unsigned in_flags, unsigned *out_flags)
 Compare two items. More...
 
int col_modify_item (struct collection_item *item, const char *property, int type, const void *data, int length)
 Modify any item element. More...
 
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. More...
 
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. More...
 
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. More...
 
int col_remove_item_with_cb (struct collection_item *ci, const char *subcollection, int disposition, const char *refprop, int idx, int type, col_item_cleanup_fn cb, void *custom_data)
 Remove item from the collection. More...
 
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. More...
 
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. More...
 
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. More...
 
void col_delete_item (struct collection_item *item)
 Delete extracted item. More...
 
void col_delete_item_with_cb (struct collection_item *item, col_item_cleanup_fn cb, void *custom_data)
 Delete extracted item with callback. More...
 

Detailed Description

Group of functions that allows retrieving individual elements of the collection_item hiding the internal implementation.

Function Documentation

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.

Parameters
[in]ciItem to get property from. If item is invalid the function will cause a segment violation.
[out]property_lenIf not NULL the variable will receive the length of the property not counting terminating 0.
Returns
Property name.
int col_get_item_type ( struct collection_item ci)

Get item type.

Get type from the item.

Parameters
[in]ciItem to get type from. If item is invalid the function will cause a segment violation.
Returns
Item type.
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.

Parameters
[in]ciItem to get value length from. If item is invalid the function will cause a segment violation.
Returns
Value length.
void* col_get_item_data ( struct collection_item ci)

Get value from the item.

Get value from the item.

Parameters
[in]ciItem to get value from. If item is invalid the function will cause a segment violation.
Returns
Property value.
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.

Parameters
[in]ciItem to get hash from. If item is invalid the function will cause a segment violation.
Returns
Hash value.
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.

Parameters
[in]stringString to hash. If NULL hash is 0.
[in]sub_lenIf 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]lengthWill receive the calculated length of the provided string. Length argument can be NULL.
Returns
Hash value.
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.

Parameters
[in]firstFirst item to compare.
[in]secondSecond item to compare.
[in]in_flagsSee comparison flags.
[out]out_flagsSee output flags.
Returns
0 if items are the same and nonzero otherwise.
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 the item is a reference or a collection and you attempt to change the data, i.e. length is not 0, the call will return an error EINVAL. If the item is a reference or a collection it can only be renamed.

The are several convenience function that are wrappers around this function. For more information see item modification wrappers.

Parameters
[in]itemItem to modify.
[in]propertyProperty name. Use NULL to leave the property unchanged.
[in]typeSee types for more information.
[in]dataNew value.
[in]lengthNew value. Use 0 to leave the value and its type unchanged.
Returns
0 - Item was successfully modified.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid. The attempt to modify an item which is a reference to a collection or a collection name.
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.

Parameters
[in]ciCollection object.
[in]subcollectionName 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]dispositionConstant that controls how the relative position of the item to extract is determined. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to extract. Useful for multi-value properties where several properties have same name in a row.
[in]typeType 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_refVariable will receive the value of the pointer to the extracted item.
Returns
0 - Item was successfully extracted.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example extracting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
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.

Parameters
[in]ciCollection object.
[in]dispositionConstant that controls how the relative position of the item to extract is determined. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to extract. Useful for multi-value properties where several properties have same name in a row.
[in]typeType 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_refVariable will receive the value of the pointer to the extracted item.
Returns
0 - Item was successfully extracted.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example extracting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
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.

Parameters
[in]ciCollection object.
[in]subcollectionName 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]dispositionConstant that controls how the relative position of the item to remove is determined. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to remove. Useful for multi-value properties where several properties have same name in a row.
[in]typeType 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.
Returns
0 - Item was successfully removed.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example deleting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
int col_remove_item_with_cb ( struct collection_item ci,
const char *  subcollection,
int  disposition,
const char *  refprop,
int  idx,
int  type,
col_item_cleanup_fn  cb,
void *  custom_data 
)

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.

Parameters
[in]ciCollection object.
[in]subcollectionName 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]dispositionConstant that controls how the relative position of the item to remove is determined. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to remove. Useful for multi-value properties where several properties have same name in a row.
[in]typeType 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.
[in]cbCallback to use.
[in]custom_dataCaller defined data that can be passed to the callback.
Returns
0 - Item was successfully removed.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example deleting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
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.

Parameters
[in]ciCollection object.
[in]dispositionConstant that controls how the relative position of the item to remove is determined. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to remove. Useful for multi-value properties where several properties have same name in a row.
[in]typeType 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.
Returns
0 - Item was successfully removed.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example deleting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
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:

  • a) Insert this item into another (or same) collection
  • b) Get item information using corresponding item management functions.
  • c) Destroy item using col_delete_item().

You are required to do either a) or c) with such item.

Parameters
[in]ciCollection object.
[in]subcollectionName 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]itemItem to insert.
[in]dispositionConstant that controls where to insert the item. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to insert. Useful for multi-value properties where several properties have same name in a row.
[in]flagsFlags that control naming issues. See insert flags for more details.
Returns
0 - Item was successfully extracted.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example extracting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
EEXIST If duplicate name/type checking is turned on and duplicate name/type is detected.
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.

Parameters
[in]ciCollection object.
[in]itemItem to insert.
[in]dispositionConstant that controls where to insert the item. For more information see disposition constants.
[in]refpropName 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]idxIndex of the property to insert. Useful for multi-value properties where several properties have same name in a row.
[in]flagsFlags that control naming issues. See insert flags for more details.
Returns
0 - Item was successfully extracted.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
ENOENT - Sub collection is not found. The position can't be determined. For example extracting next item after item with name "foo" will cause this error if item "foo" is the last item in the collection. There are other cases when this error can be returned but the common theme is that something was not found.
ENOSYS Unknown disposition value.
EEXIST If duplicate name/type checking is turned on and duplicate name/type is detected.
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.

Parameters
[in]itemItem to delete.
void col_delete_item_with_cb ( struct collection_item item,
col_item_cleanup_fn  cb,
void *  custom_data 
)

Delete extracted item with callback.

This function is similar to col_delete_item but allows passing a callback function so that value stored in the collection can be properly distroyed.

Parameters
[in]itemItem to delete.
[in]cbCallback to use.
[in]custom_dataCaller defined data that can be passed to the callback.