Strings

Description

Helper functions and classes for string handling.

A note on string encoding

By default, all strings use UTF-8 encoding. All length and position parameters are measured in bytes. Hence, they do not reflect the real numbers of characters, if characters other than ASCII 0..127 are used.

In cases, where this matters (e.g. in 'CInputLine'), the 'CString' class may alternatively carry ISO8859-1(-15?) encoded strings with a one-to-one correspondence between characters and bytes. The caller is responsible for making the necessary conversions in the right places.

By convention, strings that are not UTF8-encoded are marked with a comment containing 'ISO8859' at their declaration.

A note on dynamic memory ownership

Unless specified otherwise, pointers returned by functions or methods are references to some memory which remains owned by the callee. Its lifetime should be documented with the method or class. If unspecified, a pointer returned by a class method is valid until the respective object is destructed.

Collaboration diagram for Strings:

Classes
class	CString
	Dynamically allocated string. More...
class	CSplitString
	Factory class to split a string into substrings. More...
class	CRegex
	Factory class for regular expression matching. More...

Macros
#define	WHITESPACE   " \t\n\r\v"
	white space characters according to 'man 3 isspace'
#define	TTS   (GetThreadTempString ())
	Get the thread-local temporary string (TTS) of the calling thread (short version).

Functions
class CString *	GetThreadTempString ()
	Get the thread-local temporary string (TTS) of the calling thread. More...
const char *	StringF (class CString *ret, const char *fmt,...)
	Return 'ret->Get ()'.
bool	BoolFromString (const char *str, bool *ret)
	Convert a string to a Boolean value. On success, '*ret' is set accordingly and 'true' is returned. On failure, 'false' is returned and '*ret' remains unchanged.
bool	ValidBoolFromString (const char *str, bool defaultVal)
	Convert a string to a Boolean value. On failure, 'defaultVal' is returned.
bool	IntFromString (const char *str, int *ret, int radix=0)
	Convert a string to an integer using 'strtol'. On success, '*ret' is set accordingly and 'true' is returned. On failure, 'false' is returned and '*ret' remains unchanged. If 'radix == 0', it is auto-detected from the string (16 with a preceeding "0x", 10 otherwise).
int	ValidIntFromString (const char *str, int defaultVal, int radix=0)
	Convert a string to an integer. On failure, 'defaultVal' is returned.
bool	UnsignedFromString (const char *str, unsigned *ret, int radix=0)
	Convert a string to an unsigned integer using 'strtoul'. On success, '*ret' is set accordingly and 'true' is returned. On failure, 'false' is returned and '*ret' remains unchanged. If 'radix == 0', it is auto-detected from the string (16 with a preceeding "0x", 10 otherwise).
unsigned	ValidUnsignedFromString (const char *str, unsigned defaultVal, int radix=0)
	Convert a string to an unsigned integer. On failure, 'defaultVal' is returned.
bool	FloatFromString (const char *str, float *ret)
	Convert a string to a floating-point value using 'strtof'. On success, '*ret' is set accordingly and 'true' is returned. On failure, 'false' is returned and '*ret' remains unchanged.
float	ValidFloatFromString (const char *str, float defaultVal)
	Convert a string to a float value. On failure, 'defaultVal' is returned.
void	StringStrip (char *str, const char *sepChars=WHITESPACE)
	Remove seperator (whitespace) characters at the beginning and end of the string.
void	StringTruncate (char *str, const char *sepChars=WHITESPACE, bool after=false)
	Cut away anything from or after the first occurence of any of the given seperator characters.
void	StringSplit (const char *str, int *retArgc, char ***retArgv, int maxArgc=INT_MAX, const char *sepChars=NULL, char **retRef=NULL)
	Split a string into (whitespace-)separated arguments. More...
void	StringSplitFree (char ***argv)
	Free memory allocated by StringSplit(). More...
bool	CharIsWhiteSpace (char c)
	Indicate whether the given character is white space (see WHITSPACE).

Path handling ...
void	PathNormalize (char *str)
	Treat string as a (full) pathname and normalize it.
void	PathRemoveTrailingSlashes (char *str)
	Treat string as a (full) pathname and remove trailing slash(es)
const char *	PathLeaf (const char *str)
	Get leaf component of a path.
const char *	GetAbsPath (class CString *ret, const char *relOrAbsPath, const char *defaultPath)
	Get absolute path. More...

Transcoding ...
const char *	ToUtf8 (class CString *ret, const char *iso8859str)
	Transcode an ISO8859-coded string to UTF-8. Result is valid until next call of this function.
const char *	ToIso8859 (class CString *ret, const char *str)
	Transcode an ISO8859-coded string to UTF-8. Result is valid until next call of this function.

Function Documentation

GetThreadTempString()

class CString * GetThreadTempString

(

)

Get the thread-local temporary string (TTS) of the calling thread.

Sometimes, functions return a string and require the 'CString' object to be provided by the caller. Examples are the various 'ToStr ()' methods.

This function 'GetThreadTempString ()' returns a single CString object that can be used globally. To avoid synchronization issues, there is one thread-temporary string (TTS) per thread.

Use it and the TTS macro with care! By convention, it is not allowed to call any function or method outside of this module (Common) between the first use of TTS and the last use of the returned 'const char *' string.

StringSplit()

void StringSplit	(	const char *	str,
		int *	retArgc,
		char ***	retArgv,
		int	maxArgc = INT_MAX,
		const char *	sepChars = NULL,
		char **	retRef = NULL
	)

Split a string into (whitespace-)separated arguments.

The number of extracted words is written to *retArgc, an array of that size is returned via ***retArgv. If maxArgc-1 strings have been split, the complete remaining string is returned as argument #(maxArgc-1).

If sepChars == NULL, whitespace characters are used as separators, and multiple of them count as a single separation. In all other cases, each individual separation character splits up a new argument, so that empty arguments are possible.

The resulting (sub-)strings will be placed into a single chunk of heap-allocated memory. The caller must later (only) free *retArgv[0] and *retArgv or call StringSplitFree() on retArgv. str remains unchanged and owned by the caller. If 'retRef' is not NULL, a reference pointer is returned by which the caller can determine the original location of some argument or character. To avoid confusion about memory handling, it is recommended to use the class CSplitString instead of this function.

StringSplitFree()

void StringSplitFree

(

char ***

argv

)

Free memory allocated by StringSplit().

Parameters

argv	is the argument regArgv passed to StringSplit().

GetAbsPath()

const char * GetAbsPath	(	class CString *	ret,
		const char *	relOrAbsPath,
		const char *	defaultPath
	)

Get absolute path.

Parameters

ret	String to write the result to
relOrAbsPath	Input path
defaultPath	Default path

Returns

Normalized absolute path

If the input path starts with '/', it is considered an absolute path and returned unchanged.Otherwise, defaultPath is prepended, and the normalized path is returned.