[Libclc-developers] String functions so far

[Hallvard B F. <h.b...@us...>]

Here are clc_string.h and the documentation of the functions,
except clc_ultostr.  Please comment.

I've included the suggested documentation for clc_str{n}casecmp, but not
included them in clc_string.h since there has been no discussion about
them.



#ifndef CLC_STRING_H
#define CLC_STRING_H

#include <stddef.h>
#include "clc_settings.h"

#ifdef __cplusplus
extern "C" {
#endif

char* clc_strdup(const char* CLC_RESTRICT clc_s);

char* clc_strtrim(char* clc_s);
char* clc_strrtrim(char* clc_s);
char* clc_strltrim(char* clc_s);
char* clc_strlwr(char *clc_s);
char* clc_strnorm(char *clc_s);
char* clc_strupr(char *clc_s);

char* clc_stralloc(const char *clc_arg1, ...);
char* clc_stpcpy(
	char* CLC_RESTRICT clc_s1,
	const char* CLC_RESTRICT clc_s2);

char* clc_strendcpy(
	char* clc_dest,
	const char* CLC_RESTRICT clc_src,
	const char* clc_end);

int clc_ultostr(
	char* clc_ptr,
	size_t clc_size,
	unsigned long clc_num,
	int clc_base);

size_t clc_strlcpy(
	char* CLC_RESTRICT clc_dest,
	const char* CLC_RESTRICT clc_src,
	size_t clc_size);

size_t clc_strlcat(
	char* CLC_RESTRICT clc_dest,
	const char* CLC_RESTRICT clc_src,
	size_t clc_size);

char* clc_strsep(
	char** CLC_RESTRICT clc_stringp,
	const char* CLC_RESTRICT clc_delim);

char* clc_strtok_r(
	char* clc_str,
	const char* CLC_RESTRICT clc_delim,
	char** clc_tracker);

#ifdef __cplusplus
}
#endif

#endif /* CLC_STRING_H */





NAME
    clc_stpcpy - copy string and return pointer to end

SYNOPSIS
    #include "clc_string.h"
    char *clc_stpcpy(char *CLC_RESTRICT s1,
                     const char *CLC_RESTRICT s2);

    Link with: clc library.

DESCRIPTION
    This function copies string s2 to s1.

RETURN VALUE
    clc_stpcpy() returns a pointer to the terminating null character in
    s1.

EXAMPLE
    clc_stpcpy(clc_stpcpy(buffer, basename), ".txt");

SEE ALSO
    strcpy(3)



NAME
    clc_strendcpy - copy limited string and return pointer to end

SYNOPSIS
    #include "clc_string.h"
    char *clc_strendcpy(char *dst, const char *CLC_RESTRICT src,
                        const char *end);

    Link with: clc library.

DESCRIPTION
    clc_strendcpy() copies the string src to dst, truncates it if
    the length is >= end, and null-terminates it.
    Nothing is done if dst >= end.

RETURN VALUE
    clc_strendcpy() returns a pointer to the terminating null character
    in dst, or to end (i.e. one past the null) if the string was
    truncated.  It return dst if end >= dst.

EXAMPLE
    char buf[80], *end = buf + sizeof(buf);
    char *dst = strendcpy(strendcpy(buf, str1, end), str2, end);
    if (dst >= end)
        warning("string was truncated");

SEE ALSO
    strcpy(3), strncpy(3), clc_strlcpy(3)



NAME
    clc_strlcat, clc_strlcpy - safe string copy and concatenation

SYNOPSIS
    #include "clc_string.h"
    size_t clc_strlcpy(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);
    size_t clc_strlcat(char *CLC_RESTRICT dest,
                       const char *CLC_RESTRICT src, size_t size);

    Link with: clc library.

DESCRIPTION
    clc_strlcpy() copies the string src to dest.  It copies at most
    size-1 characters, and if size != 0 it then null-terminates dest.

    clc_strlcat() appends the string src to dest.  It appends at most
    size-1-strlen(dest) characters, and if size != 0 it then null-
    terminates dest.  Dest is not truncated if size <= strlen(dest).

    You can check for truncation by checking if the return values
    are less than size, except when clc_strlcat() is given a dest
    string which is >= size.

RETURN VALUES
    clc_strlcpy() returns strlen(src).
    clc_strlcat() returns strlen(dest) + strlen(src).

EXAMPLE
    if (clc_strlcat(buf, "text", sizeof(buf)) >= sizeof(buf))
        printf(stderr, "Value was truncated.\n");

ACKNOWLEDGMENTS
    These functions were invented by Todd C. Miller and Theo de Raadt,
    see <http://www.courtesan.com/todd/papers/strlcpy.html>.

SEE ALSO
    clc_strendcpy(3), strncpy(3), strncat(3)



NAME
    clc_strdup - allocate a duplicate of a string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strdup(const char * CLC_RESTRICT s);

    Link with: clc library.

DESCRIPTION
    clc_strdup() creates a malloced copy of the string s.
    The result should be freed with free().

RETURN VALUE
    The function returns the duplicated string, or NULL if enough space
    could not be allocated.

EXAMPLE
    char *s = clc_strdup("foo");
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc_stralloc(3), malloc(3), strcpy(3)



NAME
    clc_stralloc - allocate a concatenation of strings

SYNOPSIS
    #include "clc_string.h"
    char *clc_stralloc(const char *arg1, ...);

    Link with: clc library.

DESCRIPTION
    This function takes zero or more string arguments followed by
    (char*)0, and concatenates them.
    The result should be freed with free().

RETURN VALUE
    clc_stralloc() returns a malloced concatenation of the arguments,
    or NULL if enough space could not be allocated.

EXAMPLE
    char *s = clc_stralloc("foo", "bar", (char *)0);
    if(s != NULL) {
        puts(s);
        free(s);
    }

SEE ALSO
    clc_strdup(3), malloc(3), strcpy(3)



NAME
    clc_strsep, clc_strtok_r - extract token from string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strsep(char **CLC_RESTRICT stringp,
                     const char *CLC_RESTRICT delim);
    char *clc_strtok_r(char *str, const char *CLC_RESTRICT delim,
                       char **tracker);

    Link with: clc library.

DESCRIPTION
    These functions split a string up in tokens delimited by any
    character in the delim parameter, like strtok() does.  Each token
    starts with the first character in the input string which is does
    not occur in delim, and ends with the next character which occurs in
    delim or with the terminating null character.

    The functions put a null character after the token in the input
    string.

    clc_strsep() takes *stringp as the input string.  It updates
    *stringp to point just past the null character in the returned
    token, or possibly to a null character when returning the last
    token.

    clc_strtok_r() takes the input string as the str parameter at the
    first call, and NULL at subsequent calls which split the same
    string.  The caller must supply a char* variable to the tracker
    parameter, the same variable for each call while splitting a string.
    This is used internally by clc_strtok_r to keep track of its
    position in the string being broken up.

    The advantages of these functions over strtok is that you need not
    split just one string at a time, and that they are thread-safe.

RETURN VALUES
    The functions return a pointer to the next token in the supplied
    string, or NULL if there are no more tokens.

EXAMPLES
    char buffer[80], *token, *s, *tracker;
    ...
    for (s = buffer; token = strsep(&s, " \t"); )
        puts(token);
    ...
    for (s = buffer; token = clc_strtok_r(s, " \t", &tracker); s = NULL)
        puts(token);

SEE ALSO
    strtok(3)



NAME
    clc_strcasecmp - case-insensitive string compare

SYNOPSIS
    #include "clc_string.h"
    char *clc_strcasecmp(const char *s1, const char *s2);

    Link with: clc library.

DESCRIPTION
    This function compares two strings byte by byte, ignoring
    differences in case.

RETURN VALUE
    The function returns 0 if the strings compare equal, a negative
    value if s1 is less by unsigned char comparison, and a positive
    value if s2 is less.

EXAMPLE
    if(strcasecmp(name, "Augestad") == 0)
        puts("Great person.");

SEE ALSO
    strcmp(3), clc_strncasecmp(3)




NAME
    clc_strncasecmp - case-insensitive string compare with size limit

SYNOPSIS
    #include "clc_string.h"
    char *clc_strncasecmp(const char *s1, const char *s2, size_t len);

    Link with: clc library.

DESCRIPTION
    This function compares two strings byte by byte, ignoring
    differences in case, up to the first null character or until
    the length parameter len is reached.

RETURN VALUE
    The function returns 0 if the strings compare equal, a negative
    value if s1 is less by unsigned char comparison, and a positive
    value if s2 is less.

EXAMPLE
    if(strncasecmp(buffer, arg, sizeof(buffer)) == 0)
        puts("The argument starts with the proper string.");

SEE ALSO
    strncmp(3), clc_strcasecmp(3)



NAME
    clc_strltrim - trim whitespace from the left of string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strltrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        puts(clc_strltrim(buffer));

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strrtrim - trim whitespace at the right of string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strrtrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the end of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    *buffer = '\0';
    if (fgets(buffer, sizeof(buffer), f))
        clc_strrtrim(buffer);
    return buffer;

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strtrim - trim whitespace surrounding string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strtrim(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning and end of the string.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        return clc_strtrim(buffer);
    return NULL;

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strnorm - remove duplicate/surrounding whitespace from string

SYNOPSIS
    #include "clc_string.h"
    char *clc_strnorm(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by removing whitespace at
    the beginning and end of the string, and converting all remaining
    groups of whitespace to a single space.

RETURN VALUE
    The function returns the s parameter.

EXAMPLE
    if (fgets(buffer, sizeof(buffer), f))
        puts(clc_strnorm(buffer));

SEE ALSO
    isspace(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strlwr - convert string in place to lowercase

SYNOPSIS
    #include "clc_string.h"
    char *clc_strlwr(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by converting it to
    lowercase.

RETURN VALUE
    The function returns the s parameter.

SEE ALSO
    tolower(3)

AUTHOR
    Eric G. Miller



NAME
    clc_strupr - convert string in place to uppercase

SYNOPSIS
    #include "clc_string.h"
    char *clc_strupr(char *s);

    Link with: clc library.

DESCRIPTION
    This function modifies the input string by converting it to
    uppercase.

RETURN VALUE
    The function returns the s parameter.

SEE ALSO
    toupper(3)

AUTHOR
    Eric G. Miller



-- 
Hallvard