The Hackerlab at `regexps.com`

## Eight-bit Characters and Strings

up: libhackerlab next: Converting Between Numbers and Strings prev: Hashing

The functions in this section operate on 8-bit characters (values of type `char` or `t_uchar` ) and strings of such characters.

NOTE: Internationalized character and string functions are not included with this release. Future releases will include such functions in addition to those documented here.

- Character Classes
- Character Names
- String Functions

### Character Classes

up: Eight-bit Characters and Strings next: Character Names

The character-class macros assign each byte to various categories of characters such as upper-case and lower-case letters.

These functions are based on the ASCII character set. They are not locale-sensative.

Macro `char_is_upper`

    int char_is_upper (t_uchar x);

Return `1` if `x` is an upper case letter, `0` otherwise.

Macro `char_is_lower`

    int char_is_lower (t_uchar x);

Return `1` if `x` is a lower case letter, `0` otherwise.

Macro `char_is_alpha`

    int char_is_alpha (t_uchar x);

Return `1` if `x` is an upper or lower case letter, `0` otherwise.

Macro `char_is_digit`

    int char_is_digit (t_uchar x);

Return `1` if `x` is a decimal digit, `0` otherwise.

Macro `char_is_alnum`

    int char_is_alnum (t_uchar x);

Return `1` if `x` is an upper or lower case letter or digit, `0` otherwise.

Macro `char_is_control`

    int char_is_control (t_uchar x);

Return `1` if `x` is a control character, `0` otherwise.

Macro `char_is_printable`

    int char_is_printable (t_uchar x);

Return `1` if `x` is a printable character, `0` otherwise.

Macro `char_is_space`

    int char_is_space (t_uchar x);

Return `1` if `x` is a space character, `0` otherwise.

Macro `char_is_graph`

    int char_is_graph (t_uchar x);

Return `1` if `x` is a non-space printable character, `0` otherwise.

Macro `char_is_c_id`

    int char_is_c_id (t_uchar x);

Return `1` if `x` is an alpha-numeric character or '_', `0` otherwise.

Macro `char_is_xdigit`

    int char_is_xdigit (t_uchar x);

Return `1` if `x` is a hexadecimal digit, `0` otherwise.

Macro `char_is_odigit`

    int char_is_odigit (t_uchar x);

Return `1` if `x` is an octal digit, `0` otherwise.

Macro `char_is_punct`

    int char_is_punct (t_uchar x);

Return `1` if `x` is a punctuation character, `0` otherwise.

### Character Names

up: Eight-bit Characters and Strings next: String Functions prev: Character Classes

Variable `char_name`

    extern t_uchar * char_name[256];

`char_name` contains the C names of each character (suitable for use in C character constants or strings). For example:

         char_name['\0']         is      "\\000"
         char_name['\n']         is      "\\n"
         char_name['\\']         is      "\\\\"
         char_name['a']          is      "a"

### String Functions

up: Eight-bit Characters and Strings prev: Character Names

These functions operate on `strings` , defined to be arrays of 't_uchar' terminated by (and not otherwise containing) the null character (`(t_uchar)0` ).

The functionality described in this function overlaps with some of the functions in the standard C library defined by Posix, but there are differences. Read the documentation carefully if you are replacing uses of Posix functions with Hackerlab functions.

- String Length
- Computing Hash Values From Strings
- Simple String Searching and Parsing
- String Comparisons
- String Comparisons Ignoring Case
- String Copying
- String Concatenation
- String Allocators
- Vararg String Functions

#### String Length

up: String Functions next: Computing Hash Values From Strings

Function `str_length`

    size_t str_length (const t_uchar * x);

Return the length of the 0-terminated string `x` . The length does not include the 0-byte itself.

Function `str_length_n`

    size_t str_length_n (const t_uchar * x, size_t n);

Return the length of the 0-terminated string `x` but not more than `n` . The length does not include the 0-byte itself.

If `x` is longer than `n` bytes, return `n` .

#### Computing Hash Values From Strings

up: String Functions next: Simple String Searching and Parsing prev: String Length

Function `str_hash_n`

    unsigned long str_hash_n (const t_uchar * chr, size_t len);

Compute an `unsigned long` hash value for a string.

#### Simple String Searching and Parsing

up: String Functions next: String Comparisons prev: Computing Hash Values From Strings

Function `str_chr_index`

    t_uchar * str_chr_index (const t_uchar * s, int c);

Return the position in 0-terminated string `s` of the first occurence of `c` . Return `0` if `c` does not occur in `s` .

Function `str_chr_rindex`

    t_uchar * str_chr_rindex (const t_uchar * s, int c);

Return the position in 0-terminated string `s` of the last occurence of `c` . Return `0` if `c` does not occur in `s` .

Function `str_chr_index_n`

    t_uchar * str_chr_index_n (const t_uchar * s, size_t n, int c);

Return the position in length `n` string `s` of the first occurence of `c` . Return `0` if `c` does not occur in `s` .

Function `str_chr_rindex_n`

    t_uchar * str_chr_rindex_n (const t_uchar * s, size_t n, int c);

Return the position in length `n` string `s` of the last occurence of `c` . Return `0` if `c` does not occur in `s` .

Function `str_separate`

    t_uchar * str_separate (t_uchar ** stringp, t_uchar * delims);

Find the first occurence of a character from `delims` in `*stringp` , replace that character with `0` , set `*stringp` the address of the next character after that, and return the value that `*stringp` had on entry.

If no delimeter is found in `*stringp` , set `*stringp` to `0` and return the value on entry of `*stringp` .

If `*stringp` is `0` , return `0` .

If `delims` is `0` , set `*stringp` to `0` , and return the value of `*stringp` on entry.

#### String Comparisons

up: String Functions next: String Comparisons Ignoring Case prev: Simple String Searching and Parsing

Function `str_cmp`

    int str_cmp (const t_uchar * a, const t_uchar * b);

Compare strings `a` and `b` returning `-1` if `a` is lexically first, `0` if the two strings are equal, `1` if `b` is lexically first.

Function `str_cmp_n`

    int str_cmp_n (const t_uchar * a,
                   size_t a_l,
                   const t_uchar * b,
                   size_t b_l);

Compare strings `a` (length `a_l` ) and `b` (length `b_l` ) returning `-1` if `a` is lexically first, `0` if the two strings are equal, `1` if `b` is lexically first.

Function `str_cmp_prefix`

    int str_cmp_prefix (const t_uchar * prefix, const t_uchar * s);

Compare strings `prefix` and `s` . If `prefix` is a prefix of `s` , return `0` . Otherwise, if `prefix` is lexically first, return `-1` ; if `s` is lexically first, return `1` .

#### String Comparisons Ignoring Case

up: String Functions next: String Copying prev: String Comparisons

Function `str_casecmp`

    int str_casecmp (const t_uchar * a, const t_uchar * b);

Compare strings `a` and `b` ignoring case, returning `-1` if `a` is lexically first, `0` if the two strings are equal, `1` if `b` is lexically first.

Function `str_casecmp_n`

    int str_casecmp_n (const t_uchar * a, size_t a_l,
                       const t_uchar * b, size_t b_l);

Compare strings `a` (length `a_l` ) and `b` (length `b_l` ) ignoring case returning `-1` if `a` is lexically first, `0` if the two strings are equal, `1` if `b` is lexically first.

Function `str_casecmp_prefix`

    int str_casecmp_prefix (const t_uchar * prefix, const t_uchar * s);

Compare strings `prefix` and `s` , ignoring case. If `prefix` is a prefix of `s` , return `0` . Otherwise, if `prefix` is lexically first, return `-1` ; if `s` is lexically first, return `1` .

#### String Copying

up: String Functions next: String Concatenation prev: String Comparisons Ignoring Case

Function `str_cpy`

    t_uchar * str_cpy (t_uchar * to, const t_uchar * from);

Copy the 0-terminated string `from` to `to` . `from` and `to` should not overlap.

Returns `to` .

Function `str_cpy_n`

    t_uchar * str_cpy_n (t_uchar * to,
                         const t_uchar * from,
                         size_t n);

Copy up-to `n` characters from `from` to `to` .

Add a final `0` to `to` .

Warning: This function is different from `strncpy` . `strncpy` always stores exactly `n` characters in `to` , padding the result with `0` if a `0` character is encountered in `from` before `n` characters are written. This function stores up to `n+1` characters: up to `n` non-0 characters from `from` , plus a final `0` .

Returns `to` .

#### String Concatenation

up: String Functions next: String Allocators prev: String Copying

Function `str_cat`

    t_uchar * str_cat (t_uchar * to, const t_uchar * from);

Append the 0-terminated string `from` to the 0-terminated string `to` . The strings should not overlap.

Returns `to` .

Function `str_cat_n`

    t_uchar * str_cat_n (t_uchar * to,
                         const t_uchar * from,
                         size_t n);

Append at most `n` characters of the 0-terminated string `from` to the 0-terminated string `to` . The strings should not overlap. Add a final `0` (thus writing up to `n + 1` characters in `to` , starting from the position of the final `0` in `to` on entry).

Returns `to` .

#### String Allocators

up: String Functions next: Vararg String Functions prev: String Concatenation

Function `str_save`

    t_uchar * strsav (alloc_limits limits, const t_uchar * str);

Allocate a copy of the 0-terminated string `str` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_save_n`

    t_uchar * str_save_n (alloc_limits limits,
                          const t_uchar * str,
                          size_t len);

Allocate a copy of the n-byte string `str` . Add one byte to the new string and store `0` in that byte.

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_alloc_cat`

    t_uchar * str_alloc_cat (alloc_limits limits,
                             const t_uchar * str1,
                             const t_uchar * str2);

Allocate a new string large enough to hold the concatenation of 0-terminated strings `str1` and `str2` (including a final `0` ). Initialize the new string with the concatenation of `str1` and `str2` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_alloc_cat_n`

    t_uchar * str_alloc_cat_n (alloc_limits limits,
                               const t_uchar * str1,
                               const t_uchar * str2,
                               size_t n);

Allocate a new 0-terminated string large enough to hold the concatenation of 0-terminated strings `str1` and `str2` , considering at most `n` characters from `str2` .

Initialize the new string with the concatenation of `str1` and up to `n` characters of `str2` . Append a final `0` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_realloc_cat`

    t_uchar * str_realloc_cat (alloc_limits limits,
                               t_uchar * str1,
                               const t_uchar * str2);

Reallocate `str1`` to be large enough to hold the concatenation of 0-terminated strings `str1` and `str2` (including a final `0` ). Initialize the new string with the concatenation of `str1` and `str2` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_realloc_cat_n`

    t_uchar * str_realloc_cat_n (alloc_limits limits,
                                 t_uchar * str1,
                                 const t_uchar * str2,
                                 size_t n);

Reallocate `str` to be large enough to hold the concatenation of 0-terminated strings `str1` and `str2` , considering at most `n` characters from `str2` .

Initialize the new string with the concatenation of `str1` and up to `n` characters of `str2` . Append a final `0` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

#### Vararg String Functions

up: String Functions prev: String Allocators

Function `str_cat_many`

    t_uchar * str_cat_many (t_uchar * to, ...);

Append 0-terminated strings to the 0-terminated string `to` . The strings should not overlap. The last argument should be the value `str_end` .

Returns `to` .

Function `str_alloc_cat_many`

    t_uchar * str_alloc_cat_many (alloc_limits limits, ...);

Allocate a new string large enough to hold the concatenation of 0-terminated strings (including a final `0` ). Initialize the new string with the concatenation of the given strings. The last argument should be the value `str_end` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

Function `str_realloc_cat_many`

    t_uchar * str_realloc_cat_many (alloc_limits limits,
                                    t_uchar * str1,
                                    ...)

Reallocate `str1` to be large enough to hold the concatenation of 0-terminated strings (including a final `0` ). Initialize the new string with the concatenation of the strings. The last argument should be the value `str_end` .

Allocate storage according to `limits` . (See Allocation With Limitations.)

libhackerlab: The Hackerlab C Library
The Hackerlab at `regexps.com`