===============================================================================
string - String and memory manipulation functions                    2007-03-17


SYNOPSIS

    #include <libHX/string.h>

    char *HX_chomp(char *S);
    void *HX_memdup(const void *B, size_t LEN);
    char **HX_split(const char *S, const char *DELIM, size_t *FIELDS);
    const char *HX_strbchr(const char *START, const char *NOW, char D);
    char *HX_strclone(char **PA, const char *PB);
    char *HX_strdup(const char *SRC);
    char *HX_strlcat(char *DEST, const char *SRC, size_t LEN);
    char *HX_strlower(char *S);
    size_t HX_strltrim(char *S);
    char *HX_strmid(const char *EXPR, long OFFSET, long LENGTH);
    char *HX_strncpy(char *DEST, const char *SRC, size_t LENGTH);
    char *HX_strrev(char *S);
    size_t HX_strrtrim(char *S);
    char *HX_strsep(char **SP, const char *D);
    char *HX_strsep2(char **SP, const char *W);
    char *HX_strupper(char *S);


HX_chomp()

    Removes any trailing newline stuff ('\r' and '\n') in the string S by
    replacing the first occurrence with '\0'.


HX_memdup()

    Duplicates the contents at memory location B which are of size LEN using
    malloc() and returns the result.


HX_split()

    FIXME.


HX_split5()

    FIXME.


HX_strbchr()

    Searches the char D in the range from NOW to START. (Like strrchr(),
    but begins at NOW.)


HX_strclone()

    Copies the string pointed to by PB into *PA. If *PA was not NULL the
    time HX_strclone() was called, that string is freed before a new is
    allocated.  Returns NULL and sets errno to EINVAL if PB is NULL (yeah
    that is the way you can free it too), or if malloc() fails, returns
    NULL and leaves errno at what malloc() set it to.


HX_strdup()

    This implementation of strdup() has been added since certain operating
    systems (like Solaris 8, 9) do not have a strdup() provided by libc. 
    (It's a BSD function.)


HX_strlcat()

    FIXED.


HX_strlower(), HX_strupper()

    HX_strlower() and HX_strupper() transform all characters in the string S
    into lower or upper case, using tolower() or toupper(), respectively. They
    return their argument.


HX_strltrim(), HX_strrtrim()

    Trims all whitespace to the left. The remaining characters in the
    string will be moved to the beginning of the memory area using
    memmove(). A pointer to the beginning of the string is returned. This
    function will use the current locale using isspace().

    HX_strrtrim() finds and trims whitespace on the right side and
    overwrites the first char of a "space block" (identified by isspace())
    with a '\0'.


HX_strmid()

    Extracts a substring out of expr and returns it. If offset is
    negative, starts that far from the end of the string. If length is 0,
    this is special, returns everything to the end of the string. (If you
    really want Perl's behavior of returning nothing (length=0) make your
    own wrapper.) If length is negative, leaves off that many characters
    off the end of the string. The storage for the extracted substring is
    malloc()'ed, so it is up to you to free it afterwards when you do not
    need it anymore.


HX_strncpy()

    Copies at most LENGTH bytes from SRC to DEST, and always
    '\0'-terminates DEST. It is therefore equal to
    snprintf(dest, length, "%s", src);, but uses libc's strncpy() because
    that is likely faster than snprintf().


HX_strrep()

    Replaces every occurence of a printf(3) style %x format specifier with
    a given string or number as outlined in the map argument structure.
    FIXME.


HX_strrev()

    Reverses the string in expr, and returns expr.


HX_strsep()

    This implementation of strsep() has been added since this functions
    conforms to BSD4.4 and may not be available on every operating system.

    This function extracts tokens, separated one of the characters in D.
    We find the delimiting character either through strchr() or strpbrk(),
    depending on difficulty. The delimiter is then overwritten with '\0',
    *sp is advanced to the char after the delimiter, and the original
    pointer is returned. In case *sp is NULL, we are finished with
    extracting tokens and thus, calling HX_strsep() with
    *sp == NULL always returns NULL.


HX_strsep2()

    Instead of splitting at any of the characters in D like HX_strsep() does,
    HX_strsep2() splits exactly on substring W.


===============================================================================