Infrasctucture Str Function Reference

Str
Collection of string processing routines.

blur     catCnt     catDT     center     cidr2Rng     cidrCnt2Msk    
cntChr     cpyPntbl     crunch     crunchChr     cTrans     dec2hex    
decat     decatChr     decatCol     decatWd     decatWsp     dq2ul    
dq2oct     expTabs     fmtCat     fmtSiz     fndChr     fndChrs    
fndStr     fndLast     fndNxtFld     fndWsp     getNxtFld     hex2bin    
isBlnkLin     intStr     lftJust     merge     msk2CidrCnt     noWsp    
nxtFld     nxtHr     oct2dq     parse     _parse     prprNam    
replChr     replChrs     rmWsp     rng2Cidr     rtJust     shrpn    
skpChr     skpDigs     skpStr     skpWsp     strLencnt     stripChr    
strInt     strLcp     strLc     strParse     strUcp     strUc    
strVect     strVectU     substr     trim     ul2dq     ul2oct    
zotChr     zotLast     zotStr    

int  blur( char* buf, int len )
Blur (opposite of "shrpn") an ascii string into a hex array.    Requires the input ascii string length.    Returns the output length.

int  catCnt( char* out, int chr, int cnt )
Concatenate "cnt" copies of "chr" to the output string "out".

int  catDT( char* output, char* fmt, clok_t* timePtr )
Concatenate a formatted date into the string "output".    The date comes from a time pointer "timePtr" which points to a clok_t (timeval struct).    This function can be used with a time pointer to type time_t if the pointer is cast to clok_t and no milliseconds or microseconds are requested.    The format string "fmt" contains normal ascii characters and formatted fields made up of a percent "%" followed by a formatting character.    The format characters are:
    Y - year as yyyy.
    AM - Ascii month name.
    AD - Ascii day of week.
    M - Numeric month of year (1-12).
    D - numeric day of month (1 - 31).
    Z - Time Zone.
    h - Hour of the day.
    m - minute of the hour.
    s - seconds of the minute.
    . - (dot) milliseconds of the second.
    ^ - (carat) Microseconds of the second.

int  center( char* dest, char* src, int outSiz )
Center the string in the available space (outSIz).    The string will be padded with whitespace to move it to the center of the display space.

ulong  cidr2Rng( ulong* bgnIp, ulong* endIp, char* cidr )
Convert the CIDR to it's beginning and ending IP storing them in bgnIp and endIp.    This is a macro so that the addresses of the two Ips are passed in.    Returns ulong Cidr mask.

ulong  cidrCnt2Msk( int cnt )
Convert the CIDR count "cnt" to a netmask    Returns int count part of a CIDR else ERR if cnt > 32.

int  cntChr( char* str, int chr )
Count the number of incidences of the specified character in the string "str".

int  cpyPntbl( char* out, char* in )
Copy characters, converting non-ascii to DOTs, until a NULL is found.    Can be used on a single string.    Returns the count of chars.

int  crunch( char* out, char* in )
Compress multiple white space characters into single spaces (makes it easier to parse).    All whitespace characters in string "in" are compressed into string "out".    Caller must supply both input and output strings.    Input and output may be the same string.

int  crunchChr( char* str, int chr )
Remove all characters matching "chr" in string "str".   

int  cTrans( char* str, xlatC_t* table, int tblLen )
Initialize a character translation table. A C program can translate character codes by using the input character as the index into the xlatC_t table and using the character coming from the table. This can also be used to test a character against a large number of possible values.

int  dec2hex( char* buf, int len )
Convert an ascii string of comma seperated decimal numbers into a hexadecimal array.    Returns the output length.

int  decat( char* out, char* in, char* match )
Decatenate the matching string from in into the out string. The remainaing characters in the input string are then moved forward to the beginning of the input string. Return OK else NOTFND.

int  decatChr( char* out, char* in, int matchChr )
Decatenate the input string at the first occurrence of the matching character. The remainaing characters in the input string are then moved forward to the beginning of the input string. Return OK else NOTFND.

int  decatCol( char* output, char* input, int col )
Decatenate the input string at the specified column. The remainaing characters in the input string are then moved forward to the beginning of the input string. Return OK else NOTFND.

int  decatWd( char* out, char* in )
Decatenate the first word (foloowed by white space) from input string into the output string. The remainaing characters in the input string are then moved forward to the beginning of the input string. Return OK else NOTFND.

int  decatWsp( char* out, char* in )
Decatenate white space from the fron of the input string. The remainaing characters in the input string are then moved forward to the beginning of the input string. Return OK else NOTFND.

ulong  dq2ul( char* quad )
Convert the dotted quad IP to a ulong.    Return the ulong containing the IP in host order.

char*  dq2oct( uchar* octOut, char* dqIn )
Convert the supplied IP in ascii dotted-quad ("dqIn") to 4 unsigned characters ("octOut") representing the 4 octets of the ascii dotted quad.   

int  expTabs( char* io )
Expand all tabs in the io string into spaces. The string will grow as a result of this. Return OK.

int  fmtCat( char* output, char* fmt, elipsis ... )
Concatenate the format "fmt" and the arguments elipsis into the string "output".    Uses the same format rules as sprintf.

int  fmtSiz( char* str, int factor )
Estimate the size of the formatted string, where "str" is the format string and factor is a multipler for each substitution.    Return: strlen(str)+(cntChr(str,PERCENT)*factor)+1.

char*  fndChr( char* str, int chr )
Find a character (chr) in the string. Return a pointer the the matching string character else NULL.

char*  fndChrs( char* str, char* list )
Find a character from list in the string. Return a pointer the the matching character else NULL.

char*  fndStr( char* str, char* match )
Find a string within the input string (str) which matches the match string. Return a pointer to this sub-string else NULL.

char*  fndLast( char* str, int chr )
Find the last occurrence of the character (chr) in string (str). Return a pointer to the matching character else NULL.

char*  fndNxtFld( char* str )
Find the next field which is delimited by white space (skip non-whitespace, then skip whitespace). Return pointer to the next field else NULL.

char*  fndWsp( char* str )
Find the next whitespace in the string. Return a pointer to the next field else NULL.

char*  getNxtFld( char* save, int delimiter )
???? I think the leading field is stripped off.

long  hex2bin( char* inputHex )
Convert ascii hexadecimal characters to a long integer.

int  isBlnkLin( char* str )
Return True if the string is blank after removing any comments (delimited by #) else FALSE.

char*  intStr( strInt_t* tb, int val )
Convert an integer into a string. Search the strInt_t table for a matching integer value.    Return the string pointer else NULL.    The strInt_t table structure.
typedef struct strInt {
     char      *name;     
     int      val;
     pfi_t      func;
} strInt_t;

Two macros are available for easily building a strInt_t table, they are, STRINTBGN( tableName ) and STRINTEND.
The STRINTBGN supplies the table name (or array name) which will be referenced in invocations of strInt().
STRINTBGN( tableName )
     { "NAME1", Value1, NULL },
     { "NAME2", Value2, NULL },
STRINTEND
The NULL supplies a void function pointer which would be strVect() calls.     

int  lftJust( char* dest, char* src, int outSiz )
Left justify a string in the display space specified by outSiz. Return OK else NOTFND.

int  merge( char* out, char* src, char** vals, int delim )
Merge the template 'src' string with values from the 'vals' array and place the resulting string into the 'out' buffer.    If the template contains the 'delim' character followed by integer digits, with a value greater than zero, the value is used as the index into the 'vals' array.    The string from the vals array is merged into the template replacing the delimiter and it's following digits.    Neither the template nor the vals array are changed.    There are no limits on how many delimiters may be included in the template.    The evaluated integers (vals indexes) are checked for greater than zero and less than or equal to the size of the 'vals' array minus one.   
char *templ[] = [ "Hello %01, I see you." };
char *Vals[] = {NULL,"Jack"};
passed into the merge function would yield: "Hello Jack, I see you.".    This is handy for things like building HTML pages from 'C' cgi.    Coming attractions: I am thinking about adding an optional second PERCENT after the numeric value followed by another numeric value.    This would cause the following lines of code to be looped through, the number of times specified in the second value.    The loop would be terminated by a double PERCENT, and all PERCENT values would be offset by the index value.
Merge is a macro redirecting to _merge which has an additional argument for the size of the 'vals' array.

int  msk2CidrCnt( ulong mask )
Convert the 32 bit "mask" to a cidr count.    Returns cidr count.

int  noWsp( char* io )
Compress tabs and spaces in the string ":io".

char*  nxtFld( char* in )
Skip the first field (delimited by whitespace) in the string and return a pointer to the nextone else NULL.

char*  nxtHr( int hr )
Increment the supplied hour and return the incremented value.    If the hour increments past midnight, wrap it back to zero.

int  oct2dq( char* dq, uchar* oct )
Convert the 4 unsigned character octets ("oct") to a dotted quad ascii string at "dq".

int  parse( char* string, int delim, char* pa )
Parse the input 'string', using the 'delim' character into sub-strings.    Place pointers to these sub-string into the parse araay 'pa'.    Unless the delimiter is negative, each sub-string is trimmed.    A negative delimiter would be 0 - '%' or negative PERCENT.    Return number of resulting substrings.    Parse is a macro redirected to _parse, which has a fourth argument for the number of entries in the parse array 'pa'.    This may be used when you allocate space for the parse array.    The resulting prototype is:
int _parse( char *str, int delim, char *pa[], int paCnt )

int  _parse( char* string, int delim, char* pa, int paCnt )
Parse the input 'string', using the 'delim' character into sub-strings.    Place pointers to these sub-string into the parse araay 'pa'.    The argument "paCnt" is the number of entries in the pa array (you may have malloced an array based on running cntChr().    Unless the delimiter is negative, each sub-string is trimmed.    A negative delimiter would be 0 - '%' or negative PERCENT.    Return number of resulting substrings.    Parse is a macro redirected to _parse, which has a fourth argument for the number of entries in the parse array 'pa'.    This may be used when you allocate space for the parse array.    The resulting prototype is:
int _parse( char *str, int delim, char *pa[], int paCnt )

int  prprNam( char* out, char* in )
Convert the input ":in" into a proper name and place in "out&qout;.    A proper name starts with a capital letter (Upper Case) and the remaining characters are lower case.

int  replChr( char* str, int old, int new )
Replace each incidence of character old with character new in string str.    Return Number of chars replaced.

int  replChrs( char* str, strInt_t* table )
Look up each character in "str" int the strInt_t "table" if result is non-zero replace original string character with the one from strInt_t.;    Return Number of chars replaced.

int  rmWsp( char* str )
Remove all whitespace from string "str" (str will shrink in length).

int  rng2Cidr( char* cidr, ulong bgnIp, ulong endIp )
Convert the beginning and ending IPs to the equivalent CIDR.    The cidr is stored into the string 'cidr'.    Returns OK.

int  rtJust( char* dest, char* src, int outSiz )
int rtJust( char* dest, char* src, int outSiz );

int  shrpn( char* buf, int len )
Sharpen (opposite of "blur") a hex array into an ascii string.    Requires the input array length.    Returns the output length.

char*  skpChr( char* str, int chr )
Skip characters matching "chr", return a pointer to the first non-"chr" in string str.

char*  skpDigs( char* str )
Skip characters matching digits 0-9, return a pointer to the first non-digit in string str.

char*  skpStr( char* str )
The first character in the string "str" is the delimiter. Find the next character matching as escape character.

char*  skpWsp( char* str )
Skip leading whitespace (TAB or SPACE) characters in "str" returning a pointer to the first non-whitespace.

int  strLencnt( char* str )
Count the number of characters ignoring non-ascii until the NULL char.    Returns the count of chars.

char*  stripChr( char* str, char* tbl )
Remove characters from string "str" if they exist in table "tbl". Note this may change

int  strInt( strInt_t* tbl, char* src )
Look up the string "str" in table "tbl", returning the associated integer.    The strInt_t table structure.
typedef struct strInt {
     char      *name;     
     int      val;
     pfi_t      func;
} strInt_t;

Two macros are available for easily building a strInt_t table, they are, STRINTBGN( tableName ) and STRINTEND.
The STRINTBGN supplies the table name (or array name) which will be referenced in invocations of strInt().
STRINTBGN( tableName )
     { "NAME1", Value1, NULL },
     { "NAME2", Value2, NULL },
STRINTEND
The NULL supplies a void function pointer which would be strVect() calls.

void  strLcp( char* dest, char* src )
Copy characters from "src" to "dest" converting each to lower case.

char*  strLc( char* str )
Convert the string "str" into all lower case characters.

int  strParse( char* strPtr, int delimChr, char** ptrArry )
Break the input string "strPtr" into multiple strings at each occurance of delimChr and number of fields (pointers int "ptrArry").

void  strUcp( char* dest, char* src )
Copy characters from "src" to "dest" converting them to uppercase.

char*  strUc( char* str )
Convert all characters in "str" to uppercase.

pfi_t  strVect( strInt_t* tbl, int tblCnt, char* in )
Convert the input string "in"to a vector (function pointer) by looking it up in table "tbl".    The strInt_t table structure.
typedef struct strInt {
     char      *name;     
     int      val;
     pfi_t      func;
} strInt_t;

Two macros are available for easily building a strInt_t table, they are, STRINTBGN( tableName ) and STRINTEND.
The STRINTBGN supplies the table name (or array name) which will be referenced in invocations of strInt().
STRINTBGN( tableName )
     { "NAME1", 0, function_1 },
     { "NAME2", 0, function_2 },
STRINTEND

In this table if the string "NAME1" is supplied to intVect, it will return a pointer to the function "function_1".

pfi_t  strVectU( strInt_t* tbl, int tblCnt, char* in )
Convert the input string "in"to a vector (function pointer) by looking it up it's upper case values in table "tbl".    The strInt_t table structure.
typedef struct strInt {
     char      *name;     
     int      val;
     pfi_t      func;
} strInt_t;

Two macros are available for easily building a strInt_t table, they are, STRINTBGN( tableName ) and STRINTEND.
The STRINTBGN supplies the table name (or array name) which will be referenced in invocations of strInt().
STRINTBGN( tableName )
     { "NAME1", 0, function_1 },
     { "NAME2", 0, function_2 },
STRINTEND

In this table if the string "NAME1" is supplied to intVect, it will return a pointer to the function "function_1".

int  substr( char* strOut, char* strIn, int offset, int len )
Copy a subset of the input string to the output string.    A group of characters of length "len" is copied to the output string "strOut" starting from the "offset"th position in the input string "strIn".    This is a macro using memcpy and appending a NULL character after the output string.

int  trim( char* dest, char* src )
Skip leading whitespace and truncate trailing whitespace, copying from "src" to "dest".

char*  ul2dq( ulong ip )
Convert the supplied ulong IP to host order then to dotted quad.    Returns semi-static pointer to buffer containing dotted quad IP.    The string is in a static rotating array of 16, so it will be re-used by the 16th call after the current call.    Do not attempt free the returned string.

char*  ul2oct( uchar* octOut, ulong ip )
Convert the supplied ulong IP ("ip") to 4 unsigned character bytes ("octOut") (representing the 4 octets of the dotted quad).

char*  zotChr( char* str, int chr )
Find the first occurence of "chr" in "str", replace it with a NULL and return a pointer to the following character else NULL.

char*  zotLast( char* str, int chr )
Find the last occurence of "chr" in "str", replace it with a NULL and return a pointer to the following character.

char*  zotStr( char* str, char* mtch )
Find the first occurence of the string "mtch" in "str", replace the first character of the matching sub-string with a NULL and return a pointer to the character following the matching sub-string else NULL.