CString Class Reference

Description

Dynamically allocated string.

This is the main class used in the Home2L project for strings of arbitrary length. The strings storage (typically heap) may either be managed by this class, but it may also be managed by the caller in order to avoid memory duplication with constant strings, for example.

Definition at line 635 of file base.H.

#include "base.H"

Public Member Functions
	CString (const CString &str)
	Copy constructor.
Initialization...
void	Clear ()
void	Set (char c)
void	Set (const char *str, int maxLen=INT_MAX)
	Set (substring) from 'str'.
void	SetF (const char *fmt,...)
	Set using printf() formatting.
void	SetFV (const char *fmt, va_list ap)
	Set using vprintf() formatting.
void	SetC (const char *_ptr)
	Set without copying or taking ownership of '_ptr' (but "copy-on-write" semantics). This is more efficient than Set(), but requires '_ptr' to remain valid afterwards. '_ptr' must be a valid pointer (!= NULL).
Ownership optimizations ...
void	SetO (const char *_ptr)
	Set content and take ownership of '_ptr'. '_ptr' must have been dynamically allocated, since it will be free'd later using 'free ()'.
char *	Disown ()
	Return current string as a dynamic object and clear 'this'. More...
Character encoding (see special not on string encoding in this file) ...
void	SetFromIso8859 (const char *iso8859str)
	'this' will be a (normal) UTF-8 string, the source is expected to be ISO-8859
bool	SetAsIso8859 (const char *str)
	'this' will be ISO-8859-encoded string, the source is expected to be (normal) UTF-8
Read access ...
char *	Get () const
	Get the C string. Unless explicitely set by 'SetC', this will never return NULL or an invalid pointer.
int	Len ()
	Get the length.
bool	IsEmpty ()
	Check, if empty.
Modifications ...
void	Del (int n0, int dn=INT_MAX)
void	Insert (int n0, int dn, int *retInsPos=NULL)
void	Insert (int n0, char c)
void	Insert (int n0, const char *str, int maxLen=INT_MAX)
void	InsertF (int n0, const char *fmt,...)
void	InsertFV (int n0, const char *fmt, va_list ap)
void	Append (char c)
void	Append (const char *str, int maxLen=INT_MAX)
void	AppendF (const char *fmt,...)
void	AppendFV (const char *fmt, va_list ap)
Extras ...
int	Compare (const char *str2)
void	Strip (const char *sepChars=WHITESPACE)
void	Truncate (const char *sepChars=WHITESPACE, bool after=false)
void	Split (class CSplitString *args, int maxArgc=INT_MAX, const char *sepChars=WHITESPACE)
void	Split (int *retArgc, char ***retArgv, int maxArgc=INT_MAX, const char *sepChars=WHITESPACE)
void	AppendFByLine (const char *fmt, const char *text)
	Same as SetFByLine(), but appending the result to the current srtring.
void	SetFByLine (const char *fmt, const char *text)
	Split 'text' into lines and reassembles the text by processing each line through sprintf and 'fmt'. 'fmt' must contain no more than "%s" (or similar) conversion modifier and should contain a trailing ' '.
void	AppendEscaped (const char *s, const char *dontEscape=NULL)
	Same as 'Set...', but appending the result to the current srtring.
void	SetEscaped (const char *s, const char *dontEscape=NULL)
	Set and escape all non-alphanumerical characters by "\...". More...
bool	AppendUnescaped (const char *s)
	Same as 'Set...', but appending the result to the current srtring.
bool	SetUnescaped (const char *s)
	Set and revers escapes. On error, 'false' is returned and the string remains unchanged. If the string has been generated by one of the '...Escaped' methods above, it is restored precisely. However, any character except '\' are tolerated in the input string and will be copied into the destination.
Path handling ...
These methods do the same as the functions with the same name.
void	PathNormalize ()
void	PathRemoveTrailingSlashes ()
const char *	PathLeaf ()
void	PathGo (const char *where)
void	PathGoUp ()
Using CString as a file buffer ...
bool	ReadFile (const char *relOrAbsPath)
	Read a complete text file into a string. The path may be absolute or relative to HOME2L_ROOT.
bool	AppendFromFile (int fd, const char *name=NULL)
	Read as much as possible from 'fd' and append to buffer. If an end-of-file is encountered, 'false' is returned. 'fd' is NOT closed automatically. This method can be used to read a file (or pipe or socket) asynchronously. The optional argument 'name' is the stream name logged in case of an error/warning.
bool	ReadLine (CString *ret)
	Consume and optionally return the first line from 'this'. On success, 'true' is returned. If no complete line is available, 'false' is returned and 'this' is not changed. In 'this', each line ends with a ' '. The output ('retLine') does not contain the ' '. 'retLine' can be 'NULL', in which case the line is ignored.
Operators ...
	operator char * ()
CString &	operator= (const CString &str)
CString &	operator= (const char *str)
char &	operator[] (int n)
CString	operator+ (const char *str)
CString &	operator+= (char c)
CString &	operator+= (const char *str)
bool	operator< (const char *str)
bool	operator> (const char *str)
bool	operator<= (const char *str)
bool	operator>= (const char *str)
bool	operator== (const char *str)
bool	operator!= (const char *str)

Static Public Attributes
Static elements ...
static const char *const	emptyStr
	Use this whenever you need an empty string ("")

Member Function Documentation

Disown()

char* CString::Disown

(

)

Return current string as a dynamic object and clear 'this'.

The caller is responsible for freeing the pointer later using free().

Note: If the memory of 'ptr' was previously not owned, a dynamic copy will be returned. This guarantees, that 'free' can safely be called afterwards, but may be less efficient than leaving the ownership with the string object.

SetEscaped()

void CString::SetEscaped ( const char *  s, const char *  dontEscape = NULL  )

inline

Set and escape all non-alphanumerical characters by "\...".

     If 's' is empty, "\0" is appended, so that the resulting string is never empty.
     Any escape sequence according to the C99 standard may be used.
     In addition to the C standard, the following sequences may occur here:
     `'\\s' == ' ' (space)`

     By default, the resulting string does not contain any other characters besides
     '0'...'9', 'a'...'z', 'A'...'Z' and '\'. Even spaces are not contained.

     The 'dontEscape' parameter is a pragmatical option to improve the human-readability and
     memory consumption of the result. If set, characters in 'dontEscape' are not escaped. 

Definition at line 726 of file base.H.

---

The documentation for this class was generated from the following file:

• common/base.H