Module str

String Manipulation.

When building up strings use a strbuf, which is a sequence of chars; can add characters and strings, formatted strings (like str_fmt) and also insert and remove substrings. The actual string is always *S but use strbuf_tostring to properly clean up and dispose of the sequence.

str_split creates a refcounted array of strings, splitting using a delimiter. str_concat works the other way, joining an array of strings with a separator.

There are searching operations which return a boolean or integer index, loosely based on C++’s std::string methods.

smaps (‘simple maps’) are arrays of strings where the odd indices are keys and the even indices are values. str_lookup does a linear search, which is simple and sufficient for small maps. A convenient way to build these maps is to start with smap_new and use either smap_add to simply add, or smap_put to update/add, key/value pairs.

See test-str.c

String buffers

strbuf_new (void) new string buffer.
strbuf_tostring (sp) convert a string buffer to a string.
strbuf_add (sp, ch) append a character to a string buffer.
strbuf_adds (sp, ss) append a string to a string buffer.
strbuf_addf (sp, fmt, ...) append formatted results to a string buffer.
strbuf_addr (sp, s, i1, i2) append a range of chars from a string.
strbuf_addsp (ss, s) append a string surronded by spaces.
strbuf_insert_at (sp, pos, src, sz) insert a string into a string buffer at pos.
strbuf_erase (sp, pos, len) erase len chars from pos.
strbuf_replace (sp, pos, len, s) replace len chars from pos with the string s.

Extra string functions

str_vfmt (fmt, ap) safe verson of vsprintf which returns a refcounted string.
str_fmt (fmt, ...) safe verson of sprintf which returns a refcounted string.
str_sub (s, i1, i2) extract a substring.
str_trim (s) trim a string in-place

Finding things in strings

str_end (s) get pointer to last char of string.
str_eq (a, b) are these strings equal?
str_starts_with (s, prefix) does the string start with this prefix?
str_ends_with (s, postfix) does the string end with this postfix?
str_is_blank (s) does a string only consist of blank characters?
str_findstr (s, sub) find substring sub in the string.
str_contains (s, sub, after) contains substring?
str_findch (s, ch) find character ch in the string.
str_find_first_of (s, ps) find first character that is in the string ps
str_find_first_not_of (s, ps) find first character that is not in the string ps

Splitting and Concatention

str_split_n (s, delim, nsplit) split a string upto nsplit times using delimiters.
str_split (s, delim) split a string using delimiters.
str_concat (ss, delim) concatenate an array of strings.
str_strings (first, ...) Allocating a simple array of strings.
str_index (strings, s) index of s in string array strings.
str_eq_any (s, ...) 1-based index of s in an arbitrary number of string arguments.

smap Functions

FOR_SMAP Iterate over a simple map
str_lookup_ptr (substs, name) Look up a string in a smap returning pointer to entry.
str_lookup (substs, name) Look up a string key in a smap returning associated value.
str_gets (substs, name) Like str_lookup but assuming value is a string.
smap_new (ref) New simple map builder.
smap_add (smap, name, data) Add a key/value pair.
smap_put (smap, name, data) Update/insert a key/value pair.
smap_get (smap, name) Get the value associated with name.
smap_close (smap) close the sequence, returning a simple map.
smap_len (smap) number of entries.
smap_put_ref (name, data) add referenced key/value pair.
smap_put_ref (name, data) update/insert a referenced key/value pair.


String buffers

strbuf_new (void)
new string buffer. Currently, string buffers are just sequences of chars.

Parameters:

  • void

Returns:

    char * *
strbuf_tostring (sp)
convert a string buffer to a string.

Parameters:

  • sp char**

Returns:

    char*
strbuf_add (sp, ch)
append a character to a string buffer.

Parameters:

  • sp char**
  • ch char
strbuf_adds (sp, ss)
append a string to a string buffer.

Parameters:

  • sp char * *
  • ss str_t
strbuf_addf (sp, fmt, ...)
append formatted results to a string buffer. Note that the result must be less than BUFSZ (default 256)

Parameters:

  • sp char * *
  • fmt str_t
  • ...
strbuf_addr (sp, s, i1, i2)
append a range of chars from a string.

Parameters:

  • sp char * *
  • s str_t
  • i1 int
  • i2 int
strbuf_addsp (ss, s)
append a string surronded by spaces. useful when building up a string of tokens separated by spaces.

Parameters:

  • ss char * *
  • s str_t
strbuf_insert_at (sp, pos, src, sz)
insert a string into a string buffer at pos. May specify the number of characters to be copied sz; if this is -1 then use the ordinary length of the string.

Parameters:

  • sp char * *
  • pos int
  • src str_t
  • sz int

Returns:

    char *
strbuf_erase (sp, pos, len)
erase len chars from pos.

Parameters:

  • sp char * *
  • pos int
  • len int

Returns:

    char *
strbuf_replace (sp, pos, len, s)
replace len chars from pos with the string s.

Parameters:

  • sp char * *
  • pos int
  • len int
  • s str_t

Returns:

    char *

Extra string functions

str_vfmt (fmt, ap)
safe verson of vsprintf which returns a refcounted string.

Parameters:

  • fmt str_t
  • ap va_list

Returns:

    char *
str_fmt (fmt, ...)
safe verson of sprintf which returns a refcounted string.

Parameters:

  • fmt str_t
  • ...

Returns:

    char *
str_sub (s, i1, i2)
extract a substring. Note that i2 and ‘i1’ are indices which may be negative, so (0,-1) is a string copy and (1,-2) copies from 2nd to second-last character.

Parameters:

  • s str_t
  • i1 int
  • i2 int

Returns:

    char *

Usage:

  • str_sub("hello",2,3) -> "l"
  • str_sub("hello",2,-1) -> "llo"
str_trim (s)
trim a string in-place

Parameters:

  • s char *

Finding things in strings

str_end (s)
get pointer to last char of string.

Parameters:

  • s str_t

Returns:

    str_t
str_eq (a, b)
are these strings equal?

Parameters:

  • a str_t
  • b str_t
str_starts_with (s, prefix)
does the string start with this prefix?

Parameters:

  • s str_t
  • prefix str_t

Returns:

    bool
str_ends_with (s, postfix)
does the string end with this postfix?

Parameters:

  • s str_t
  • postfix str_t

Returns:

    bool
str_is_blank (s)
does a string only consist of blank characters?

Parameters:

  • s str_t

Returns:

    bool
str_findstr (s, sub)
find substring sub in the string.

Parameters:

  • s str_t
  • sub str_t

Returns:

    int
str_contains (s, sub, after)
contains substring? also optionally return index past match.

Parameters:

  • s str_t
  • sub str_t
  • after int *

Returns:

    bool
str_findch (s, ch)
find character ch in the string.

Parameters:

  • s str_t
  • ch char

Returns:

    int
str_find_first_of (s, ps)
find first character that is in the string ps

Parameters:

  • s str_t
  • ps str_t

Returns:

    int
str_find_first_not_of (s, ps)
find first character that is not in the string ps

Parameters:

  • s str_t
  • ps str_t

Returns:

    int

Splitting and Concatention

str_split_n (s, delim, nsplit)
split a string upto nsplit times using delimiters. Returns a ref array of ref strings.

Parameters:

  • s str_t
  • delim str_t
  • nsplit int

Returns:

    char * *
str_split (s, delim)
split a string using delimiters. Returns a ref array of ref strings.

Parameters:

  • s str_t
  • delim str_t

Returns:

    char * *
str_concat (ss, delim)
concatenate an array of strings. Assumes that the array is refcounted

Parameters:

  • ss char * *
  • delim str_t

Returns:

    char *
str_strings (first, ...)
Allocating a simple array of strings. End the string arguments with a final NULL. Note that this array is not a ref container; the string addresses are just copied over.

Parameters:

  • first char *
  • ...

Returns:

    char * *
str_index (strings, s)
index of s in string array strings. -1 if not found. The string array must be NULL terminated.

Parameters:

  • strings const char * *
  • s const char *

Returns:

    int
str_eq_any (s, ...)
1-based index of s in an arbitrary number of string arguments. If we don’t match, then return 0! str_eq_any is a convenient replacement for a chain of string comparions. Also useful to parse enum values.

Parameters:

  • s string the string to match
  • ... the strings to match against

Returns:

    int

Usage:

    str_eq_any("foo","baz","foo","bar") == 2;

smap Functions

FOR_SMAP
Iterate over a simple map
  • k variable for key
  • v variable for value
str_lookup_ptr (substs, name)
Look up a string in a smap returning pointer to entry.

Parameters:

  • substs char * *
  • name const char *

Returns:

    void * *
str_lookup (substs, name)
Look up a string key in a smap returning associated value.

Parameters:

  • substs char * *
  • name const char *

Returns:

    void *
str_gets (substs, name)
Like str_lookup but assuming value is a string.

Parameters:

  • substs char * *
  • name const char *

Returns:

    char *
smap_new (ref)
New simple map builder.

Parameters:

  • ref bool

Returns:

    char * * *
smap_add (smap, name, data)
Add a key/value pair.

Parameters:

  • smap char * * *
  • name const char *
  • data const void *
smap_put (smap, name, data)
Update/insert a key/value pair.

Parameters:

  • smap char * * *
  • name const char *
  • data const void *
smap_get (smap, name)
Get the value associated with name.

Parameters:

  • smap char * * *
  • name const char *

Returns:

    void *
smap_close (smap)
close the sequence, returning a simple map.

Parameters:

  • smap char * * *

Returns:

    char * *
smap_len (smap)
number of entries.

Parameters:

  • smap char * * *

Returns:

    int
smap_put_ref (name, data)
add referenced key/value pair.

Parameters:

  • name str_t
  • data str_t
smap_put_ref (name, data)
update/insert a referenced key/value pair.

Parameters:

  • name str_t
  • data str_t
generated by LDoc 1.4.3 Last updated 2015-04-27 12:35:55