Vstr documentation -- functions (345)

Index of sections

• Library initialization and exit functions (2)
• Exporting data functions (10)
• Memory reference functions (14)
• Creation/destruction of core objects (18)
• Adding and deleting of data functions (24)
• Substitution of data functions (12)
• Comparison of data functions (69)
• Searching for data functions (32)
• Span of data calculation functions (20)
• Convertion of data functions (6)
• Section of Vstr string functions (13)
• Splitting data into sections functions (6)
• Parsing data functions (13)
• Custom formatter functions (5)
• Short cut helper functions (77)
• Interator functions (7)
• Miscellaneous functions (17)

Index of sections, and their contents

• Library initialization and exit functions
  • vstr_init()
  • vstr_exit()
• Exporting data functions
  • vstr_export_cstr_ptr()
  • vstr_export_cstr_malloc()
  • vstr_export_cstr_buf()
  • vstr_export_cstr_ref()
  • vstr_export_iovec_ptr_all()
  • vstr_export_iovec_cpy_buf()
  • vstr_export_iovec_cpy_ptr()
  • vstr_export_buf()
  • vstr_export_chr()
  • vstr_export_ref()
• Memory reference functions
  • vstr_ref_add()
  • vstr_ref_del()
  • vstr_ref_cb_free_nothing()
  • vstr_ref_cb_free_ref()
  • vstr_ref_cb_free_ptr()
  • vstr_ref_cb_free_ptr_ref()
  • vstr_ref_make_malloc()
  • vstr_ref_make_ptr()
  • vstr_ref_make_memdup()
  • vstr_ref_make_strdup()
  • VSTR_REF_MAKE_STRDUP()
  • vstr_ref_make_vstr_base()
  • vstr_ref_make_vstr_conf()
  • vstr_ref_make_vstr_sects()
• Creation/destruction of core objects
  • vstr_make_conf()
  • vstr_free_conf()
  • vstr_make_base()
  • vstr_free_base()
  • vstr_dup_buf()
  • vstr_dup_ptr()
  • vstr_dup_non()
  • vstr_dup_ref()
  • vstr_dup_vstr()
  • vstr_dup_rep_chr()
  • vstr_dup_cstr_buf()
  • vstr_dup_cstr_ptr()
  • vstr_dup_cstr_ref()
  • VSTR_DUP_CSTR_BUF()
  • VSTR_DUP_CSTR_PTR()
  • VSTR_DUP_CSTR_REF()
  • vstr_make_spare_nodes()
  • vstr_free_spare_nodes()
• Adding and deleting of data functions
  • vstr_add_buf()
  • vstr_add_ptr()
  • vstr_add_non()
  • vstr_add_ref()
  • vstr_add_vstr()
  • vstr_add_rep_chr()
  • vstr_add_cstr_buf()
  • vstr_add_cstr_ptr()
  • vstr_add_cstr_ref()
  • VSTR_ADD_CSTR_BUF()
  • VSTR_ADD_CSTR_PTR()
  • VSTR_ADD_CSTR_REF()
  • vstr_add_vfmt()
  • vstr_add_fmt()
  • vstr_add_vsysfmt()
  • vstr_add_sysfmt()
  • vstr_add_iovec_buf_beg()
  • vstr_add_iovec_buf_end()
  • vstr_add_netstr_beg()
  • vstr_add_netstr_end()
  • vstr_add_netstr2_beg()
  • vstr_add_netstr2_end()
  • vstr_del()
  • vstr_mov()
• Substitution of data functions
  • vstr_sub_buf()
  • vstr_sub_ptr()
  • vstr_sub_non()
  • vstr_sub_ref()
  • vstr_sub_vstr()
  • vstr_sub_rep_chr()
  • vstr_sub_cstr_buf()
  • vstr_sub_cstr_ptr()
  • vstr_sub_cstr_ref()
  • VSTR_SUB_CSTR_BUF()
  • VSTR_SUB_CSTR_PTR()
  • VSTR_SUB_CSTR_REF()
• Comparison of data functions
  • vstr_cmp()
  • vstr_cmp_buf()
  • vstr_cmp_case()
  • vstr_cmp_case_buf()
  • vstr_cmp_fast()
  • vstr_cmp_fast_buf()
  • vstr_cmp_vers()
  • vstr_cmp_vers_buf()
  • vstr_cmp_eq()
  • vstr_cmp_cstr()
  • vstr_cmp_buf_eq()
  • vstr_cmp_cstr_eq()
  • vstr_cmp_case_eq()
  • vstr_cmp_case_cstr()
  • vstr_cmp_case_buf_eq()
  • vstr_cmp_case_cstr_eq()
  • vstr_cmp_fast_cstr()
  • vstr_cmp_vers_eq()
  • vstr_cmp_vers_cstr()
  • vstr_cmp_vers_buf_eq()
  • vstr_cmp_vers_cstr_eq()
  • vstr_cmp_bod()
  • vstr_cmp_eod()
  • vstr_cmp_bod_eq()
  • vstr_cmp_eod_eq()
  • vstr_cmp_bod_buf()
  • vstr_cmp_eod_buf()
  • vstr_cmp_bod_buf_eq()
  • vstr_cmp_eod_buf_eq()
  • vstr_cmp_bod_cstr()
  • vstr_cmp_eod_cstr()
  • vstr_cmp_bod_cstr_eq()
  • vstr_cmp_eod_cstr_eq()
  • vstr_cmp_case_bod()
  • vstr_cmp_case_eod()
  • vstr_cmp_case_bod_eq()
  • vstr_cmp_case_eod_eq()
  • vstr_cmp_case_bod_buf()
  • vstr_cmp_case_eod_buf()
  • vstr_cmp_case_bod_buf_eq()
  • vstr_cmp_case_eod_buf_eq()
  • vstr_cmp_case_bod_cstr()
  • vstr_cmp_case_eod_cstr()
  • vstr_cmp_case_bod_cstr_eq()
  • vstr_cmp_case_eod_cstr_eq()
  • vstr_cmp_vers_bod()
  • vstr_cmp_vers_eod()
  • vstr_cmp_vers_bod_eq()
  • vstr_cmp_vers_eod_eq()
  • vstr_cmp_vers_bod_buf()
  • vstr_cmp_vers_eod_buf()
  • vstr_cmp_vers_bod_buf_eq()
  • vstr_cmp_vers_eod_buf_eq()
  • vstr_cmp_vers_bod_cstr()
  • vstr_cmp_vers_eod_cstr()
  • vstr_cmp_vers_bod_cstr_eq()
  • vstr_cmp_vers_eod_cstr_eq()
  • VSTR_CMP_EQ()
  • VSTR_CMP_CSTR()
  • VSTR_CMP_BUF_EQ()
  • VSTR_CMP_CSTR_EQ()
  • VSTR_CMP_CASE_EQ()
  • VSTR_CMP_CASE_CSTR()
  • VSTR_CMP_CASE_BUF_EQ()
  • VSTR_CMP_CASE_CSTR_EQ()
  • VSTR_CMP_VERS_EQ()
  • VSTR_CMP_VERS_CSTR()
  • VSTR_CMP_VERS_BUF_EQ()
  • VSTR_CMP_VERS_CSTR_EQ()
• Searching for data functions
  • vstr_srch_chr_fwd()
  • vstr_srch_chr_rev()
  • vstr_srch_chrs_fwd()
  • vstr_srch_chrs_rev()
  • vstr_csrch_chrs_fwd()
  • vstr_csrch_chrs_rev()
  • vstr_srch_buf_fwd()
  • vstr_srch_buf_rev()
  • vstr_srch_vstr_fwd()
  • vstr_srch_vstr_rev()
  • vstr_srch_case_chr_fwd()
  • vstr_srch_case_chr_rev()
  • vstr_srch_case_buf_fwd()
  • vstr_srch_case_buf_rev()
  • vstr_srch_case_vstr_fwd()
  • vstr_srch_case_vstr_rev()
  • vstr_srch_cstr_buf_fwd()
  • vstr_srch_cstr_buf_rev()
  • vstr_srch_cstr_chrs_fwd()
  • vstr_srch_cstr_chrs_rev()
  • vstr_csrch_cstr_chrs_fwd()
  • vstr_csrch_cstr_chrs_rev()
  • vstr_srch_case_cstr_buf_fwd()
  • vstr_srch_case_cstr_buf_rev()
  • VSTR_SRCH_CSTR_BUF_FWD()
  • VSTR_SRCH_CSTR_BUF_REV()
  • VSTR_SRCH_CSTR_CHRS_FWD()
  • VSTR_SRCH_CSTR_CHRS_REV()
  • VSTR_CSRCH_CSTR_CHRS_FWD()
  • VSTR_CSRCH_CSTR_CHRS_REV()
  • VSTR_SRCH_CASE_CSTR_BUF_FWD()
  • VSTR_SRCH_CASE_CSTR_BUF_REV()
• Span of data calculation functions
  • vstr_spn_bmap_eq_fwd()
  • vstr_spn_bmap_eq_rev()
  • vstr_spn_bmap_and_fwd()
  • vstr_spn_bmap_and_rev()
  • vstr_spn_chrs_fwd()
  • vstr_spn_chrs_rev()
  • vstr_cspn_bmap_eq_fwd()
  • vstr_cspn_bmap_eq_rev()
  • vstr_cspn_bmap_and_fwd()
  • vstr_cspn_bmap_and_rev()
  • vstr_cspn_chrs_fwd()
  • vstr_cspn_chrs_rev()
  • vstr_spn_cstr_chrs_fwd()
  • vstr_spn_cstr_chrs_rev()
  • vstr_cspn_cstr_chrs_fwd()
  • vstr_cspn_cstr_chrs_rev()
  • VSTR_SPN_CSTR_CHRS_FWD()
  • VSTR_SPN_CSTR_CHRS_REV()
  • VSTR_CSPN_CSTR_CHRS_FWD()
  • VSTR_CSPN_CSTR_CHRS_REV()
• Convertion of data functions
  • vstr_conv_lowercase()
  • vstr_conv_uppercase()
  • vstr_conv_unprintable_chr()
  • vstr_conv_unprintable_del()
  • vstr_conv_encode_uri()
  • vstr_conv_decode_uri()
• Section of Vstr string functions
  • VSTR_SECTS_DECL()
  • VSTR_SECTS_EXTERN_DECL()
  • VSTR_SECTS_DECL_INIT()
  • VSTR_SECTS_INIT()
  • VSTR_SECTS_NUM()
  • vstr_sects_make()
  • vstr_sects_free()
  • vstr_sects_add()
  • vstr_sects_del()
  • vstr_sects_foreach()
  • vstr_sects_update_add()
  • vstr_sects_update_del()
  • vstr_sects_srch()
• Splitting data into sections functions
  • vstr_split_buf()
  • vstr_split_chrs()
  • vstr_split_cstr_buf()
  • vstr_split_cstr_chrs()
  • VSTR_SPLIT_CSTR_BUF()
  • VSTR_SPLIT_CSTR_CHRS()
• Parsing data functions
  • vstr_parse_num()
  • vstr_parse_short()
  • vstr_parse_ushort()
  • vstr_parse_int()
  • vstr_parse_uint()
  • vstr_parse_long()
  • vstr_parse_ulong()
  • vstr_parse_intmax()
  • vstr_parse_uintmax()
  • vstr_parse_netstr()
  • vstr_parse_netstr2()
  • vstr_parse_ipv4()
  • vstr_parse_ipv6()
• Custom formatter functions
  • vstr_fmt_add()
  • vstr_fmt_del()
  • vstr_fmt_srch()
  • VSTR_FMT_CB_ARG_PTR()
  • VSTR_FMT_CB_ARG_VAL()
• Short cut helper functions
  • vstr_sc_bmap_init_eq_spn_buf()
  • vstr_sc_bmap_init_eq_spn_cstr()
  • vstr_sc_bmap_init_or_spn_buf()
  • vstr_sc_bmap_init_or_spn_cstr()
  • vstr_sc_posdiff()
  • VSTR_SC_POSDIFF()
  • vstr_sc_poslast()
  • VSTR_SC_POSLAST()
  • vstr_sc_reduce()
  • vstr_sc_basename()
  • vstr_sc_add_grpbasenum_buf()
  • vstr_sc_add_grpbasenum_ptr()
  • vstr_sc_add_grpbasenum_ref()
  • vstr_sc_add_grpnum_buf()
  • vstr_sc_add_cstr_grpbasenum_buf()
  • vstr_sc_add_cstr_grpbasenum_ptr()
  • vstr_sc_add_cstr_grpbasenum_ref()
  • VSTR_SC_ADD_CSTR_GRPBASENUM_BUF()
  • VSTR_SC_ADD_CSTR_GRPBASENUM_PTR()
  • VSTR_SC_ADD_CSTR_GRPBASENUM_REF()
  • vstr_sc_add_cstr_grpnum_buf()
  • VSTR_SC_ADD_CSTR_GRPNUM_BUF()
  • vstr_sc_conv_num_uint()
  • vstr_sc_conv_num10_uint()
  • vstr_sc_conv_num_ulong()
  • vstr_sc_conv_num10_ulong()
  • vstr_sc_conv_num_size()
  • vstr_sc_conv_num10_size()
  • vstr_sc_conv_num_uintmax()
  • vstr_sc_conv_num10_uintmax()
  • vstr_sc_dirname()
  • vstr_sc_fmt_cb_beg()
  • vstr_sc_fmt_cb_end()
  • vstr_sc_fmt_add_vstr()
  • vstr_sc_fmt_add_buf()
  • vstr_sc_fmt_add_ptr()
  • vstr_sc_fmt_add_non()
  • vstr_sc_fmt_add_ref()
  • vstr_sc_fmt_add_rep_chr()
  • vstr_sc_fmt_add_bkmg_Byte_uint()
  • vstr_sc_fmt_add_bkmg_Bytes_uint()
  • vstr_sc_fmt_add_bkmg_bit_uint()
  • vstr_sc_fmt_add_bkmg_bits_uint()
  • vstr_sc_fmt_add_bkmg_Byte_uintmax()
  • vstr_sc_fmt_add_bkmg_Bytes_uintmax()
  • vstr_sc_fmt_add_bkmg_bit_uintmax()
  • vstr_sc_fmt_add_bkmg_bits_uintmax()
  • vstr_sc_fmt_add_ipv4_ptr()
  • vstr_sc_fmt_add_ipv6_ptr()
  • vstr_sc_fmt_add_ipv4_vec()
  • vstr_sc_fmt_add_ipv6_vec()
  • vstr_sc_fmt_add_ipv4_vec_cidr()
  • vstr_sc_fmt_add_ipv6_vec_cidr()
  • vstr_sc_fmt_add_upper_base2_uint()
  • vstr_sc_fmt_add_upper_base2_ulong()
  • vstr_sc_fmt_add_upper_base2_size()
  • vstr_sc_fmt_add_upper_base2_uintmax()
  • vstr_sc_fmt_add_lower_base2_uint()
  • vstr_sc_fmt_add_lower_base2_ulong()
  • vstr_sc_fmt_add_lower_base2_size()
  • vstr_sc_fmt_add_lower_base2_uintmax()
  • vstr_sc_fmt_add_all()
  • VSTR_SC_FMT_ADD()
  • vstr_sc_mmap_fd()
  • vstr_sc_mmap_file()
  • vstr_sc_read_iov_fd()
  • vstr_sc_read_len_fd()
  • vstr_sc_read_iov_file()
  • vstr_sc_read_len_file()
  • vstr_sc_write_fd()
  • vstr_sc_write_file()
  • vstr_sc_add_b_uint16()
  • vstr_sc_add_b_uint32()
  • vstr_sc_sub_b_uint16()
  • vstr_sc_sub_b_uint32()
  • vstr_sc_parse_b_uint16()
  • vstr_sc_parse_b_uint32()
• Interator functions
  • vstr_iter_fwd_beg()
  • vstr_iter_fwd_nxt()
  • vstr_iter_fwd_chr()
  • vstr_iter_fwd_buf()
  • vstr_iter_fwd_cstr()
  • vstr_iter_pos()
  • vstr_iter_len()
• Miscellaneous functions
  • vstr_cntl_opt()
  • vstr_cntl_base()
  • vstr_cntl_conf()
  • VSTR_FLAGXX()
  • vstr_num()
  • vstr_cache_add()
  • vstr_cache_get()
  • vstr_cache_set()
  • vstr_cache_srch()
  • vstr_cache_cb_sub()
  • vstr_cache_cb_free()
  • vstr_data_add()
  • vstr_data_srch()
  • vstr_data_del()
  • vstr_data_get()
  • vstr_data_set()
  • vstr_swap_conf()

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

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

This function can be called before exit, after all vstr objects have been freed, to cleanup data allocated internally in the Vstr library.

The function isn't needed but helps make sure there are no memory leaks, when used with a memory checker (or with the internal memory checker in the debug build).

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.

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.

This data needs to be cached in the Vstr string, and so can only work if the Vstr string has the ability to cache data (see VSTR_CNTL_BASE_GET_FLAG_HAVE_CACHE). If you want to make sure that the cached data is gone from the Vstr string, cache then you can call vstr_cache_cb_free() on the cookie from "/vstr__/cstr".

Any _NON data in the Vstr will be uninitialized 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 style string functions.

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.

Any _NON data in the Vstr will be uninitialized 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.

This function is used to export a copy of the data in the Vstr string to a data array, the maximum amount 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).

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.

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

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

Any _NON data in the Vstr will be uninitialized 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.

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.

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). However if you do alter the data then you'll need to do vstr_cache_cb_sub().

Either of the pointers for the iovec array (Parameter[2]) or the number of iovecs (Parameter[3]) can be the NULL pointer, in which case nothing will be written to those pointers.

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.

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.

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.

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

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.

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

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

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

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

Any _NON data in the Vstr will be uninitialized data in the memory pointed to by the memory reference.

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

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.

This function does nothing.

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

This will call free() on the data in the Vstr_ref (Parameter[1])->ptr (unless the passed reference is the NULL pointer, then it does nothing).

This will call free() on the data in the Vstr_ref (Parameter[1])->ptr and then call free() on the Vstr_ref (Parameter[1]) (unless the passed reference is the NULL pointer, then it does nothing).

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 the cleanup function will point to a function to free both the reference and the copy of memory.

This function will call malloc() to 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]).

This function will create a Vstr memory reference. The Vstr memory reference will have a reference count of 1 and a copy of the memory pointed to by (Parameter[1]) of length (Parameter[2]) will be the pointer value. The cleanup function will point to a function to free both the reference and the copy of memory.

This function calls vstr_ref_make_memdup() with the length being the value of (strlen() + 1) on the data parameter (Parameter[1]).

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

This function will create a Vstr memory reference. The Vstr memory reference will have a reference count of 1, a pointer value of the Vstr string (Parameter[1]). The cleanup function will point to a function to free both the reference and the Vstr string.

This function will create a Vstr memory reference. The Vstr memory reference will have a reference count of 1, a pointer value of the Vstr configuration (Parameter[1]). The cleanup function will point to a function to free both the reference and the Vstr configuration.

This function will create a Vstr memory reference. The Vstr memory reference will have a reference count of 1, a pointer value of the Vstr sections (Parameter[1]). The cleanup function will point to a function to free both the reference and the Vstr sections.

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

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

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

If the configuration (Parameter[1]) is NULL, then the global configuration is used.

If there are spare base objects, then no allocations are done.

This function will free a Vstr string, allocated by vstr_make_base().

If the base object VSTR_CNTL_BASE_GET_TYPE_GRPALLOC_CACHE is of the same type as it's configurations VSTR_CNTL_CONF_GET_TYPE_GRPALLOC_CACHE, then the base object will be turned into a spare object so it can be reused by vstr_make_base().

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

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

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

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

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

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

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

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

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

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

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

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

This function will try and create a number (Parameter[3]) of nodes of type (Parameter[2]).

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.

If the configuration (Parameter[1]) is NULL, then the global configuration is used.

This function will try and destroy a number (Parameter[3]) of nodes of type (Parameter[2]).

The number of nodes destroyed 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]).

If the configuration (Parameter[1]) is NULL, then the global configuration is used.

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

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

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.

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

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

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

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.

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

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

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

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

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

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

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

This function works like calling vsprintf() directly into a Vstr string, however this is a portable implementation 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).

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 implementation system bugs of inaccuracy 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().

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

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

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

This function is used to add a copy of data directly into the Vstr string, the amount 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 is 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).

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

It is currently believed that, on Linux, doing disk IO in amounts greater than 8k gives little real performance improvement. This can be converted into iovec numbers by using a formula like...

    min = (8k / buf_sz) + 2;
    max = min + (min / 2);    

...where the +2 is due to both the extra space at the end of the current last node, and rounding errors due to the division. The max being slightly bigger is an attempt to make the constant overhead of the call slightly less, and may not be useful. It is very possible that some kind of dynamic scaling of the values would result in the best performance, however the solution to that doesn't fit in the margin :).

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

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.

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.

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.

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

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.

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.

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 beginning of a netstring2, this is incompatible 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 beginning/middle.

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

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.

Deleting the entire Vstr string and deleting from the beginning onward are faster operations than a generic delete. They also never require allocating memory and so the return value can be ignored.

This function is used to move data, deleting 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).

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

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

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

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

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

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

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

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

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

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.

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

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