X11 Work Bench Toolkit  1.0
Text Utilities (generic)

Generic Utility functions for copying and manipulating text. More...

Modules

 XML-specific Text Utilities
 Specialized text utility functions for parsing XML data.
 

Macros

#define NEXT_WORD(pX, pY, pZ)   {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}
 Obtain the 'next word' within a string pointed to by pX, bounded by pY and pZ. More...
 

Functions

char * WBCopyString (const char *pSrc)
 A simple utility that returns a WBAlloc() copy of a 0-byte terminated string. More...
 
char * WBCopyStringN (const char *pSrc, unsigned int nMaxChars)
 A simple utility that returns a WBAlloc() copy of a string up to a maximum length (can also be 0-byte terminated) More...
 
void WBCatString (char **ppDest, const char *pSrc)
 A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string. More...
 
void WBCatStringN (char **ppDest, const char *pSrc, unsigned int nMaxChars)
 A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string up to a maximum length (can also be 0-byte terminated) More...
 
void WBDeQuoteString (char *pszStr)
 De-Quote a string 'in place', that is modifying the original string by removing quotes. More...
 
int WBStringLineCount (const char *pSrc, unsigned int nMaxChars)
 Determine how many 'lines' are in a block of text by counting 'linefeed' characters. More...
 
const char * WBStringNextLine (const char *pSrc, unsigned int *pnMaxChars)
 Locate the next line in a block of text, returning its pointer (and updating remaining length) More...
 

Detailed Description

Generic Utility functions for copying and manipulating text.

Utility functions for copying and manipulating text, such as string copying and concatenation. These function standardize common string operations and allocate buffers with 'malloc()' as needed.

Macro Definition Documentation

#define NEXT_WORD (   pX,
  pY,
  pZ 
)    {while(*(pX) && *(pX) <= ' '){(pX)++;} (pY)=(pZ)=(pX); while(*(pX)>' '){(pX)++;} (pZ)=(pX);}

Obtain the 'next word' within a string pointed to by pX, bounded by pY and pZ.

Parameters
pXA pointer to a 0-byte terminated string; returned as the 'current' pointer within that string for further parsing
pYA pointer to the word that was found within the string
pZA pointer to the character just following the found word. If pY == pZ, no word was found (and *pX should be 0)

use this function in a loop to parse out the "next word" within the string until *pX == 0 or pY == pZ

Definition at line 702 of file platform_helper.h.

Function Documentation

void WBCatString ( char **  ppDest,
const char *  pSrc 
)

A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string.

Parameters
ppDestA pointer to a pointer to a WBAlloc() string containing the first portion of the concatenated result (also the return value)
pSrcA pointer to a character string to concatenate onto the end of the first string

This function concatenates two strings together. The first parameter must point to the character pointer variable that points to the first string to be concatenated. This must either be a WBAlloc() pointer or NULL, and the string itself must be 0-byte terminated. The second parameter points to a 0-byte terminated string, which does not have to be a WBAlloc() string. The function will overwrite the first pointer with WBAlloc() copy of the result of concatenating the two strings.
On error, the function does NOT modify ppDest and aborts the concatenate operation.

Header File: platform_helper.h

Definition at line 528 of file platform_helper.c.

void WBCatStringN ( char **  ppDest,
const char *  pSrc,
unsigned int  nMaxChars 
)

A simple utility that concatenates a string onto the end of a 0-byte terminated WBAlloc() string up to a maximum length (can also be 0-byte terminated)

Parameters
ppDestA pointer to a pointer to a WBAlloc() string containing the first portion of the concatenated result (also the return value)
pSrcA pointer to a character string to concatenate onto the end of the first string (can be 0-byte terminated)
nMaxCharsThe maximum number of characters to be concatenated, or until a 0-byte is found in pSrc

This function concatenates two strings together. The first parameter must point to the character pointer variable that points to the first string to be concatenated. This must either be a WBAlloc() pointer or NULL, and the string itself must be 0-byte terminated. The second parameter points to a POSSIBLY 0-byte terminated string, which does not have to be a WBAlloc() string. The function will overwrite the first pointer with WBAlloc() copy of the result of concatenating the two strings. The string 'pSrc' will be concatenated up to 'nMaxChars' or until a 0-byte is found, whichever happens first.
On error, the function does NOT modify pszStr1 and aborts the concatenate operation.

Header File: platform_helper.h

Definition at line 589 of file platform_helper.c.

char* WBCopyString ( const char *  pSrc)

A simple utility that returns a WBAlloc() copy of a 0-byte terminated string.

Parameters
pSrcA pointer to the original ASCII string (0-byte terminated)
Returns
a 'WBAlloc() copy of the string (0-byte terminated)

This function creates a 'WBAlloc() copy of szStr, up to the 0-byte. The returned string ALWAYS ends in a zero byte. The caller must deallocate the returned pointer using 'WBFree()'.
The function returns NULL on error.

Header File: platform_helper.h

Definition at line 465 of file platform_helper.c.

char* WBCopyStringN ( const char *  pSrc,
unsigned int  nMaxChars 
)

A simple utility that returns a WBAlloc() copy of a string up to a maximum length (can also be 0-byte terminated)

Parameters
pSrcA pointer to the original ASCII string (can be 0-byte terminated)
nMaxCharsThe maximum number of characters to be copied, or until a 0-byte is found
Returns
a 'WBAlloc() copy of the string (0-byte terminated)

This function creates a 'WBAlloc() copy of pStr, up to 'nMaxChars' or until a 0-byte is found, whichever happens first. The returned string ALWAYS ends in a zero byte. The caller must deallocate the returned pointer using 'WBFree()'.
The function returns NULL on error.

Header File: platform_helper.h

Definition at line 495 of file platform_helper.c.

void WBDeQuoteString ( char *  pszStr)

De-Quote a string 'in place', that is modifying the original string by removing quotes.

Parameters
pszStrA pointer to a (0-byte terminated) ASCII string that may contain quotes. Quotes are removed 'in place'

Often you need to be able to remove quote characters from a string in a standardized manner. This function handles just about every standard quoting method available, including the use of double-quotes to indicate a quote within a quoted string, the use of single or double quotes, etc.

Header File: platform_helper.h

Definition at line 655 of file platform_helper.c.

int WBStringLineCount ( const char *  pSrc,
unsigned int  nMaxChars 
)

Determine how many 'lines' are in a block of text by counting 'linefeed' characters.

Parameters
pSrcA const pointer to an ASCII or UTF8 string (may end in zero byte)
nMaxCharsThe maximum number of characters in the buffer
Returns
The total number of lines (including blank lines)

Use this function to determine how many lines are in the block of text. A line is considered to be a string of 1 or more characters, ending in a zero byte [or end of text as determined by 'nMaxChars'], or one of the following sequences: <CRLF>, <LF>, <CR>, or <LFCR>

Header File: platform_helper.h

Definition at line 698 of file platform_helper.c.

const char* WBStringNextLine ( const char *  pSrc,
unsigned int *  pnMaxChars 
)

Locate the next line in a block of text, returning its pointer (and updating remaining length)

Parameters
pSrcA const pointer to an ASCII or UTF8 string (may end in a zero byte)
pnMaxCharsA pointer to an integer containing maximum number of characters in the buffer
Returns
A pointer to the next line, the character just following a <CRLF>, <LF>, <CR>, or <LFCR> sequence.

Use this function to find the 'next line' in a block of text. It will also update the number of characters remaining in the buffer, and store the result in '*pnMaxChars'. If 'pnMaxChars' is NULL, the string buffer is assumed to terminate with a zero-byte.

Header File: platform_helper.h

Definition at line 728 of file platform_helper.c.