Vstr documentation -- functions |
Initialization function |
Function: vstr_exit()
Returns: Nothing Type: void |
Parameter[1]: Nothing Type[1]: void |
Explanation: |
This function can be called before exit, after all vstr objects have been freed, to cleanup data allocated internally in the vstr library. |
Note: |
The function isn't needed but helps make sure there are no memory leaks, when used with a memory checker. |
Functions to choose multiple VSTR_FLAG_* constants |
Function: VSTR_FLAGXX()
Returns: The value of the flags combined Type: unsigned int |
Parameter[1]: Name of flag type to use. Type[1]: <symbol> |
Parameter[ ... ]: Names of a flags in the given flag type Type[ ... ]: <symbol> |
Explanation: |
This isn't one macro function but a group of functions that all do the same
thing, just with different numbers of arguments. They combine the namespace
requirements so that you can specify multiple flags in a concise manner. For
instance VSTR_FLAG06() combines 6 flags. So instead of having to wite...
(VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_NUL | VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_BEL | VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_BS | VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_HT | VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_LF | VSTR_FLAG_CONV_UNPRINTABLE_ALLOW_VT)...you can write... VSTR_FLAG06(CONV_UNPRINTABLE_ALLOW, NUL, BEL, BS, HT, LF, VT)...which is a lot more readable as the number of flags increases. The Range of macro functions is from VSTR_FLAG01() to VSTR_FLAG31(), the number at the end refering to how many flags are passed to it (not the number of parameters, which is one more than that). |
Functions to get specific data about the vstr |
Function: vstr_num()
Returns: Number of nodes used in the vstr Type: unsigned int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Explanation: |
This function is used to find out how many nodes are being used for a given section of a vstr. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Functions to export vstr data |
Function: vstr_export_ref()
Returns: Vstr memory reference Type: struct Vstr_ref * |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr Type[2]: size_t |
Parameter[3]: Length from position in the Vstr Type[3]: size_t |
Parameter[4]: Offset of Vstr memory refernce (Return) Type[4]: size_t * |
Explanation: |
This function is used to return a pointer to a Vstr memory reference of at least length (Parameter[3]). The offset (Parameter[4]) should be used to find the beginning of the block of memory to use. When you are finnished with the reference you need to use vstr_ref_del() or the memory will stay allocated forever. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. The function will return NULL if it needs to allocate memory and cannot do so. |
Note: |
Any _NON data in the Vstr will be uninitialised data in the memory pointed to by the memory reference. |
Functions to use as callbacks in a Vstr memory reference |
Function: vstr_ref_cb_free_nothing()
Returns: Nothing Type: void |
Parameter[1]: Vstr memory reference Type[1]: struct Vstr_ref * |
Explanation: |
|
Function: vstr_ref_cb_free_ref()
Returns: Nothing Type: void |
Parameter[1]: Vstr memory reference Type[1]: struct Vstr_ref * |
Explanation: |
|
Function: vstr_ref_cb_free_ptr_ref()
Returns: Nothing Type: void |
Parameter[1]: Vstr memory reference Type[1]: struct Vstr_ref * |
Explanation: |
This will call free() on the data in the Vstr_ref (Parameter[1])->ptr and then call free() on the Vstr_ref (Parameter[1]). |
Functions to reference and dereference a Vstr memory reference |
Function: vstr_ref_del()
Returns: Type: void |
Parameter[1]: Vstr memory reference Type[1]: struct Vstr_ref * |
Explanation: |
This function will delete a reference count from the Vstr_ref (Parameter[1]), when the reference count reaches zero then the cleanup function will be called. |
Creation/destruction of core objects |
Function: vstr_make_conf()
Returns: Vstr configuration Type: struct Vstr_conf * |
Parameter[1]: Nothing Type[1]: void |
Explanation: |
This function will make a Vstr configuration, or return NULL. |
Function: vstr_make_base()
Returns: Vstr string Type: struct Vstr_base * |
Parameter[1]: Vstr configuration Type[1]: struct Vstr_conf * |
Parameter[2]: Type[2]: struct Vstr_conf * |
Explanation: |
|
Function: vstr_free_base()
Returns: Nothing Type: void |
Parameter[1]: Vstr string Type[1]: struct Vstr_base * |
Explanation: |
This function will free a Vstr string, allocated by vstr_make_base(). |
Function: vstr_free_spare_nodes()
Returns: Number of nodes destroyed Type: unsigned int |
Parameter[1]: Vstr configuration Type[1]: struct Vstr_conf * |
Parameter[2]: Type of nodes to destroy Type[2]: unsigned int |
Parameter[3]: Number of nodes to destroy Type[3]: unsigned int |
Explanation: |
This function will try and destroy a number (Parameter[3]) of nodes of type (Parameter[2]). |
Note: |
The number of nodes created will be less than or equal to the number requested (Parameter[3]), the only reason that less will be destroyed is if there are no more unused nodes of that type (Parameter[2]). |
Functions to add and delete data to a Vstr string |
Function: vstr_del()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Explanation: |
This function is used to delete data in the Vstr string. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. The function will return 0 if it needs to allocate memory and cannot do so, although if it does fail the Vstr string won't have changed (Ie. the function is atomic). |
Note: |
Deleted nodes do not get returned to the system, they get put into a pool in the Vstr configuration for reuse on the next call to a vstr_add_*() function. Deleteing the entire Vstr string and deleteing from the begining onwards are faster operations than a generic delete. They also never require allocating memory and so the return value can be ignored. |
Functions to substitute data in a Vstr string with other data |
Function: VSTR_SUB_CSTR_REF()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Vstr memory reference Type[4]: struct Vstr_ref * |
Parameter[5]: Offset of Vstr memory refernce (Parameter[4]) Type[5]: size_t |
Explanation: |
This macro function calls vstr_sub_ref() with the length being the value of strlen() on the memory from the Vstr memory reference (Parameter[3]) starting at the offset (Parameter[4]). |
Functions to move data from a Vstr string to another Vstr string |
Function: vstr_mov()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: struct Vstr_base * |
Parameter[2]: Append position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Vstr string Type[3]: struct Vstr_base * |
Parameter[4]: Start position in the Vstr string (Parameter[3]) Type[4]: size_t |
Parameter[5]: Length in the Vstr string (Parameter[3]) Type[5]: size_t |
Explanation: |
This function is used to move data, deleteing it from one Vstr string (Parameter[3]) and adding it to another Vstr string (Parameter[1]). If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. The function will return 0 if it needs to allocate memory and cannot do so, although if it does fail the Vstr string won't have changed (Ie. the function is atomic). |
Functions for miscellaneous control of options |
Function: vstr_cntl_conf()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Type[1]: struct Vstr_conf * |
Parameter[2]: Option type starting VSTR_CNTL_CONF_ Type[2]: int |
Parameter[ ... ]: Options depending on value of Parameter[2] Type[ ... ]: ... |
Functions to compare with a Vstr string |
Function: VSTR_CMP_VERS_CSTR_EQ()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to ASCII C string Type[4]: const char * |
Explanation: |
This macro function returns !vstr_cmp_vers_buf(), if both of the length values are equal, with the length of the buffer being the value of strlen() on the data parameter (Parameter[4]). |
Functions to search in a Vstr string |
Function: vstr_srch_chr_fwd()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Character to search for Type[4]: char |
Explanation: |
This function is used to search forwards for a character in a Vstr string. Think of this function as doing a vstr_export_cstr_ptr() on the Vstr string, and then a call to memchr() (although it's much faster than doing that and doesn't allocate anything). If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_srch_chr_rev()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Character Type[4]: char |
Explanation: |
This function is used to search backwards for a character in a Vstr string. Think of this function as doing a vstr_export_cstr_ptr() on the Vstr string, and then a call to memrchr() (although it doesn't allocate anything). If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_srch_chrs_fwd()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to data Type[4]: const char * |
Parameter[5]: Length of data (Parameter[4]) Type[5]: size_t |
Explanation: |
This function is used to search forwards for any of the characters in the data array (Parameter[4]) in a Vstr string. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_srch_chrs_rev()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to data Type[4]: const char * |
Parameter[5]: Length of data (Parameter[4]) Type[5]: size_t |
Explanation: |
This function is used to search backwards for any of the characters in the data array (Parameter[4]) in a Vstr string. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_csrch_chrs_fwd()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to data Type[4]: const char * |
Parameter[5]: Length of data (Parameter[4]) Type[5]: size_t |
Explanation: |
This function is used to search forwards for any of the characters not in the data array (Parameter[4]) in a Vstr string. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_csrch_chrs_rev()
Returns: Position in the Vstr string of the character Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to data Type[4]: const char * |
Parameter[5]: Length of data (Parameter[4]) Type[5]: size_t |
Explanation: |
This function is used to search backwards for any of the characters not in the data array (Parameter[4]) in a Vstr string. If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_srch_vstr_fwd()
Returns: Position in the Vstr string of the start of the data Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Vstr string Type[4]: const struct Vstr_base * |
Parameter[5]: Start position in the Vstr string (Parameter[4]) Type[5]: size_t |
Parameter[6]: Length in the Vstr string (Parameter[4]) Type[6]: size_t |
Explanation: |
This function is used to search forwards for the data in the Vstr string (Parameter[4]) in the Vstr string (Parameter[1]). Think of this function as doing a vstr_export_cstr_ptr() on each Vstr string, and then a call to memmem() (although it's much faster than doing that and doesn't allocate anything). If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: vstr_srch_vstr_rev()
Returns: Position in the Vstr string of the start of the data Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Vstr string Type[4]: const struct Vstr_base * |
Parameter[5]: Start position in the Vstr string (Parameter[4]) Type[5]: size_t |
Parameter[6]: Length in the Vstr string (Parameter[4]) Type[6]: size_t |
Explanation: |
This function is used to search backwards for the data in the Vstr string (Parameter[4]) in the Vstr string (Parameter[1]). If the function can detect that the values of parameters are in error the function will return 0 to indicate an error. |
Function: VSTR_SRCH_CASE_CSTR_BUF_REV()
Returns: Position in the Vstr string of the start of the data Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to data Type[4]: const char * |
Explanation: |
This macro function calls vstr_srch_case_buf_rev() with the length being the value of strlen() on the data parameter (Parameter[4]). |
Functions to calculate spanning in a Vstr string |
Function: VSTR_CSPN_CSTR_CHRS_REV()
Returns: Number of characters in the compliment span Type: size_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to spanning characters Type[4]: const char * |
Explanation: |
This macro function calls vstr_cspn_chrs_rev() with the length being the value of strlen() on the data parameter (Parameter[4]). |
Functions for converting data in a vstr |
Function: vstr_conv_unprintable_del()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Flags starting VSTR_FLAG_CONV_UNPRINTABLE_ Type[4]: unsigned int |
Explanation: |
|
Function: vstr_conv_decode_uri()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Explanation: |
This function converts characters from the URI %<hex><hex> encoding, so that the encoded sequence %20 becomes the ASCII space character ' ' etc. |
Functions for dealing with a section of a vstr |
Function: vstr_sects_make()
Returns: Vstr sections Type: struct Vstr_sects * |
Parameter[1]: Maximum number of the Vstr sections Type[1]: unsigned int |
Explanation: |
|
Function: vstr_sects_free()
Returns: Nothing Type: void |
Parameter[1]: Vstr sections Type[1]: struct Vstr_sects * |
Explanation: |
This function will free a Vstr sections, allocated by vstr_sects_make(). |
Function: vstr_sects_update_add()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Vstr sections Type[2]: struct Vstr_sects * |
Explanation: |
This function will cause the section (Parameter[2]) to automatically be updated when changes are made to the Vstr string (Parameter[1]). |
Note: |
You need to call vstr_sects_update_del(), before you free the section (Parameter[2]). However if the next thing you are going to do is call vstr_free_base() on the Vstr string (Parameter[1]), then you can delete them backwards. |
Function: vstr_sects_srch()
Returns: Number of the section in the Vstr sections (Parameter[1]) Type: unsigned int |
Parameter[1]: Vstr sections Type[1]: struct Vstr_sects * |
Parameter[2]: Position in a Vstr string Type[2]: size_t |
Parameter[3]: Length in a Vstr string Type[3]: size_t |
Explanation: |
This function will search for the first Vstr section node in a Vstr section (Parameter[1]) that matches the position and length. |
Functions for splitting data in a Vstr into sections |
Function: VSTR_SPLIT_CSTR_CHRS()
Returns: Number of Vstr section nodes added to the Vstr sections Type: unsigned int |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Pointer to characters to split on Type[4]: const char * |
Parameter[5]: Length of characters (Parameter[4]) Type[5]: size_t |
Parameter[6]: Vstr sections Type[6]: struct Vstr_sects * |
Parameter[7]: Limit of sections to add to Vstr sections (Parameter[6]) Type[7]: unsigned int |
Parameter[8]: Flags starting VSTR_FLAG_SPLIT_ Type[8]: unsigned int |
Explanation: |
This macro function calls vstr_split_chrs() with the length being the value of strlen() on the data parameter (Parameter[4]). |
Functions for parsing data from a vstr |
Function: vstr_parse_ipv4()
Returns: Number pared from Vstr string Type: uintmax_t |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Returns ip in array ellements 0 to 3 Type[4]: unsigned char * |
Parameter[5]: Returns cidr mask Type[5]: unsigned int * |
Parameter[6]: Flags starting VSTR_FLAG_PARSE_IPV4_ Type[6]: unsigned int |
Parameter[7]: Returns length of parsed ip address (Parameter[4] Parameter[5]) Type[7]: size_t * |
Parameter[8]: Returns error code starting VSTR_TYPE_PARSE_IPV4_ERR_ Type[8]: unsigned int * |
Explanation: |
This function will parse an ipv4 address, or optionaly an ipv4 address and a cidr mask / netmask, from the Vstr string. |
Functions for hooking into the fmt function for the Vstr string |
Function: VSTR_FMT_CB_ARG_VAL()
Returns: Data of specified type Type: Paramter[2] |
Parameter[1]: Format specifier passed to a callback of vstr_add_vfmt() Type[1]: struct Vstr_fmt_spec * |
Parameter[2]: Type of the specified value Type[2]: <symbol> |
Parameter[3]: Number of the parameter for the callback Type[3]: size_t |
Explanation: |
This macro function returns the nth (Parameter[3]) parameter passed to a callback of vstr_add_vfmt(), by value. |
Functions for hooking into the cache system for the Vstr string |
Function: vstr_cache_get()
Returns: Data for cache function Type: void * |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Cookie reference for cache function Type[2]: unsigned int |
Explanation: |
|
Function: vstr_cache_cb_free()
Returns: Nothing Type: void |
Parameter[1]: Vstr string Type[1]: const struct Vstr_base * |
Parameter[2]: Cookie reference for cache function Type[2]: unsigned int |
Explanation: |
If you have generated cache data, this function will tell the cache function to free that data. |
Note: |
A Cookie reference of "zero" means tell all cache functions to free cached data. Note that this can cause severe performance degradation if overly used. |
Short cut helper functions |
Function: vstr_sc_write_file()
Returns: TRUE on success and FALSE on failure Type: int |
Parameter[1]: Vstr string Type[1]: struct Vstr_base * |
Parameter[2]: Start position in the Vstr string (Parameter[1]) Type[2]: size_t |
Parameter[3]: Length in the Vstr string (Parameter[1]) Type[3]: size_t |
Parameter[4]: Filename to add a mapping from Type[4]: const char * |
Parameter[5]: Flags to pass to the open() system call Type[5]: int |
Parameter[6]: Mode to pass to the open() system call Type[6]: mode_t |
Parameter[7]: Offset to start writing at Type[7]: off64_t |
Parameter[8]: Returns error code starting VSTR_TYPE_SC_WRITE_FILE_ERR_ Type[8]: unsigned int * |
Explanation: |
This function is used to take data from a Vstr string and write it to a file, after open()ing the file (Parameter[4]) with open flags (Parameter[5]) and open mode (Parameter[6]). |