NAME

stringx − character string operations: strapp, strnapp, strbld, strbldf, strchg, strins, strdel, strcmpi, strncmpi, strnew, strfree, strend, strhash, strhashi, strstrx, strrstrx, strwcmp, strwcmpi, strwpat, strupper, strlower, strtokx, strsep, strsepb, strcmbn, strcmbnb, strvdup, strvfree, strvlen

SYNOPSIS

#include <stdio.h>
#include <string.h>
#include <codelibs/boolean.h>
#include <codelibs/stringx.h>
 char  ∗strapp(char ∗s1, const char ∗s2);
char  ∗strnapp(char ∗s1, const char ∗s2, size_t n);
 const char  ∗strbld(const char ∗arg, ...);
const char  ∗strbldf(const char ∗fmt, ...);
 char  ∗strchg(char ∗s1, const char ∗s2, char ∗ptr, long n);
char  ∗strins(char ∗s1, const char ∗s2, char ∗ptr);
char  ∗strdel(char ∗s1, char ∗ptr, long n);
 int    strcmpi(const char ∗s1, const char ∗s1);
int    strncmpi(const char ∗s1, const char ∗s2, size_t n);
 int  streq(const char ∗s1, const char ∗s2);
int  streqi(const char ∗s1, const char ∗s2);
 char  ∗strnew(size_t len);
void   strfree(const char ∗s);
 char  ∗strend(const char ∗s);
 unsigned  strhash(const char ∗key);
unsigned  strhashi(const char ∗key);
 char  ∗strstrx(char ∗s1, const char ∗s2);
char  ∗strrstrx(char ∗s1, const char ∗s2);
 int    strwcmp(const char ∗pattern, const char ∗str);
int    strwcmpi(const char ∗pattern, const char ∗str);
char  ∗strwpat(const char ∗pattern);
 char  ∗strupper(char ∗s);
char  ∗strlower(char ∗s);
 char  ∗strtokx(char ∗&ptr, const char ∗sep);
 char ∗∗strsep(const char ∗str, const char ∗sep,
  boolean whsp = TRUE, int ∗num = NULL);
char ∗∗strsepb(const char ∗str, const char ∗sep,
  boolean whsp = TRUE, int ∗num = NULL, void ∗∗bufvar = NULL);
const char ∗strcmbn(const char ∗∗vec, const char ∗sep = " ");
const char ∗strcmbnb(const char ∗∗vec, const char ∗sep = " ",
      void∗∗ bufvar = NULL);
 char ∗∗strvdup(const char ∗∗vec, int num = -1);
void   strvfree(const char ∗∗vec, int num = -1);
int    strvlen(const char ∗∗vec);
  CC ... -lcodelibs
 

DESCRIPTION

These functions operate on null-terminated strings.  Many of these are extended versions of the routines in string(3C).

strapp strnapp

Strapp and Strnapp are dynamic-allocation versions of strcat(3C) and strncat(3C), respectively.  If s1 is a NULL pointer, space will be allocated for the result.  Otherwise, the string pointed to by s1 must be a dynamically-allocated string.  This string will be expanded to hold the result.  Note that the pointer returned by these routines will not necessarily be the same as the value passed for s1.  The value n for strnapp should always be greater than zero. 

strbld

Strbld concatenates a null-terminated variable-length list of strings into an internal buffer, and returns a pointer to that buffer.  This buffer is automatically grown so it will never overflow. 

strbldf

Strbldf uses mvsprintf(3X) to write the variable-length argument list into an internal buffer, and then returns a pointer to that buffer. The first argument should be a format string describing how the following arguments should be formatted. The internal buffer is automatically grown so that it can never overflow. This buffer is different than the ones used in strbld and msprintf(3X). (See stdiox(3X) for more details.)

strchg strdel strins

These are three functions for manipulating a dynamically allocated string.  Strchg changes the substring of s1 that is pointed to by ptr and whose length is n to the value of the string s2.  The string s2 may be a different length than the substring being replaced.  Strdel deletes the substring of s1 that is pointed to by ptr and whose length is n.  Strins inserts the string s2 into the string s1 before the character pointed to by ptr.  If ptr points to the null at the end of s1, an append operation will be performed.  In all three functions, the string s1 will be re-allocated to the correct size to hold the result.  In addition, a NULL pointer will be returned if ptr doesn’t point into s1, or if s1 is the NULL pointer.  If the substring specified in strchg or strdel would go beyond the end of s1, the tail of s1 will be changed/deleted. 

strcmpi strncmpi

Strcmpi and strncmpi are case-insensitive versions of strcmp(3C) and strncmp(3C), respectively. Strcmpi compares its arguments and returns an integer greater than, equal to, or less than 0, if s1 is lexicographically greater than, equal to, or less than s2. (NULL pointers for s1 and s2 are treated the same as pointers to null strings.)  Strncmpi makes the same comparison but looks at at most n characters (n less than or equal to zero implies equality).  Both of these routines use unsigned char for character comparison.  The strings are always compared as if they had been converted to upper-case. 

streq streqi

Streq is a macro that returns TRUE if the strings are equal, and FALSE if they are not.  Streqi is the same except that the compare is case-insensitive. 

strnew strfree

Strnew allocates space (using malloc(3C)) for a string of length len plus one (for the null byte terminator), but doesn’t initialize it.  Thus strnew will always return a pointer to at least one byte of memory.  Strfree frees strings allocated by strnew by calling free(3C) but ignoring calls with s == NULL. Both these routines are inlines for C++.

strend

This returns a pointer to the NULL character at the end of the passed string. 

strhash strhashi

strhash returns a unique non-negative hash value for a given string.  It is mostly useful with packages like hashtable(3X). strhashi is the same except that the hash value is case-insensitive.   For strings with no upper case letters strhash and strhashi return the same value.  strhash.

strstrx strrstrx

Strstrx (strrstrx) returns a pointer to the first (last) occurrence of string s2 in string s1, or NULL if s2 does not occur in the string.  The null character terminating a string is considered to be part of the string.  If a NULL pointer is given for either argument, it is treated as a null string.  Since strstrx (strrstrx) must return a pointer into its left argument, passing NULL as the first argument will always result in a return value of NULL. 

strwcmp strwcmpi

Strwcmp compares the sh(1) style wildcard string in its first argument with its second argument. If the pattern match is successful, the function returns zero, otherwise a one is returned.  These return values are consistent with the values returned by the other string comparison functions. Strwcmpi is a case-insensitive version of Strwcmp. It is the equivalent of calling Strwcmp with both arguments converted to upper-case. 

strwpat

If the passed string is an sh(1) style wildcard string, this function returns a pointer to the first wildcard character in the string, otherwise it returns NULL. The POSIX 16-bit extended wildcard matching rules are not yet supported.

strupper strlower

Converts the string argument to all upper or all lower case, properly handling 8 and 16 bit NLS character strings.  Does nothing to 16-bit character strings, where case makes no sense anyway. 
 
If an upper or lower case copy is needed, use strdup(3C).

strtokx

This is one alternative to the strtok(3C) function.  Because it uses a user-supplied variable to maintain its state, several strings may safely be parsed at the same time. Strtokx should be used any time strtok(3C) is needed inside of a general-purpose library function, since there is no way to tell if the caller may already be using a string returned by strtok(3C).

Strtokx considers the string pointed to by ptr to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string sep. Each call returns a pointer to the first character of the first token, and will have written a null character into the string pointed to by ptr immediately following the returned token. The function keeps track of its position by updating the ptr variable between separate calls, so that subsequent calls will work through the string immediately following that token until no tokens remain.  The separator string sep may be different from call to call.  When no token remains in the string pointed to by ptr, a NULL pointer is returned.

strsep

Strsep separates a given str into an array of strings much like the split function in awk(1). Sep is a string of the separator characters to use when breaking up str. If whsp is TRUE (1), then multiple separators will be treated as one (like whitespace).  If FALSE (0), then separators are treated as field separators.  If num is not NULL, then the number of strings in the vector is returned there.  The resulting array is also terminated with a NULL string.  Str is not modified in any way. 

The vector returned is re-used with each call to strsep and must NOT be directly freed, although strvdup can be used to make a copy of it if desired. 

strcmbn

Combines the contents of a string vector vec into a single string, using the string sep as a separator (defauly being a single space) between each vector element.  This is basically the reverse of strsep above. 

strvdup strvfree

Strvdup returns a complete copy of an array of strings (including copying each string within the array with strdup(3C)). Strvfree frees the array and all the strings within it.  If the number of elements in the array num is negative, then the array is assumed to be NULL terminated and num is calculated appropriately.  If the array is not NULL terminated, a value for num must be provided by the caller. 

strvlen

Return the number of strings in a vector of strings by looking for a NULL pointer. 
 

strsepb strcmbnb

These routines act just like their counterparts above, except that they do not maintain any internal buffers.  They have one additional void∗∗ bufvar argument which must be the address of a user-defined static variable.  This bufvar is then used to manage the private buffers that these routines need.  (This feature is mostly used by other library routines.)  However, if bufvar is NULL, these routines instead allocate and return a new string or vector that must (eventually) be freed using strfree or strvfree as appropriate. 

SEE ALSO

awk(1), ctype(3C), hashtable(3X), malloc(3C), malloc(3X), sh(1), string(3C), stdiox(3X),

NOTES

Supports HP-NLS 8-bit and 16-bit characters. 

Strapp, strnapp, strchg, strdel, and strins all work with dynamically allocated strings.  They assume that the strings were allocated by strnew or strdup(3C). If strings allocated by any other means are used, the results may be unpredictable. Any string returned should be de-allocated by using strfree or free(3C), although using strfree is preferred as it is a lot more readable. 

Strwcmp and strwcmpi do not treat a leading ‘.’ on a string differently like sh(1) does. The POSIX 16-bit extended wildcard matching rules are not yet supported.

WARNINGS

Overlapping string moves or copies may NOT work as expected. 

Strbldf does not check for overflow of the destination;  The static buffers for strbld and strbldf can hold at most 4000 characters including the NULL byte. 

NULL sources are treated as zero-length strings. 

  —  codelibs  —  C++