Vstr documentation -- functions

Index of sections

Initialization function

Function: vstr_init()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Nothing
Type[1]: void
Explanation:

This function needs to be called before any of the other functions are called.

Note:

The function can be called multiple times, without any problems.

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_cstr_ptr()
Returns: A pointer to an array of characters, terminated by NUL
Type: char *
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
Explanation:

This function is used to export a pointer to an array of characters of length (Parameter[3] + 1), the last byte will be a 0 to terminate the "C string".

Multiple adjacent calls will return the same pointer.

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:

If you alter the Vstr in anyway then the returned pointer may point to free()'d memory. To get a reference to this data use vstr_export_cstr_ref() instead.

If you want to make sure that the cached data is gone from the Vstr string, cache then you can call vstr_cache_free() on the cookie from "/vstr__/cstr".

Any _NON data in the Vstr will be uninitialised data in the "C string".

If there are any 0 bytes in the Vstr they will make the string look shorter than it really is to normal C/POSIX string functions.

Function: vstr_export_cstr_malloc()
Returns: A malloc'd pointer to an array of characters, terminated by NUL
Type: char *
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
Explanation:

This function is used to export a malloc'd pointer to an array of characters of length (Parameter[3] + 1), the last byte will be a 0 to terminate the "C string". You will need to pass the pointer to free(), when you are done with it.

Each call will return a different pointer.

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 "C string".

If there are any 0 bytes in the Vstr they will make the string look shorter than it really is to normal C/POSIX string functions.

Function: vstr_export_cstr_buf()
Returns: Nothing
Type: void
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]: Pointer to data
Type[4]: void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to export a copy of the data in the Vstr string to a data array, the maximum ammount of data stored in the array will be of length (Parameter[3] + 1), the last byte will be a 0 to terminate the "C string". However the data before the terminator of the "C string" is limited to (Parameter[5] - 1).

Note:

Data from nodes of type NON are exported by not doing anything to the underlying data array (Ie. It'll have whatever data was in there to start with).

If there are any 0 bytes in the Vstr they will make the "C string" look shorter than it really is to normal C/POSIX string functions.

Function: vstr_export_cstr_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] + 1), the last byte will be a 0 to terminate the "C string" stored in (Vstr_ref *)->ptr. 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:

If you want to make sure that the cached data is gone from the Vstr string, cache then you can call vstr_cache_free() on the cookie from "/vstr__/cstr".

Any _NON data in the Vstr will be uninitialised data in the "C string".

If there are any 0 bytes in the Vstr they will make the string look shorter than it really is to normal C/POSIX string functions.

Function: vstr_export_iovec_ptr_all()
Returns: Size of bytes in the Vstr string
Type: size_t
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Returns the start of the iovec array
Type[2]: struct iovec **
Parameter[2]: Returns the number of iovec structures in the array
Type[2]: unsigned int *
Explanation:

This function is used to export a pointer to an array of iovec structures this can then be passed directly to writev() etc. or just used to quickly access the 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.

Note:

Nodes of type NON are represented by a iov_base set to NULL.

Altering the iov_base/iov_len members will probably do very bad things, if you need to do this use the vstr_export_iovec_cpy_ptr()

Altering the data in the iovec structure isn't a good idea as it isn't easy for the programer to know if the data is shared/read-only. If you need to do this you should use either the vstr_sub_* functions instead or vstr_export_iovec_cpy_buf() (the later does a copy).

Function: vstr_export_iovec_cpy_buf()
Returns: Size of bytes exported from the Vstr string
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 array of initialized iovec structures
Type[4]: struct iovec *
Parameter[5]: Number of iovec structures (Parameter[4])
Type[5]: unsigned int
Parameter[6]: Returns the number of iovec structures used in the array
Type[6]: unsigned int *
Explanation:

This function is used to export a copy of the data in the Vstr string to an array of iovec structures this can then be passed directly to writev() (or even a readv() although that wouldn't often be useful) etc.

Think of this function as doing a readv() from 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.

Note:

Data from nodes of type NON are exported by not doing anything to the underlying iov_base data arrays (Ie. It'll have whatever data was in there to start with).

The length returned may be shorter than that given as Parameter[3], as it's the number of bytes copied into the iov_base arrays in the iovec structures.

Function: vstr_export_iovec_cpy_ptr()
Returns: Size of bytes exported from the Vstr string
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 array of iovec structures
Type[4]: struct iovec *
Parameter[5]: Number of iovec structures (Parameter[4])
Type[5]: unsigned int
Parameter[6]: Returns the number of iovec structures used in the array
Type[6]: unsigned int *
Explanation:

This function is used to export a set of pointer/length pairs to the data specified in the Vstr string, this can then be passed directly to writev() etc.

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Note:

Nodes of type NON are represented by a iov_base set to NULL.

Altering the data in the iovec structure isn't a good idea as it isn't easy for the programer to know if the data is shared/read-only. If you need to do this you should use either the vstr_sub_* functions instead or vstr_export_iovec_cpy_buf() (the later does a copy).

Function: vstr_export_buf()
Returns: Size of bytes exported from the Vstr string
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]: Data array to export to
Type[4]: void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to export a copy of the data in the Vstr string to a data array.

Think of this function as doing a read() from a Vstr string. However the data will be limited to the minimum of the length of the vstr (Parameter[3]) and the length of the data (Parameter[5]).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Note:

Data from nodes of type NON are exported by not doing anything to the underlying data array (Ie. It'll have whatever data was in there to start with).

Function: vstr_export_chr()
Returns: Character exported from the Vstr string
Type: char
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Position in the Vstr string (Parameter[1])
Type[2]: size_t
Explanation:

This function is used to return a character at a certain position in a Vstr string.

Note:

It is impossible to distinguish between an error, data from a NON node and real data that is equal to the value 0.

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:

This function does nothing.

Function: vstr_ref_cb_free_ref()
Returns: Nothing
Type: void
Parameter[1]: Vstr memory reference
Type[1]: struct Vstr_ref *
Explanation:

This will call free() on the Vstr_ref (Parameter[1]).

Function: vstr_ref_cb_free_ptr()
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.

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_add()
Returns: Vstr memory reference (Parameter[1])
Type: struct Vstr_ref *
Parameter[1]: Vstr memory reference
Type[1]: struct Vstr_ref *
Explanation:

This function will add a reference count to the Vstr_ref (Parameter[1]).

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_free_conf()
Returns: Nothing
Type: void
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Explanation:

This function will free a Vstr configuration, allocated by vstr_make_conf().

Function: vstr_swap_conf()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: New Vstr configuration; returned old Vstr configuration
Type[2]: struct Vstr_conf **
Explanation:

This function will swap a Vstr configuration into a Vstr string possibly changing the Vstr configuration to be compatible with the Vstr string. On success the Vstr configuration that was being used by the Vstr string is returned.

Note:

Using this function allows you to use vstr_add_fmt() and vstr_add_vfmt() on a Vstr that you don't own, by doing...

     if (vstr_swap_conf(notmy_vstr_string, &my_vstr_conf))
     {
       vstr_add_fmt(notmy_vstr_string, ... );
       vstr_swap_conf(notmy_vstr_string, &my_vstr_conf);
     }

...note that the last call swaps the configuration back. However if you are not using any custom specifiers then you can just call vstr_add_sysfmt() instead.

The function will return 0 if it needs to allocate memory and cannot do so.

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:

This function will make a Vstr string, or return NULL.

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_dup_buf()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Pointer to data
Type[2]: const void *
Parameter[3]: Length of data (Parameter[2])
Type[3]: size_t
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_buf().

Function: vstr_dup_ptr()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Pointer to data
Type[2]: const void *
Parameter[3]: Length of data (Parameter[2])
Type[3]: size_t
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_ptr().

Function: vstr_dup_non()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Length of non data
Type[2]: size_t
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_non().

Function: vstr_dup_ref()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Vstr memory reference
Type[2]: struct Vstr_ref *
Parameter[3]: Offset of Vstr memory refernce (Parameter[2])
Type[3]: size_t
Parameter[4]: Length of Vstr memory refernce (Parameter[2])
Type[4]: size_t
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_ref().

Function: vstr_dup_vstr()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Vstr string
Type[2]: const struct Vstr_base *
Parameter[3]: Start position in the Vstr string (Parameter[2])
Type[3]: size_t
Parameter[4]: Length in the Vstr string (Parameter[2])
Type[4]: size_t
Parameter[6]: Flags for Vstr add (VSTR_TYPE_ADD_*)
Type[6]: unsigned int
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_vstr().

Function: vstr_dup_rep_chr()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Character to repeat
Type[2]: char
Parameter[3]: Number of times to repeat characnter (Parameter[2])
Type[3]: size_t
Explanation:

This function is equivilent to calling vstr_make_base() and then vstr_add_rep_chr().

Function: VSTR_DUP_CSTR_BUF()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Pointer to data
Type[2]: const char *
Explanation:

This macro function calls vstr_dup_buf() with the length being the value of strlen() on the data parameter (Parameter[2]).

Function: VSTR_DUP_CSTR_PTR()
Returns: Vstr string
Type: struct Vstr_base *
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Pointer to data
Type[2]: const char *
Explanation:

This macro function calls vstr_dup_ptr() with the length being the value of strlen() on the data parameter (Parameter[2]).

Function: VSTR_DUP_CSTR_REF()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Vstr memory reference
Type[2]: struct Vstr_ref *
Parameter[3]: Offset of Vstr memory refernce (Parameter[3])
Type[3]: size_t
Explanation:

This macro function calls vstr_dup_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]).

Function: vstr_ref_make_malloc()
Returns: Vstr memory reference
Type: struct Vstr_ref *
Parameter[1]: Size of malloc'd area to create in the memory reference
Type[1]: size_t
Explanation:

This function will create an area of memory, using malloc, and create a Vstr memory reference to that memory. The Vstr memory reference will have a reference count of 1 and a cleanup function of vstr_ref_cb_free_ptr_ref().

Function: vstr_ref_make_ptr()
Returns: Vstr memory reference
Type: struct Vstr_ref *
Parameter[1]: Pointer to memory
Type[1]: void *
Parameter[1]: Function callback for Vstr memory reference
Type[1]: void (*)(struct Vstr_ref *)
Explanation:

This function will create a Vstr memory reference. The Vstr memory reference will have a reference count of 1, a pointer value of pointer passed (Parameter[1]) and a cleanup function of the function passed (Parameter[2]).

Function: vstr_make_spare_nodes()
Returns: Number of nodes created
Type: unsigned int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Type of nodes to create
Type[2]: unsigned int
Parameter[3]: Number of nodes to create
Type[3]: unsigned int
Explanation:

This function will try and create 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]), however if it is less than then the malloc_bad flag will be set (Parameter[1])->malloc_bad.

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_add_buf()
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]: Pointer to data
Type[3]: const void *
Parameter[4]: Length of data (Parameter[3])
Type[4]: size_t
Explanation:

This function is used to add a copy of the data in the data array to a Vstr string.

Think of this function as doing a write() into 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.

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).

Function: vstr_add_ptr()
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]: Pointer to data
Type[3]: const void *
Parameter[4]: Length of data (Parameter[3])
Type[4]: size_t
Explanation:

This function is used to add a pointer to a data array to 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.

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:

If the data in the array needs to be free'd the programer will have to decide when it is no longer being used by the Vstr string and free it. It is often easier to create a memory reference and use vstr_add_ref() instead.

Function: vstr_add_non()
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]: Length of non data
Type[3]: size_t
Explanation:

This function is used to add "non" (or invisible) data to 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.

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).

Function: vstr_add_ref()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Append position in the Vstr string (Parameter[1])
Type[2]: size_t
Parameter[3]: Vstr memory reference
Type[3]: struct Vstr_ref *
Parameter[4]: Offset of Vstr memory refernce (Parameter[3])
Type[4]: size_t
Parameter[5]: Length of Vstr memory refernce (Parameter[3])
Type[5]: size_t
Explanation:

This function is used to add a memory reference to 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.

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).

Function: vstr_add_vstr()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Append position in the Vstr string (Parameter[1])
Type[2]: size_t
Parameter[3]: Vstr string
Type[3]: const 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
Parameter[6]: Flags for Vstr add (VSTR_TYPE_ADD_*)
Type[6]: unsigned int
Explanation:

This function is used to add data in one Vstr string (Parameter[3]) 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).

Note:

The function can change how the data is added to the Vstr string (Parameter[1]) and in some cases even how the data is represented in the Vstr string (Parameter[3]) for more information see the documentation on the VSTR_TYPE_ADD_* constants.

This function will set _both_ (Parameter[1])->conf->malloc_bad and (Parameter[3])->conf->malloc_bad if any of the allocation calls fails.

Function: vstr_add_rep_chr()
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]: Character to repeat
Type[3]: char
Parameter[4]: Number of times to repeat characnter (Parameter[3])
Type[4]: size_t
Explanation:

This function is used to add 1 or more copies of the character (Parameter[3]) to the Vstr string.

Think of this function as doing a memset() into 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).

Function: VSTR_ADD_CSTR_BUF()
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]: Pointer to data
Type[3]: const char *
Explanation:

This macro function calls vstr_add_buf() with the length being the value of strlen() on the data parameter (Parameter[3]).

Function: VSTR_ADD_CSTR_PTR()
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]: Pointer to data
Type[3]: const char *
Explanation:

This macro function calls vstr_add_ptr() with the length being the value of strlen() on the data parameter (Parameter[3]).

Function: VSTR_ADD_CSTR_REF()
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 memory reference
Type[3]: struct Vstr_ref *
Parameter[4]: Offset of Vstr memory refernce (Parameter[3])
Type[4]: size_t
Explanation:

This macro function calls vstr_add_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]).

Function: vstr_add_vfmt()
Returns: Number of bytes added
Type: size_t
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]: Format string, a superset of the rules for C99 printf
Type[3]: const char *
Parameter[4]: Standard argument object from va_start()
Type[4]: va_list
Explanation:

This function works like calling vsprintf() directly into a Vstr string, however this is a portable implimentation which is feature complete with glibc-2.2.x sprintf(); implements custom specifiers, if you use the vstr_fmt_add() function, and doesn't require a double copy.

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:

Depending on how the library was compiled double support is implemented by either calling the underlying host implementation of sprintf(), by internal code or simply by assuming all double's are zero. When using the host implemention system bugs of inacuracy will show through, however the feature set remains the same (Ie. the ' flag works the same).

Because specifiers can be overridden using vstr_fmt_add() if you are adding data to a Vstr string that you didn't create you should use either vstr_add_vsysfmt() or vstr_swap_conf().

Function: vstr_add_fmt()
Returns: Number of bytes added
Type: size_t
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]: Format string, a superset of the rules for C99 printf
Type[3]: const char *
Parameter[4]: Options depending on value of Parameter[3]
Type[4]: ...
Explanation:

This just calls vstr_add_vfmt() after convtering the argument list (Paramter[4]) a va_list object.

Function: vstr_add_vsysfmt()
Returns: Number of bytes added
Type: size_t
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]: Format string, a superset of the rules for C99 printf
Type[3]: const char *
Parameter[4]: Standard argument object from va_start()
Type[4]: va_list
Explanation:

This function does the same thing as vstr_add_vfmt() but ignores custom specifiers (see vstr_fmt_add()).

Function: vstr_add_sysfmt()
Returns: Number of bytes added
Type: size_t
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]: Format string, a superset of the rules for C99 printf
Type[3]: const char *
Parameter[4]: Options depending on value of Parameter[3]
Type[4]: ...
Explanation:

This just calls vstr_add_vsysfmt() after convtering the argument list (Paramter[4]) a va_list object.

Function: vstr_add_iovec_buf_beg()
Returns: Number of bytes in the iovec array
Type: size_t
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]: Minimum ammount of iovecs to add
Type[3]: unsigned int
Parameter[4]: Maximum ammount of iovecs to add
Type[4]: unsigned int
Parameter[5]: Returns the start of the iovec array
Type[5]: struct iovec **
Parameter[6]: Returns the number of iovec structures in the array
Type[6]: unsigned int *
Explanation:

This function is used to add a copy of data directly into the Vstr string, the ammount of data available will be between the minimum (Parameter[4]) and maximum ((Parameter[5]) + 1) number of iovecs multiplied by the length of data in _BUF type nodes. The obvious use for the data if to call readv() on it.

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:

You shouldn't call any other vstr functions between vstr_add_iovec_buf_beg() and vstr_add_iovec_buf_end(), unless you know that they are operating on a different Vstr string which is using a different Vstr configuration.

The reason there is a +1 on the maximum value is that data may be appened to a _BUF node just before the start of where the data is to go, this is almost guaranteed to happen when adding to the end of a Vstr string and saves a lot of wasted space.

Function: vstr_add_iovec_buf_end()
Returns: Nothing
Type: void
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Append position in the Vstr string (Parameter[1])
Type[2]: size_t
Parameter[3]: Number of bytes added to the iovec array
Type[3]: size_t
Explanation:

This function is used after calling vstr_add_iovec_buf_beg() and you've then filled in a bunch of data.

Note:

Although it's safe to not bother calling this function if you didn't have anything to add to the Vstr string it is often more efficient to call this function with Parameter[3] as 0.

Function: vstr_add_netstr_beg()
Returns: Position of start of netstr (Parameter[2]) + 1
Type: size_t
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Append position in the Vstr string (Parameter[1])
Type[2]: size_t
Explanation:

This function creates the start of a netstring http://cr.yp.to/proto/netstrings.txt this can be used in conjunction with vstr_add_netstr_end() to easily create netstrings.

Function: vstr_add_netstr_end()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Position returned from vstr_add_netstr_beg()
Type[2]: size_t
Parameter[3]: End of netstring
Type[3]: size_t
Explanation:

This function is called after calling vstr_add_netstr_beg(), adding all the data you want to the netstring and then passing the position of the end of that data.

Upon success a valid netstring will contain all the data added between the two calls.

Note:

It is valid to pass the same values for (Parameter[2]) and (parameter[3]), as that signifies that there is no data in the netstring.

It is almost guaranteed that data will need to be removed from the begining of the netstring due to the length being shorter than the maximum, this is inefficient and could cause problems if you know how big the Vstr string is you can use the vstr_add_netstr2_* functions to solve both problems.

Function: vstr_add_netstr2_beg()
Returns: Position of start of netstr (Parameter[2]) + 1
Type: size_t
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Append position in the Vstr string (Parameter[1])
Type[2]: size_t
Explanation:

This function creates the start of a netstring2 which is like a netstring http://cr.yp.to/proto/netstrings.txt but can have leading zeros, this can be used in conjunction with vstr_add_netstr2_end() to easily create netstring2s.

Function: vstr_add_netstr2_end()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Position returned from vstr_add_netstr2_beg()
Type[2]: size_t
Parameter[3]: End of netstring2
Type[3]: size_t
Explanation:

This function is called after calling vstr_add_netstr2_beg(), adding all the data you want to the netstring2 and then passing the position of the end of that data.

Upon success a netstring2 will contain all the data added between the two calls.

Note:

It is valid to pass the same values for (Parameter[2]) and (parameter[3]), as that signifies that there is no data in the netstring.

No data is ever removed from the begining of a netstring2, this is imcompatible with the netstring spec. but is more efficient and doesn't cause problems if you know how big the Vstr string is and can't have it lose data from the begining/middle.

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_buf()
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]: Pointer to data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to substitute the data in the Vstr string with a copy of the data in the data array.

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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[5]).

Think of this function as doing a vstr_del() and then a vstr_add_buf() (but it's atomic).

If the length of the data (Parameter[5]) is less than or equal to the length of the Vstr string (Parameter[3]) and the data in the Vstr string is in a BUF node then the data will just be overwritten (Ie. no allocations will happen).

Function: vstr_sub_ptr()
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]: Pointer to data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to substitute the data in the Vstr string with a pointer to a data array.

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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[7]), think of this function like doing a vstr_del() and then a vstr_add_ptr() (but it's atomic).

Function: vstr_sub_non()
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]: Length of non data
Type[4]: size_t
Explanation:

This function is used to substitute the data in the Vstr string with "non" (or invisible) data.

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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[7]), think of this function like doing a vstr_del() and then a vstr_add_non() (but it's atomic).

Function: vstr_sub_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
Parameter[6]: Length of Vstr memory refernce (Parameter[4])
Type[6]: size_t
Explanation:

This function is used to substitute the data in the Vstr string with a memory reference.

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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[7]), think of this function like doing a vstr_del() and then a vstr_add_ref() (but it's atomic).

Function: vstr_sub_vstr()
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 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
Parameter[6]: Flags for Vstr sub (VSTR_TYPE_SUB_*)
Type[6]: unsigned int
Explanation:

This function is used to substitute the data in the Vstr string (Parameter[1]) with the data in another Vstr string (Parameter[4]).

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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[7]), think of this function like doing a vstr_del() and then a vstr_add_vstr() (but it's atomic).

The function can change how the data is added to the Vstr string (Parameter[1]) and in some cases even how the data is represented in the Vstr string (Parameter[3]) for more information see the documentation on the VSTR_TYPE_SUB_* constants.

Function: vstr_sub_rep_chr()
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]: Character to repeat
Type[4]: char
Parameter[5]: Number of times to repeat characnter (Parameter[3])
Type[5]: size_t
Explanation:

This function is used to substitute the data in the Vstr string with one or more copies of the character (Parameter[3]).

Think of this function as doing a memset() into 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:

The length of the Vstr string (Parameter[3]) can be larger or smaller than the length of the data (Parameter[5]).

Think of this function as doing a vstr_del() and then a vstr_add_rep_chr() (but it's atomic).

If the length of the data (Parameter[5]) is equal to the length of the Vstr string (Parameter[3]) and the data in the Vstr string is in a BUF node then the data will just be overwritten (Ie. no allocations will happen).

Function: VSTR_SUB_CSTR_BUF()
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]: Pointer to data
Type[4]: const char *
Explanation:

This macro function calls vstr_sub_buf() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SUB_CSTR_PTR()
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]: Pointer to data
Type[4]: const char *
Explanation:

This macro function calls vstr_sub_ptr() with the length being the value of strlen() on the data parameter (Parameter[4]).

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_opt()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Option type starting VSTR_CNTL_OPT_
Type[1]: int
Parameter[ ... ]: Options depending on value of Parameter[1]
Type[ ... ]: ...
Function: vstr_cntl_base()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Option type starting VSTR_CNTL_BASE_
Type[2]: int
Parameter[ ... ]: Options depending on value of Parameter[2]
Type[ ... ]: ...
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()
Returns: Less then zero, zero or greater than zero depending on comparison
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]: 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 compares the data in one Vstr string (Parameter[1]) with data in another Vstr string (Parameter[4]) byte by byte, all data is compared unsigned.

Think of this function as doing a vstr_export_cstr_ptr() on each Vstr string, and then a call to memcmp() (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.

Note:

Data of type _NON is assumed to have the value -1, and so all data compares as greater than it.

Function: vstr_cmp_buf()
Returns: Less then zero, zero or greater than zero depending on comparison
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 data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

Think of this function as doing a vstr_dup_ptr() on the data array (Parameter[4]) and then calling vstr_cmp().

Function: vstr_cmp_case()
Returns: Less then zero, zero or greater than zero depending on comparison
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]: 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 like vstr_cmp() but uppercase and lowercase ASCII values compare equally with each other.

Note:

Data of type _NON is assumed to have the value -1, and so all data compares as greater than it.

Function: vstr_cmp_case_buf()
Returns: Less then zero, zero or greater than zero depending on comparison
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 *
Parameter[5]: Length of ASCII C string (Parameter[4])
Type[5]: size_t
Explanation:

Think of this function as doing a vstr_dup_ptr() on the data array (Parameter[4]) and then calling vstr_cmp_case().

Function: vstr_cmp_vers()
Returns: Less then zero, zero or greater than zero depending on comparison
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]: 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 compare the data in one Vstr string (Parameter[1]) with data in another Vstr string (Parameter[4]), however for ASCII digits the algorithum tests on the numbers themselves (so "10" is greater than "9" but "01" is greater than "012", as the later are fractions).

Think of this function as doing a vstr_export_cstr_ptr() on each Vstr string, and then a call to strverscmp() (although it doesn't allocate anything, _and_ it deals with 0 bytes in the data).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Note:

Data of type _NON is assumed to have the value -1, and so all data compares as greater than it.

Function: vstr_cmp_vers_buf()
Returns: Less then zero, zero or greater than zero depending on comparison
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 *
Parameter[5]: Length of ASCII C string (Parameter[4])
Type[5]: size_t
Explanation:

Think of this function as doing a vstr_dup_ptr() on the data array (Parameter[4]) and then calling vstr_cmp_vers().

Function: VSTR_CMP_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]: 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 macro function calls returns !vstr_cmp() if both of the length values (Parameter[3] Parameter[6]) are equal.

Function: VSTR_CMP_CSTR()
Returns: Less then zero, zero or greater than zero depending on comparison
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 calls vstr_cmp_buf() with the length of the buffer being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CMP_BUF_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 data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This macro function calls returns !vstr_cmp_buf() if both of the length values (Parameter[3] Parameter[5]) are equal.

Function: VSTR_CMP_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_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]).

Function: VSTR_CMP_CASE_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]: 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 macro function calls returns !vstr_cmp_case() if both of the length values (Parameter[3] Parameter[6]) are equal.

Function: VSTR_CMP_CASE_CSTR()
Returns: Less then zero, zero or greater than zero depending on comparison
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 calls vstr_cmp_case_buf() with the length of the buffer being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CMP_CASE_BUF_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 void *
Parameter[5]: Length of ASCII C string (Parameter[4])
Type[5]: size_t
Explanation:

This macro function calls returns !vstr_cmp_case_buf() if both of the length values (Parameter[3] Parameter[5]) are equal.

Function: VSTR_CMP_CASE_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_case_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]).

Function: VSTR_CMP_VERS_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]: 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 macro function calls returns !vstr_cmp_vers() if both of the length values (Parameter[3] Parameter[6]) are equal.

Function: VSTR_CMP_VERS_CSTR()
Returns: Less then zero, zero or greater than zero depending on comparison
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 calls vstr_cmp_vers_buf() with the length of the buffer being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CMP_VERS_BUF_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 void *
Parameter[5]: Length of ASCII C string (Parameter[4])
Type[5]: size_t
Explanation:

This macro function calls returns !vstr_cmp_vers_buf() if both of the length values (Parameter[3] Parameter[5]) are equal.

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.

If the character cannot be found 0 is returned.

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.

If the character cannot be found 0 is returned.

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.

If any of the characters cannot be found 0 is returned.

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.

If any of the characters cannot be found 0 is returned.

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.

If any of the characters cannot be found 0 is returned.

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.

If any of the characters cannot be found 0 is returned.

Function: vstr_srch_buf_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]: Pointer to data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to search forwards for the data in the data array (Parameter[4]) in a Vstr string.

Think of this function as doing a vstr_export_cstr_ptr() on the 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.

If the data cannot be found 0 is returned.

Note:

If the pointer to data (Paramter[4]) is NULL then _NON data of the specified size (Paramter[5]) will be searched for.

Function: vstr_srch_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 void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to search backwards for the data 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.

If the data cannot be found 0 is returned.

Note:

If the pointer to data (Paramter[4]) is NULL then _NON data of the specified size (Paramter[5]) will be searched for.

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.

If the data cannot be found 0 is returned.

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.

If the data cannot be found 0 is returned.

Function: vstr_srch_case_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 the same as vstr_srch_chr_fwd() but uppercase and lowercase ASCII values are treated equivalently.

Function: vstr_srch_case_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 the same as vstr_srch_chr_rev() but uppercase and lowercase ASCII values are treated equivalently.

Function: vstr_srch_case_buf_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]: Pointer to data
Type[4]: const void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is the same as vstr_srch_buf_fwd() but uppercase and lowercase ASCII values are treated equivalently.

Note:

If the pointer to data (Paramter[4]) is NULL then _NON data of the specified size (Paramter[5]) will be searched for.

Function: vstr_srch_case_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 void *
Parameter[5]: Length of data (Parameter[4])
Type[5]: size_t
Explanation:

This function is the same as vstr_srch_buf_fwd() but uppercase and lowercase ASCII values are treated equivalently.

Note:

If the pointer to data (Paramter[4]) is NULL then _NON data of the specified size (Paramter[5]) will be searched for.

Function: vstr_srch_case_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 the same as vstr_srch_vstr_fwd() but uppercase and lowercase ASCII values are treated equivalently.

Function: vstr_srch_case_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 the same as vstr_srch_vstr_rev() but uppercase and lowercase ASCII values are treated equivalently.

Function: VSTR_SRCH_CSTR_BUF_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]: Pointer to data
Type[4]: const char *
Explanation:

This macro function calls vstr_srch_buf_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SRCH_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_buf_rev() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SRCH_CSTR_CHRS_FWD()
Returns: Position in the Vstr string of the start 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 *
Explanation:

This macro function calls vstr_srch_chrs_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SRCH_CSTR_CHRS_REV()
Returns: Position in the Vstr string of the start 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 *
Explanation:

This macro function calls vstr_srch_chrs_rev() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CSRCH_CSTR_CHRS_FWD()
Returns: Position in the Vstr string of the start 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 *
Explanation:

This macro function calls vstr_csrch_chrs_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CSRCH_CSTR_CHRS_REV()
Returns: Position in the Vstr string of the start 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 *
Explanation:

This macro function calls vstr_csrch_chrs_rev() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SRCH_CASE_CSTR_BUF_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]: Pointer to data
Type[4]: const char *
Explanation:

This macro function calls vstr_srch_case_buf_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

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_spn_chrs_fwd()
Returns: Number of characters in the 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 *
Parameter[5]: Length of spanning characters (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to caculate the forward span of characters in the Vstr string that are in the data array.

Think of this function as doing a vstr_export_cstr_ptr() on the Vstr string, and then a call to strspn() (although it's much faster than doing that and doesn't allocate anything, _and_ it deals with 0 bytes in the data).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Function: vstr_spn_chrs_rev()
Returns: Number of characters in the 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 *
Parameter[5]: Length of spanning characters (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to caculate the forward span of characters in the Vstr string that are in the data array.

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Function: vstr_cspn_chrs_fwd()
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 *
Parameter[5]: Length of spanning characters (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to caculate the forward span of characters in the Vstr string that are in the compliment of those in the data array.

Think of this function as doing a vstr_export_cstr_ptr() on the Vstr string, and then a call to strcspn() (although it's much faster than doing that and doesn't allocate anything, _and_ it deals with 0 bytes in the data).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Function: vstr_cspn_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 *
Parameter[5]: Length of spanning characters (Parameter[4])
Type[5]: size_t
Explanation:

This function is used to caculate the backward span of characters in the Vstr string that are in the compliment of those in the data array.

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

Function: VSTR_SPN_CSTR_CHRS_FWD()
Returns: Number of characters in the 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_spn_chrs_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_SPN_CSTR_CHRS_REV()
Returns: Number of characters in the 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_spn_chrs_rev() with the length being the value of strlen() on the data parameter (Parameter[4]).

Function: VSTR_CSPN_CSTR_CHRS_FWD()
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_fwd() with the length being the value of strlen() on the data parameter (Parameter[4]).

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_lowercase()
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 converts all the uppercase ASCII characters into lowercase ASCII characters.

Function: vstr_conv_uppercase()
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 converts all the lowercase ASCII characters into uppercase ASCII characters.

Function: vstr_conv_unprintable_chr()
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
Parameter[5]: Character to substitute in place of the unprintable character
Type[5]: char
Explanation:

This function substitutes all unprintable characters with the substitution character (Paramter[5]).

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:

This function deletes all unprintable characters.

Function: vstr_conv_encode_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 to the URI %<hex><hex> encoding, so the ASCII space character ' ' becomes the encoded sequence %20 etc.

Note:

It converts all the characters in section 2.4.3 of rfc2396 into encoded form (that's all of the control, space, unwise and high ASCII characters).

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_DECL()
Returns: Declaration of a Vstr sections
Type: struct Vstr_sects *
Parameter[1]: Name of variable to declare
Type[1]: <symbol>
Parameter[2]: Maximum size of the Vstr sections (Parameter[1])
Type[2]: unsigned int
Explanation:

This macro function declares a Vstr sections, of the specified size (Parameter[2]).

Note:

VSTR_SECTS_DECL_INIT() needs to be called on the Vstr sections before it can be used.

Function: VSTR_SECTS_EXTERN_DECL()
Returns: Extern declaration of a Vstr sections
Type: struct Vstr_sects *
Parameter[1]: Name of variable to declare
Type[1]: <symbol>
Parameter[2]: Maximum size of the Vstr sections
Type[2]: unsigned int
Explanation:

This macro function declares a Vstr sections, of the specified size (Parameter[2]), that is usable after an extern keyword.

Function: VSTR_SECTS_DECL_INIT()
Returns: Nothing
Type: void
Parameter[1]: Vstr sections
Type[1]: struct Vstr_sects *
Explanation:

This macro function finishes initilising a Vstr sections that has been allocated using VSTR_SECTS_DECL().

This macro function can be called multiple times without causing any problems.

Function: VSTR_SECTS_INIT()
Returns: Nothing
Type: void
Parameter[1]: Vstr sections
Type[1]: struct Vstr_sects *
Parameter[2]: Maximum number of the Vstr sections
Type[2]: unsigned int
Parameter[3]: Array of Vstr section nodes
Type[3]: struct Vstr_sect_node *
Parameter[4]: Non-zero if the nodes (Parameter[3]) can be passed to free()
Type[4]: int
Explanation:

The macro function initialises a self declared Vstr sections.

Note:

Unlike VSTR_SECTS_DECL_INIT() this should only be called once per initialisation.

Function: VSTR_SECTS_NUM()
Returns: The ith Vstr section node in the Vstr sections
Type: struct Vstr_sect_node *
Parameter[1]: Vstr sections
Type[1]: struct Vstr_sects *
Parameter[2]: Number of the section in the Vstr sections (Parameter[1])
Type[2]: unsigned int
Explanation:

Simple way to goto the Vstr section node in a Vstr sections.

Function: vstr_sects_make()
Returns: Vstr sections
Type: struct Vstr_sects *
Parameter[1]: Maximum number of the Vstr sections
Type[1]: unsigned int
Explanation:

This function will make a Vstr sections, or return NULL.

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_add()
Returns: TRUE on success and FALSE on failure
Type: 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 add the position and length to a Vstr section node at the end of the Vstr sections (Paramter[1]). If space is not available and (Paramter[1])->can_add_sz is TRUE, then space try to be allocated.

Function: vstr_sects_del()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr sections
Type[1]: struct Vstr_sects *
Parameter[2]: Number of the section in the Vstr sections (Parameter[1])
Type[2]: unsigned int
Explanation:

This function will delete a specified Vstr section node. If (Paramter[1])->can_del_sz is TRUE then space may be compated.

Function: vstr_sects_foreach()
Returns: Number of the times the foreach function ran the callback
Type: unsigned int
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Vstr sections
Type[2]: struct Vstr_sects *
Parameter[3]: Flags starting VSTR_FLAG_SECT_FOREACH_
Type[3]: unsigned int
Parameter[4]: Function to run as foreach body
Type[4]: unsigned int (*)(const Vstr_base *, size_t, size_t, void *)
Parameter[5]: Data to pass to foreach body function (Parameter[4])
Type[5]: void *
Explanation:

This function will run the foreach body function (Parameter[4]) on every valid Vstr section node in the Vstr sections.

Note:

The foreach callback body function returns types starting VSTR_TYPE_SECT_FOREACH_.

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.

This uses the vstr_cache_add() function.

Function: vstr_sects_update_del()
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]) that was previously updated when changes are made to the Vstr string (Parameter[1]) to not be updated anymore.

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_buf()
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 data to split on
Type[4]: const void *
Parameter[5]: Length of data (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 function is used to add section nodes to the Vstr sections (Parameter[6]) about the Vstr string (Parameter[1]). The function will add one section before each occurance of the data (Parameter[4]), and one final section for the rest of the Vstr string.

If the limit (Parameter[7]) is non-zero then ((Parameter[7]) - 1) occurances of the data will be searched for and one final section will be added for the rest of the Vstr string. This means that "a:b:c" if split on ":" with a limit of 2 will split into "a" and "b:c", and that "a::" if split on ":" with a limit of 2 will split into "a" and ":".

Function: vstr_split_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 function works like vstr_split_buf() except that instead of having to match all the data in the data buffer it matches any of the characters in the character buffer (Parameter[4]).

Function: VSTR_SPLIT_CSTR_BUF()
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 data to split on
Type[4]: const char *
Parameter[5]: Vstr sections
Type[5]: struct Vstr_sects *
Parameter[6]: Limit of sections to add to Vstr sections (Parameter[6])
Type[6]: unsigned int
Parameter[7]: Flags starting VSTR_FLAG_SPLIT_
Type[7]: unsigned int
Explanation:

This macro function calls vstr_split_buf() with the length being the value of strlen() on the data parameter (Parameter[4]).

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_short()
Returns: Number pared from Vstr string
Type: short
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range SHRT_MIN to SHRT_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_ushort()
Returns: Number pared from Vstr string
Type: unsigned short
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range 0 to USHRT_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_int()
Returns: Number pared from Vstr string
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range INT_MIN to INT_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_uint()
Returns: Number pared from Vstr string
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range 0 to UINT_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_long()
Returns: Number pared from Vstr string
Type: long
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range LONG_MIN to LONG_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_ulong()
Returns: Number pared from Vstr string
Type: unsigned long
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range 0 to ULONG_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

Function: vstr_parse_intmax()
Returns: Number pared from Vstr string
Type: intmax_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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range INTMAX_MIN to INTMAX_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

If the intmax_t type is unavailable on the platform, then this function will act the same as vstr_parse_long().

Function: vstr_parse_uintmax()
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]: Base to parse number in and flags starting VSTR_FLAG_PARSE_NUM_
Type[4]: unsigned int
Parameter[5]: Returns length of number (Return)
Type[5]: size_t *
Parameter[6]: Returns error code starting VSTR_TYPE_PARSE_NUM_ERR_
Type[6]: unsigned int *
Explanation:

This function will parse a number, in the range 0 to UINTMAX_MAX, from the start of a Vstr string.

The base that the number is parsed as is passed by specifying a number between 2 and 36 as part of the flags (Parameter[4]).

Note:

A base of 0 specifies that the base should be automatically detected, by choosing base 16 if the number starts 0x or 0X, base 8 if the number starts with a 0 and defaulting to base 10 otherwise.

If the intmax_t type is unavailable on the platform, then this function will act the same as vstr_parse_ulong().

Function: vstr_parse_netstr()
Returns: Returns the length of the netstring
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]: Returns the position of the start of the netstring data
Type[4]: size_t *
Parameter[5]: Returns the length of the data in the netstring
Type[5]: size_t *
Explanation:

This function is used to search forwards for the begining of a netstring in the Vstr string (Parameter[4]).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

If the data cannot be found 0 is returned.

Note:

The netstring is only found if it is "whole", in that the entire netstring and data exist in the Vstr string. If one is found but is not whole then the position of the start of data and the length of the netstring will still be returned.

Function: vstr_parse_netstr2()
Returns: Position in the Vstr string of the start of the netstring2
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]: Returns the position of the start of the netstring data
Type[4]: size_t *
Parameter[5]: Returns the length of the netstring
Type[5]: size_t *
Explanation:

This function is used to search forwards for the begining of a netstring in the Vstr string (Parameter[4]).

If the function can detect that the values of parameters are in error the function will return 0 to indicate an error.

If the data cannot be found 0 is returned.

Note:

The netstring is only found if it is "whole", in that the entire netstring and data exist in the Vstr string. If one is found but is not whole then the position of the start of data and the length of the netstring will still be returned.

The specification of a netstring2 is a superset of the specification of a netstring, so this function will find either.

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_add()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Parameter[3]: Function to use as callback from vstr_add_vfmt()
Type[3]: int (*)(struct Vstr_base *, size_t, struct Vstr_fmt_spec *)
Parameter[4]: List of VSTR_TYPE_FMT_* types for format specifier (Parameter[2])
Type[4]: ...
Explanation:

This function allows you to register arbitrary format specifiers for printing from vstr_fmt_vstr(). Note that these trigger off the user escape character, which may or may not be the same as the "system" escape character of '%'.

Note:

If the user escape character is '%', then you can override system specifiers by using a specifier name (Paramter[2]) of "i" etc. This isn't recommended, but is done so that you can have specifier names like "igloo" and it not be taken as a system specifier, however if you then did "%igoo" that would be interpreted as a "%i" (int) specification followed by the string "goo".

You can register multiple names with one callback, so you can register say "{Vstr}" and "{Vstr:%p%zu%zu%u}" ... the latter, with a user escape != '%', will do the right thing with current printf warning checks in gcc. We can all hope that the former will be as usable eventually.

Function: vstr_fmt_del()
Returns: Nothing
Type: void
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function allows you to deregister a format specifier added using vstr_fmt_add().

Function: vstr_fmt_srch()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function allows you to find out if a format specifier has been added using vstr_fmt_add().

Function: VSTR_FMT_CB_ARG_PTR()
Returns: Pointer to data
Type: void *
Parameter[1]: Format specifier passed to a callback of vstr_add_vfmt()
Type[1]: struct Vstr_fmt_spec *
Parameter[2]: Number of the parameter passed to the callback
Type[2]: size_t
Explanation:

This macro function returns the nth (Parameter[2]) parameter passed to a callback of vstr_add_vfmt(), as a generic pointer.

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_add()
Returns: Cookie reference for cache function
Type: unsigned int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Name of cache function
Type[2]: const char *
Parameter[3]: Function to use as callback from the cache
Type[3]: void *(*)(const struct Vstr_base *, size_t, size_t, unsigned int, void *)
Explanation:

This function will add the callback function (Parameter[3]) to the Vstr configuration for use in all Vstr strings that use the Vstr configuration and have a cache. The name of the cache function (Parameter[2]) should be unique, the vstr library uses names starting "/vstr__/".

Note:

The name of the cache function should be placed in permanent storage, Ie. only the pointer to the name will be stored so you cannot malloc() the name and then free() it after calling the function.

The callback function parameters, are the Vstr string, position, length, the type of callback starting VSTR_TYPE_CACHE_ and the data for the cache function.

The callback function will not be called if the data for the cache function is NULL.

The inline adding and delete from the Vstr strings is not performed if callbacks are registered for the string (because functions will have to be called anyway).

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:

This function will get the data for the cache function.

Function: vstr_cache_set()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: const struct Vstr_base *
Parameter[2]: Cookie reference for cache function
Type[2]: unsigned int
Parameter[3]: Data for cache function
Type[3]: void *
Explanation:

This function will set the data for the cache function.

Note:

The callback function will not be called if the data for the cache function is NULL.

Function: vstr_cache_srch()
Returns: Cookie reference for cache function
Type: unsigned int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Name of cache function
Type[2]: const char *
Explanation:

This function will find a cache function name (Parameter[2]) and return the cookie reference for use in the other cache functions.

Function: vstr_cache_cb_sub()
Returns: Nothing
Type: void
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:

If you are substituting data in a vstr (from an iovec export, followed by a readv for instance or changing the data in a mmap()'d area) then you can use this function to notify the vstr caching mechanisms.

Note:

This is a last resort function, to make the hard things possible, use the vstr_sub_*() functions instead.

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_basename()
Returns: Nothing
Type: void
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]: Position of basename (Return)
Type[4]: size_t *
Parameter[5]: Length of basename (Return)
Type[5]: size_t *
Explanation:

This function is a helper function to return the basename of a path. Unlike other implementations of this function nothing is allocated and altered in the original string

Note:

This function, with vstr_sc_dirname(), always returns values that can be combined to generate the original path. This means that this function will return an empty length for the path "/".

Function: vstr_sc_dirname()
Returns: Nothing
Type: void
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]: Length of dirname (Return)
Type[4]: size_t *
Explanation:

This function is a helper function to return the directory of a path, excluding the basename. Unlike other implementations of this function nothing is allocated and nothing is altered in the original string.

Note:

This function, with vstr_sc_basename(), always returns values that can be combined to generate the original path. This means that this function will return an empty length for a relative filename in the current cirectory.

Function: vstr_sc_fmt_cb_beg()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Position in the Vstr string (Parameter[1]), updated for padding.
Type[2]: size_t *
Parameter[3]: Format specifier passed to a callback of vstr_add_vfmt()
Type[3]: struct Vstr_fmt_spec *
Parameter[4]: Length of data you are going to add, updated due to precision.
Type[4]: size_t *
Parameter[5]: Flags starting VSTR_FLAG_SC_FMT_CB_BEG_*
Type[5]: unsigned int
Explanation:

This function is a helper function for any custom format specifiers you write, it takes care of truncation of length due to precision (on strings only) and printing initial output for numbers or strings.

Note:

If this function returns FALSE, you should probably just return from the callback with FALSE.

Function: vstr_sc_fmt_cb_end()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr string
Type[1]: struct Vstr_base *
Parameter[2]: Position you added your data to the Vstr (Parameter[1]).
Type[2]: size_t
Parameter[3]: Format specifier passed to a callback of vstr_add_vfmt()
Type[3]: struct Vstr_fmt_spec *
Parameter[4]: Length of data you added.
Type[4]: size_t
Explanation:

This function is a helper function for any custom format specifiers you write, it takes care of doing the standard transforms to your data after it is output as if you were printing a string.

Note:

You shouldn't alter the position between calling vstr_sc_fmt_cb_beg() and vstr_sc_fmt_cb_end(), if padding is added in vstr_sc_fmt_cb_end() it is added at position (Parameter[2]) + length (Parameter[4]).

If this function returns FALSE, you should probably just return from the callback with FALSE.

Function: vstr_sc_fmt_add_vstr()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print Vstr strings. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_PTR_VOID, VSTR_TYPE_FMT_SIZE_T, VSTR_TYPE_FMT_SIZE_T, VSTR_TYPE_FMT_UINT and VSTR_TYPE_FMT_END. These correspond to the last 4 arguments to vstr_add_vstr().

Note:

As you would expect the precision and field width values are used from the format, so the length of the Vstr string printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_buf()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a memory block. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_PTR_CHAR, VSTR_TYPE_FMT_SIZE_T and VSTR_TYPE_FMT_END. These correspond to the last 2 arguments to vstr_add_buf().

Note:

As you would expect the precision and field width values are used from the format, so the length of the memory block printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_ptr()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a memory block. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_PTR_CHAR, VSTR_TYPE_FMT_SIZE_T and VSTR_TYPE_FMT_END. These correspond to the last 2 arguments to vstr_add_ptr().

Note:

As you would expect the precision and field width values are used from the format, so the length of the memory block printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_non()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a memory block. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_SIZE_T and VSTR_TYPE_FMT_END. These correspond to the last argument to vstr_add_non().

Note:

As you would expect the precision and field width values are used from the format, so the length of the memory block printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_ref()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a memory block. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_SIZE_T, VSTR_TYPE_FMT_SIZE_T, VSTR_TYPE_FMT_PTR_VOID and VSTR_TYPE_FMT_END. These correspond to the last 3 arguments to vstr_add_ref().

Note:

As you would expect the precision and field width values are used from the format, so the length of the memory block printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_bkmg_Byte_uint()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a number in a human accessible form. Displaying either K, M or G after the number and before a "B" for bytes.

Note:

The precision specifies how many digits are included after the "whole" part of the number, the default precision is 2.

The padding of the number can be done with spaces or zero characters, and the '+' or ' ' modifiers will work as on unsigned ints.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_bkmg_Bytes_uint()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a number in a human accessible form. Displaying either K, M or G after the number and before a "B/s" for bytes per second.

Note:

The precision specifies how many digits are included after the "whole" part of the number, the default precision is 2.

The padding of the number can be done with spaces or zero characters, and the '+' or ' ' modifiers will work as on unsigned ints.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_bkmg_bit_uint()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a number in a human accessible form. Displaying either K, M or G after the number and before a "b" for bits.

Note:

The precision specifies how many digits are included after the "whole" part of the number, the default precision is 2.

The padding of the number can be done with spaces or zero characters, and the '+' or ' ' modifiers will work as on unsigned ints.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_bkmg_bits_uint()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print a number in a human accessible form. Displaying either K, M or G after the number and before a "b/s" for bits per second.

Note:

The precision specifies how many digits are included after the "whole" part of the number, the default precision is 2.

The padding of the number can be done with spaces or zero characters, and the '+' or ' ' modifiers will work as on unsigned ints.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_ipv4_ptr()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print ipv4 IP addresses from a struct in_addr *. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_PTR_VOID and VSTR_TYPE_FMT_END. This pointer is a struct in_addr *, to be passed to inet_ntop().

Note:

As you would expect the precision and field width values are used from the format, so the length of the string printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_fmt_add_ipv6_ptr()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Vstr configuration
Type[1]: struct Vstr_conf *
Parameter[2]: Specifier name, for use with vstr_add_vfmt()
Type[2]: const char *
Explanation:

This function is used to add a custom specifier function to print ipv4 IP addresses from a struct in6_addr *. It is equivalent to calling vstr_add_fmt() with the type arguments of VSTR_TYPE_FMT_PTR_VOID and VSTR_TYPE_FMT_END. This pointer is a struct in6_addr *, to be passed to inet_ntop().

Note:

As you would expect the precision and field width values are used from the format, so the length of the string printed is the lower bound of the length passed and the precision.

The function will return 0 if it needs to allocate memory and cannot do so.

Function: vstr_sc_mmap_fd()
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]: File descriptor
Type[3]: int
Parameter[4]: Offset to start map in file descriptor
Type[4]: off64_t
Parameter[5]: Size of map in file descriptor
Type[5]: size_t
Parameter[6]: Returns error code starting VSTR_TYPE_SC_MMAP_FD_ERR_
Type[6]: unsigned int *
Explanation:

This function is used to add a mmap()d mapping of data from a filedescriptor (Parameter[3]) at offset (Paramter[4]) and of size (Parameter[5]) to a Vstr string.

Note:

If the size (Parameter[5]) is zero, then then the size of the file is automatically worked out and the size (Parameter[5]) becomes the file size minus the offset (Parameter[4]).

Function: vstr_sc_mmap_file()
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]: Filename to add a mapping from
Type[3]: const char *
Parameter[4]: Offset to start map in file open()'d by filename
Type[4]: off64_t
Parameter[5]: Size of map in file open()'d by filename
Type[5]: size_t
Parameter[6]: Returns error code starting VSTR_TYPE_SC_MMAP_FILE_ERR_
Type[6]: unsigned int *
Explanation:

This function is used to add a mmap()d mapping of the entire data of filename (Parameter[3]) to a Vstr string.

Function: vstr_sc_read_iov_fd()
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]: File descriptor
Type[3]: int
Parameter[4]: Minimum ammount of nodes to read into
Type[4]: unsigned int
Parameter[5]: Maximum ammount of nodes to read into
Type[5]: unsigned int
Parameter[6]: Returns error code starting VSTR_TYPE_SC_READ_FD_ERR_
Type[6]: unsigned int *
Explanation:

This function is used to call vstr_add_iovec_buf_beg(), then readv() with the filedescriptor (Parameter[3]) and finally vstr_add_iovec_buf_end() before returning.

Function: vstr_sc_read_len_fd()
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]: File descriptor
Type[3]: int
Parameter[4]: Size of data to try to read
Type[4]: size_t
Parameter[5]: Returns error code starting VSTR_TYPE_SC_READ_FD_ERR_
Type[5]: unsigned int *
Explanation:

This function is used to call vstr_add_iovec_buf_beg(), then readv() with the filedescriptor got by opening the filename (Parameter[3]) and finally vstr_add_iovec_buf_end() before returning.

However the arguments to the vstr_add_iovec_buf_* calls are limited so that only upto size (Parameter[4]) data will be read.

If size (Parameter[4]) is zero then the entire file will try to be read.

Note:

As with all calls in the vstr library, this is a non-blocking call. If you need all of the data specified (Parameter[4]) then you'll need to loop.

Function: vstr_sc_read_iov_file()
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]: Filename to read from
Type[3]: const char *
Parameter[4]: Offset to start reading at
Type[4]: off64_t
Parameter[5]: Minimum ammount of nodes to read into
Type[5]: unsigned int
Parameter[6]: Maximum ammount of nodes to read into
Type[6]: unsigned int
Parameter[7]: Returns error code starting VSTR_TYPE_SC_READ_FILE_ERR_
Type[7]: unsigned int *
Explanation:

This function is used to call vstr_add_iovec_buf_beg(), then readv() with the filedescriptor (Parameter[3]) and finally vstr_add_iovec_buf_end() before returning.

Function: vstr_sc_read_len_file()
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]: Filename to read from
Type[3]: const char *
Parameter[4]: Offset to start reading at
Type[4]: off64_t
Parameter[5]: Size of data to try to read
Type[5]: size_t
Parameter[6]: Returns error code starting VSTR_TYPE_SC_READ_FILE_ERR_
Type[6]: unsigned int *
Explanation:

This function is used to call vstr_add_iovec_buf_beg(), then readv() with the filedescriptor got by opening the filename (Parameter[3]) and finally vstr_add_iovec_buf_end() before returning.

However the arguments to the vstr_add_iovec_buf_* calls are limited so that only upto exactly size (Parameter[4]) data will be read. If size (Parameter[5]) is zero then the entire file, minus the offset (Parameter[4]) will try and be read.

Note:

As with all calls in the vstr library, this is a non-blocking call. If you need all of the data specified (Parameter[5]) then you'll need to loop.

Function: vstr_sc_write_fd()
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[3]: File descriptor
Type[3]: int
Parameter[4]: Returns error code starting VSTR_TYPE_SC_WRITE_FD_ERR_
Type[4]: unsigned int *
Explanation:

This function is used to take data from a Vstr string and write it to a filedescriptor.

Note:

If the start position is 1, the length is (Parameter[1])->len and caching is available for the Vstr string the data will be exported as though vstr_export_iovec_ptr_all(), writev() and then vstr_del() were called.

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]).