bglibs: str: Dynamically allocated string library.

- Main Page
- Modules
- Data Structures
- Files
- Directories
- Related Pages
- Examples

# str: Dynamically allocated string library.

## Data Structures
struct | str
struct | str_sortentry
## Overhead Functions
#define | str_ready(S, SZ) str_alloc(S,SZ,0)
#define | str_realloc(S, SZ) str_alloc(S,SZ,1)
int | str_init (str *s)
int | str_alloc (str *s, unsigned size, int copy)
void | str_free (str *s)
int | str_truncate (str *s, unsigned len)
## In-place Modification Functions
#define | str_strip(S) (str_rstrip(S), str_lstrip(S))
void | str_lower (str *s)
void | str_upper (str *s)
long | str_subst (str *s, char from, char to)
void | str_lstrip (str *s)
void | str_rstrip (str *s)
void | str_lcut (str *s, unsigned count)
void | str_rcut (str *s, unsigned count)
int | str_sort (str *s, char sep, long count, int(*fn)(const str_sortentry *a, const str_sortentry *b))
int | str_splice (str *s, unsigned start, unsigned len, const str *r)
int | str_splices (str *s, unsigned start, unsigned len, const char *r)
int | str_spliceb (str *s, unsigned start, unsigned len, const char *r, unsigned rlen)
long | str_xlate (str *s, const char *from, const char *to, unsigned nchars)
## Searching Functions
#define | str_findfirst(S, C) str_findnext(S,C,0)
#define | str_findfirstof(S, L) str_findnextof(S,L,0)
#define | str_findfirstnot(S, L) str_findnextnot(S,L,0)
#define | str_findlast(S, C) str_findprev(S,C,-1)
#define | str_findlastof(S, L) str_findprevof(S,L,-1)
#define | str_findlastnot(S, L) str_findprevof(S,L,-1)
void | str_buildmap (int map[256], const char *list)
unsigned | str_count (const str *s, char ch)
unsigned | str_countof (const str *s, const char *list)
int | str_findnext (const str *s, char ch, unsigned pos)
int | str_findnextof (const str *s, const char *list, unsigned pos)
int | str_findnextnot (const str *s, const char *list, unsigned pos)
int | str_findprev (const str *s, char ch, unsigned pos)
int | str_findprevof (const str *s, const char *list, unsigned pos)
int | str_findprevnot (const str *s, const char *list, unsigned pos)
## Assignment Functions
int | str_copy (str *s, const str *in)
int | str_copys (str *s, const char *in)
int | str_copyb (str *s, const char *in, unsigned len)
int | str_copyf (str *s, const char *format,...)
int | str_copyfv (str *s, const char *format, va_list ap)
int | str_copyns (str *s, unsigned int count,...)
int | str_copy2s (str *s, const char *a, const char *b)
int | str_copy3s (str *s, const char *a, const char *b, const char *c)
int | str_copy4s (str *s, const char *a, const char *b, const char *c, const char *d)
int | str_copy5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
int | str_copy6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)
## Appending Functions
int | str_cat (str *s, const str *in)
int | str_cats (str *s, const char *in)
int | str_catc (str *s, char in)
int | str_catb (str *s, const char *in, unsigned len)
int | str_catf (str *s, const char *format,...)
int | str_catfv (str *s, const char *format, va_list ap)
int | str_cati (str *s, long in)
int | str_catiw (str *s, long in, unsigned width, char pad)
int | str_catu (str *s, unsigned long in)
int | str_catuw (str *s, unsigned long in, unsigned width, char pad)
int | str_catx (str *s, unsigned long in)
int | str_catxw (str *s, unsigned long in, unsigned width, char pad)
int | str_catill (str *s, long long in)
int | str_catiwll (str *s, long long in, unsigned width, char pad)
int | str_catull (str *s, unsigned long long in)
int | str_catuwll (str *s, unsigned long long in, unsigned width, char pad)
int | str_catxll (str *s, unsigned long long in)
int | str_catxwll (str *s, unsigned long long in, unsigned width, char pad)
int | str_catsnumw (str *s, long in, unsigned width, char pad, unsigned base, const char *digits)
int | str_catunumw (str *s, unsigned long in, unsigned width, char pad, unsigned base, const char *digits)
int | str_catsllnumw (str *s, long long in, unsigned width, char pad, unsigned base, const char *digits)
int | str_catullnumw (str *s, unsigned long long in, unsigned width, char pad, unsigned base, const char *digits)
int | str_catns (str *s, unsigned int count,...)
int | str_cat2s (str *s, const char *a, const char *b)
int | str_cat3s (str *s, const char *a, const char *b, const char *c)
int | str_cat4s (str *s, const char *a, const char *b, const char *c, const char *d)
int | str_cat5s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e)
int | str_cat6s (str *s, const char *a, const char *b, const char *c, const char *d, const char *e, const char *f)
int | str_join (str *s, char sep, const str *t)
int | str_joins (str *s, char sep, const char *in)
int | str_joinb (str *s, char sep, const char *in, unsigned len)
## Comparison Functions
int | str_cmp (const str *a, unsigned aoffset, const str *b, unsigned boffset)
int | str_cmps (const str *a, unsigned offset, const char *b)
int | str_cmpb (const str *a, unsigned offset, const char *b, unsigned len)
int | str_diff (const str *a, const str *b)
int | str_diffs (const str *a, const char *b)
int | str_diffb (const str *a, const char *b, unsigned len)
int | str_start (const str *a, const str *b)
int | str_starts (const str *a, const char *b)
int | str_startb (const str *a, const char *b, unsigned len)
int | str_case_start (const str *a, const str *b)
int | str_case_starts (const str *a, const char *b)
int | str_case_startb (const str *a, const char *b, unsigned len)
## Pattern Matching Functions
int | str_match (const str *s, const str *pattern)
int | str_matchb (const str *s, const char *pptr, unsigned plen)
int | str_matchs (const str *s, const char *pattern)
int | str_case_match (const str *s, const str *pattern)
int | str_case_matchb (const str *s, const char *pptr, unsigned plen)
int | str_case_matchs (const str *s, const char *pattern)
int | str_glob (const str *s, const str *pattern)
int | str_globb (const str *s, const char *pptr, unsigned plen)
int | str_globs (const str *s, const char *pattern)
int | str_case_glob (const str *s, const str *pattern)
int | str_case_globb (const str *s, const char *pptr, unsigned plen)
int | str_case_globs (const str *s, const char *pattern)
## Globals
const char | str_lcase_digits [36]
const char | str_ucase_digits [36]
## Defines
#define | STR_BLOCKSIZE 16
## Typedefs
typedef str | str
typedef str_sortentry | str_sortentry

## Detailed Description

Calling Convention
  The standard calling convention to `str` functions is to pass the string being examined or modified as the first argument. For most functions, the return value will be `0` (false) if an error occurred (ie memory allocation failed) and non-zero (true) otherwise.

## Define Documentation

#define STR_BLOCKSIZE 16

The block size in which string memory is allocated.

`STR_BLOCKSIZE` should be set to at least the size at which the allocator (ie `malloc`) will align the data it returns. String data will be allocated in steps of this number. Values smaller than the alignment will only cause a small amount of space to be wasted, and will not trigger bugs.

#define str_ready | ( | S,
|  | SZ |  | ) | str_alloc(S,SZ,0)

Make sure string S has at least SZ bytes ready (no copy)

#define str_realloc | ( | S,
|  | SZ |  | ) | str_alloc(S,SZ,1)

Reallocate string S to size SZ bytes, copying the existing string

## Typedef Documentation

typedef struct str str

String structure typedef.

typedef struct str_sortentry str_sortentry

String sort entry typedef.

## Function Documentation

int str_alloc | ( | str * | s,
|  | unsigned | size,
|  | int | copy |
| ) |  |  |

Allocate storage for a string.

Parameters:

  | s | String to modify.
  | size | Minimum number of bytes for which to allocate.
  | copy | If set, the existing string will be copied into the new string.

The size given is incremented to account for adding a trailing `NUL` byte (to ensure compatibility with C string functions) and is then rounded up to the nearest `STR_BLOCKSIZE` interval.

void str_buildmap | ( | int | map[256],
|  | const char * | list |
| ) |  |  |

Build a map from the list of characters.

Each byte in the output map contains either `-1` if the corresponding character was not present in the input string, or the offset of the last instance of the character in the list.

int str_case_match | ( | const str * | s,
|  | const str * | pattern |
| ) |  |  |

Simple pattern match on dynamic string pattern.

int str_case_matchb | ( | const str * | s,
|  | const char * | pptr,
|  | unsigned | plen |
| ) |  |  |

Simple but fast (linear time) pattern matching on binary pattern.

int str_case_matchs | ( | const str * | s,
|  | const char * | pattern |
| ) |  |  |

Simple pattern match on C string pattern.

int str_case_start | ( | const str * | a,
|  | const str * | b |
| ) |  |  |

Match the prefix of the string to another string.

int str_case_startb | ( | const str * | a,
|  | const char * | b,
|  | unsigned | len |
| ) |  |  |

Match the prefix of the string to a binary chunk.

int str_case_starts | ( | const str * | a,
|  | const char * | b |
| ) |  |  |

Match the prefix of the string to a C string.

int str_cat | ( | str * | s,
|  | const str * | in |
| ) |  |  |

Append another string

int str_cat2s | ( | str * | s,
|  | const char * | a,
|  | const char * | b |
| ) |  |  |

Append 2 C strings

int str_cat3s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c |
| ) |  |  |

Append 3 C strings

int str_cat4s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d |
| ) |  |  |

Append 4 C strings

int str_cat5s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d,
|  | const char * | e |
| ) |  |  |

Append 5 C strings

int str_cat6s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d,
|  | const char * | e,
|  | const char * | f |
| ) |  |  |

Append 6 C strings

int str_catb | ( | str * | s,
|  | const char * | in,
|  | unsigned | len |
| ) |  |  |

Append a binary block

int str_catc | ( | str * | s,
|  | char | in |
| ) |  |  |

Append a single character

int str_catf | ( | str * | s,
|  | const char * | format,
|  |  | ... |
| ) |  |  |

Append formatted data using `fmt_multi` from variable arguments

int str_catfv | ( | str * | s,
|  | const char * | format,
|  | va_list | ap |
| ) |  |  |

Append formatted data using `fmt_multi` from a `va_list`

int str_cati | ( | str * | s,
|  | long | in |
| ) |  |  |

Append a signed integer in decimal.

int str_catill | ( | str * | s,
|  | long long | in |
| ) |  |  |

Append a signed long long integer in decimal.

int str_catiw | ( | str * | s,
|  | long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append a signed integer in decimal, padded to a minimum width.

int str_catiwll | ( | str * | s,
|  | long long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append a signed long long integer in decimal, padded to a minimum width.

int str_catns | ( | str * | s,
|  | unsigned int | count,
|  |  | ... |
| ) |  |  |

Append N C strings

int str_cats | ( | str * | s,
|  | const char * | in |
| ) |  |  |

Append a C string

int str_catsllnumw | ( | str * | s,
|  | long long | in,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits |
| ) |  |  |

Append a signed long long integer, optionally padded to a minimum width

int str_catsnumw | ( | str * | s,
|  | long | in,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits |
| ) |  |  |

Append a signed integer, optionally padded to a minimum width

int str_catu | ( | str * | s,
|  | unsigned long | in |
| ) |  |  |

Append an unsigned integer in decimal, padded to a minimum width.

int str_catull | ( | str * | s,
|  | unsigned long long | in |
| ) |  |  |

Append an unsigned long long integer in decimal.

int str_catullnumw | ( | str * | s,
|  | unsigned long long | in,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits |
| ) |  |  |

Append an unsigned long long integer, optionally padded to a minimum width

int str_catunumw | ( | str * | s,
|  | unsigned long | in,
|  | unsigned | width,
|  | char | pad,
|  | unsigned | base,
|  | const char * | digits |
| ) |  |  |

Append an unsigned integer, optionally padded to a minimum width

int str_catuw | ( | str * | s,
|  | unsigned long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append an unsigned integer in decimal.

int str_catuwll | ( | str * | s,
|  | unsigned long long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append an unsigned long long integer in decimal, padded to a minimum width.

int str_catx | ( | str * | s,
|  | unsigned long | in |
| ) |  |  |

Append an unsigned integer in hexadecimal, padded to a minimum width.

int str_catxll | ( | str * | s,
|  | unsigned long long | in |
| ) |  |  |

Append an unsigned long long integer in hexadecimal.

int str_catxw | ( | str * | s,
|  | unsigned long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append an unsigned integer in hexadecimal.

int str_catxwll | ( | str * | s,
|  | unsigned long long | in,
|  | unsigned | width,
|  | char | pad |
| ) |  |  |

Append an unsigned long long integer in hexadecimal, padded to a minimum width.

int str_cmp | ( | const str * | a,
|  | unsigned | aoffset,
|  | const str * | b,
|  | unsigned | boffset |
| ) |  |  |

Compare part of two strings.

This function compares two strings, starting at `aoffset` bytes into `a` and `boffset` bytes into `b`. The first non-zero difference is returned. If the portion of `b` is longer than the portion of `a`, the result is positive.

int str_cmpb | ( | const str * | a,
|  | unsigned | offset,
|  | const char * | b,
|  | unsigned | len |
| ) |  |  |

Compare a string against a binary block.

int str_cmps | ( | const str * | a,
|  | unsigned | offset,
|  | const char * | b |
| ) |  |  |

Compare a string against a C string.

int str_copy | ( | str * | s,
|  | const str * | in |
| ) |  |  |

Copy in a string

int str_copy2s | ( | str * | s,
|  | const char * | a,
|  | const char * | b |
| ) |  |  |

Copy in the concatenation of 2 C strings

int str_copy3s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c |
| ) |  |  |

Copy in the concatenation of 3 C strings

int str_copy4s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d |
| ) |  |  |

Copy in the concatenation of 4 C strings

int str_copy5s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d,
|  | const char * | e |
| ) |  |  |

Copy in the concatenation of 5 C strings

int str_copy6s | ( | str * | s,
|  | const char * | a,
|  | const char * | b,
|  | const char * | c,
|  | const char * | d,
|  | const char * | e,
|  | const char * | f |
| ) |  |  |

Copy in the concatenation of 6 C strings

int str_copyb | ( | str * | s,
|  | const char * | in,
|  | unsigned | len |
| ) |  |  |

Copy in a binary block

int str_copyf | ( | str * | s,
|  | const char * | format,
|  |  | ... |
| ) |  |  |

Copy formatted data using `fmt_multi` from variable arguments

int str_copyfv | ( | str * | s,
|  | const char * | format,
|  | va_list | ap |
| ) |  |  |

Copy formatted data using `fmt_multi` from a `va_list`

int str_copyns | ( | str * | s,
|  | unsigned int | count,
|  |  | ... |
| ) |  |  |

Copy in the concatenation of N C strings

int str_copys | ( | str * | s,
|  | const char * | in |
| ) |  |  |

Copy in a C string

unsigned str_count | ( | const str * | s,
|  | char | ch |
| ) |  |  |

Count the number of instances of a character

unsigned str_countof | ( | const str * | s,
|  | const char * | list |
| ) |  |  |

Count the number of instances of a list of characters

int str_diff | ( | const str * | a,
|  | const str * | b |
| ) |  |  |

Differentiate two strings.

The first non-zero difference between `a` and `b` is returned. If `a` is longer than `b` and no differences are found up to the length of `b`, then the return value is positive. If `b` is longer than `a` and no differences are found up to the length of `a`, then the return value is negative.

int str_diffb | ( | const str * | a,
|  | const char * | b,
|  | unsigned | len |
| ) |  |  |

Differentiate a string and a binary block.

int str_diffs | ( | const str * | a,
|  | const char * | b |
| ) |  |  |

Differentiate a string and a C string.

int str_findnext | ( | const str * | s,
|  | char | ch,
|  | unsigned | pos |
| ) |  |  |

Find the next instance of the given character, on or after `pos`

int str_findnextnot | ( | const str * | s,
|  | const char * | list,
|  | unsigned | pos |
| ) |  |  |

Find the next instance of a character not in the given list of characters, on or after `pos`

int str_findnextof | ( | const str * | s,
|  | const char * | list,
|  | unsigned | pos |
| ) |  |  |

Find the next instance of the given list of characters, on or after `pos`

int str_findprev | ( | const str * | s,
|  | char | ch,
|  | unsigned | pos |
| ) |  |  |

Find the previous instance of the given character on or before `pos`

int str_findprevnot | ( | const str * | s,
|  | const char * | list,
|  | unsigned | pos |
| ) |  |  |

Find the previous instance of a character not in the given list of characters, on or before `pos`

int str_findprevof | ( | const str * | s,
|  | const char * | list,
|  | unsigned | pos |
| ) |  |  |

Find the previous instance of the given list of characters, on or before `pos`

void str_free | ( | str * | s | ) |

Free a string's storage. This function also sets all the members of the structure to zero.

int str_init | ( | str * | s | ) |

Initialize a string, giving it a small empty allocation.

int str_join | ( | str * | s,
|  | char | sep,
|  | const str * | in |
| ) |  |  |

Join two strings together with exactly one instance of the seperator.

int str_joinb | ( | str * | s,
|  | char | sep,
|  | const char * | in,
|  | unsigned | len |
| ) |  |  |

Join a binary block to this string

int str_joins | ( | str * | s,
|  | char | sep,
|  | const char * | in |
| ) |  |  |

Join a C string to this string

void str_lcut | ( | str * | s,
|  | unsigned | count |
| ) |  |  |

Cut `count` bytes from the left (front) of the string

void str_lower | ( | str * | s | ) |

Translate all upper-case characters to lower-case

void str_lstrip | ( | str * | s | ) |

Strip all white space from the left (front) of the string

int str_match | ( | const str * | s,
|  | const str * | pattern |
| ) |  |  |

Simple pattern match on dynamic string pattern.

int str_matchb | ( | const str * | s,
|  | const char * | pptr,
|  | unsigned | plen |
| ) |  |  |

Simple but fast (linear time) pattern matching on binary pattern.

int str_matchs | ( | const str * | s,
|  | const char * | pattern |
| ) |  |  |

Simple pattern match on C string pattern.

void str_rcut | ( | str * | s,
|  | unsigned | count |
| ) |  |  |

Cut `count` bytes from the right (end) of the string

void str_rstrip | ( | str * | s | ) |

Strip all white space from the right (end) of the string

int str_sort | ( | str * | s,
|  | char | sep,
|  | long | count,
|  | int(*)(const str_sortentry *a, const str_sortentry *b) | fn |
| ) |  |  |

Sort a string.

Parameters:

  | s | The string to sort.
  | sep | The character which delimits the substrings.
  | count | The number of substrings within `s` (set to `-1` if not known).
  | fn | The comparison function. Defaults to a function that works like `memcmp`.

Note:
  This function allocates a temporary array of substring pointers, and so may return `0` if memory allocation fails. The string itself is not reallocated.

int str_start | ( | const str * | a,
|  | const str * | b |
| ) |  |  |

Match the prefix of the string to another string.

int str_startb | ( | const str * | a,
|  | const char * | b,
|  | unsigned | len |
| ) |  |  |

Match the prefix of the string to a binary chunk.

int str_starts | ( | const str * | a,
|  | const char * | b |
| ) |  |  |

Match the prefix of the string to a C string.

long str_subst | ( | str * | s,
|  | char | from,
|  | char | to |
| ) |  |  |

Substitute one character for another throughout the string.

Returns:
  the number of substitutions made.

int str_truncate | ( | str * | s,
|  | unsigned | len |
| ) |  |  |

Truncate a string.

If `len` is larger than the current size, the string is reallocated. If `len` is less than the existing length (not size), the length of the string is reduced to `len`. A `NUL` marker is placed at `len`.

void str_upper | ( | str * | s | ) |

Translate all lower-case characters to upper-case

long str_xlate | ( | str * | s,
|  | const char * | from,
|  | const char * | to,
|  | unsigned | nchars |
| ) |  |  |

Substitute one character for another throughout the string.

Returns:
  the number of substitutions made.

## Variable Documentation

const char str_lcase_digits[36]

Lower-case digits, also used for decimal numbers.

const char str_ucase_digits[36]

Upper-case digits.