TLString Class Reference

Thread-save reference-counting string class. More...

#include <tlstring.h>

Collaboration diagram for TLString:

[legend]List of all members.


Public Member Functions
	TLString ()
	Create a NULL string (NULL ref).
	TLString (const char *str)
	Create a string.
	TLString (const TLString &s)
	Copy a string (i.e. reference it).
	TLString (const char strA, const char strB)
	Create a string which is the concatenation of both passed strings.
	TLString (const char *strA, const TLString &strB)
	Create a string which is the concatenation of both passed strings.
	TLString (const TLString &strA, const char *strB)
	Create a string which is the concatenation of both passed strings.
	TLString (const TLString &strA, const TLString &strB)
	Create a string which is the concatenation of both passed strings.
	~TLString ()
	Destructor: dereference.
TLString &	operator= (const TLString &s)
	Normal assignment, i.e. reference.
TLString &	operator= (const char *str)
	Assign a NUL-terminated string.
void	assign (const char *str, size_t len)
	Assign a string with specified length.
void	deref ()
	This is like assigning a NULL ref,.
bool	operator! () const
	This can be used to check for NULL refs.
	operator bool () const
	This can be used to check for NULL refs.
size_t	length () const
	Get length of string; 0 for NULL refs.
const char *	str () const
	Get pointer to internally stored string.
char	operator[] (size_t idx) const
	Get one char in the string. Returns NUL if out of range.
void	append (const char *str)
	Append a NUL-terminated string.
void	append (const char *str, size_t len)
	Append a (non-terminated) string with passed length.
TLString &	operator+= (const char *str)
	Append a NUL-terminated string.
void	append (const TLString &str)
	Append string.
TLString &	operator+= (const TLString &str)
	Append string.
void	prepend (const char *str)
	Prepend string.
void	prepend (const TLString &str)
	Prepend string.
void	sprintf (const char *fmt,...) _fnformat_(__printf__
	sprintf() functionality.
void	vsprintf (const char *fmt, va_list ap)
	Version of sprintf() with va_list argument.
void	trunc (size_t len, bool do_not_shrink=0)
	Truncate the string to specified length.
void	skip (size_t n)
	Skip the first n chars in the string.
int	zero ()
	Zero out the string.
ssize_t	index (char c) const
	Return index of first occurance of passed character in string.
ssize_t	rindex (char c) const
	Return index of last occurance of passed character in string.
ssize_t	find (const char *str) const
ssize_t	find (const TLString &str) const
ssize_t	rfind (const char *str) const
	Like find() but from backwards.
ssize_t	rfind (const TLString &str) const
size_t	TightenSize ()
	Make sure the string does not consume more memory than needed.
int	compare (const TLString &strB)
	Compare two strings.
Static Public Member Functions
TLString	ParseString (const char *instr, ssize_t inlen, SError &error)
	Parse C-like string.
Private Member Functions
void	_aqref () const
void	_deref () const
void	_aqrefN () const
void	_derefN () const
void	_detachN ()
	Detach the data.
void	_detach ()
	Detach the data.
void	_storeN (const char *str)
	Store passed string, no NULL check.
void	_storeN (const char *str, size_t len)
void	_storeN (const TLString &str)
void	_referenceN (const TLString &str)
	Reference passed string, no NULL check.
Private Attributes
SData *	d
	Internally used ref-counting data structure.
Friends
bool	operator== (const TLString &strA, const TLString &strB)
bool	operator== (const TLString &strA, const char *strB)
bool	operator< (const TLString &strA, const TLString &strB)
bool	operator< (const TLString &strA, const char *strB)
bool	operator> (const TLString &strA, const char *strB)
bool	operator<= (const TLString &strA, const TLString &strB)
bool	operator<= (const TLString &strA, const char *strB)
bool	operator>= (const TLString &strA, const char *strB)

Detailed Description

Thread-save reference-counting string class.

Author:: Wolfgang Wieser ] wwieser (a) gmx <*> de [

This is a general purpose string class for storage and manipulation of strings.

Note:: This class can deal with NUL-terminated as well as non-NUL-term strings. All strings will be NUL-terminated, however all methods of the class can deal with stray NUL inside the strings, so you can store arbitrary "binary" data.

Definition at line 53 of file tlstring.h.

Constructor & Destructor Documentation

TLString::TLString ( ) [inline]

Create a NULL string (NULL ref).

Definition at line 156 of file tlstring.h.
References d.
Referenced by ParseString().

TLString::TLString ( const char * str ) [inline]

Create a string.

Definition at line 158 of file tlstring.h.
References d.

TLString::TLString ( const TLString & s ) [inline]

Copy a string (i.e. reference it).

Definition at line 161 of file tlstring.h.
References _aqref(), and d.

TLString::TLString ( const char * strA,

const char * strB

)

Create a string which is the concatenation of both passed strings.

Definition at line 702 of file tlstring.cc.
References _storeN(), d, TLString::SData::len, and TLString::SData::str.

TLString::TLString ( const char * strA,

const TLString & strB

)

Create a string which is the concatenation of both passed strings.

Definition at line 718 of file tlstring.cc.
References _aqrefN(), _derefN(), _referenceN(), _storeN(), d, TLString::SData::len, and TLString::SData::str.

TLString::TLString ( const TLString & strA,

const char * strB

)

Create a string which is the concatenation of both passed strings.

Definition at line 736 of file tlstring.cc.
References _aqrefN(), _derefN(), _referenceN(), _storeN(), d, TLString::SData::len, and TLString::SData::str.

TLString::TLString ( const TLString & strA,

const TLString & strB

)

Create a string which is the concatenation of both passed strings.

Definition at line 753 of file tlstring.cc.
References _aqrefN(), _derefN(), _referenceN(), d, TLString::SData::len, and TLString::SData::str.

TLString::~TLString ( ) [inline]

Destructor: dereference.

Definition at line 171 of file tlstring.h.
References _deref().

Member Function Documentation

void TLString::_aqref ( ) const [inline, private]

Definition at line 117 of file tlstring.h.
References d, AtomicInt::inc(), and TLString::SData::refcnt.
Referenced by _referenceN(), operator=(), and TLString().

void TLString::_aqrefN ( ) const [inline, private]

Definition at line 119 of file tlstring.h.
References d, AtomicInt::inc(), and TLString::SData::refcnt.
Referenced by compare(), find(), operator<(), operator<=(), operator==(), operator>(), operator>=(), rfind(), and TLString().

void TLString::_deref ( ) const [inline, private]

Definition at line 118 of file tlstring.h.
References d, AtomicInt::DecAndTest(), and TLString::SData::refcnt.
Referenced by assign(), deref(), operator=(), vsprintf(), and ~TLString().

void TLString::_derefN ( ) const [inline, private]

Definition at line 120 of file tlstring.h.
References d, AtomicInt::DecAndTest(), and TLString::SData::refcnt.
Referenced by _detachN(), compare(), find(), operator<(), operator<=(), operator==(), operator>(), operator>=(), rfind(), skip(), TLString(), trunc(), and zero().

void TLString::_detach ( ) [inline, private]

Detach the data.
This means: Make a private copy if the ref count is larger than 1.
With NULL check for *d.
Definition at line 140 of file tlstring.h.
References _detachN(), and d.

void TLString::_detachN ( ) [inline, private]

Detach the data.
This means: Make a private copy if the ref count is larger than 1.
No NULL check for *d.
Definition at line 128 of file tlstring.h.
References _derefN(), d, TLString::SData::refcnt, and AtomicInt::val().
Referenced by _detach(), append(), and prepend().

void TLString::_referenceN ( const TLString & str ) [inline, private]

Reference passed string, no NULL check.

Definition at line 151 of file tlstring.h.
References _aqref(), and d.
Referenced by append(), prepend(), and TLString().

void TLString::_storeN ( const TLString & str ) [inline, private]

Definition at line 147 of file tlstring.h.
References d.

void TLString::_storeN ( const char * str,

size_t len

) [inline, private]

Definition at line 145 of file tlstring.h.
References d.

void TLString::_storeN ( const char * str ) [inline, private]

Store passed string, no NULL check.

Definition at line 143 of file tlstring.h.
References d.
Referenced by append(), prepend(), skip(), and TLString().

void TLString::append ( const TLString & str )

Append string.

Definition at line 147 of file tlstring.cc.
References _detachN(), TLString::SData::_EnsureSize(), _referenceN(), d, TLString::SData::len, and TLString::SData::str.

void TLString::append ( const char * str,

size_t len

)

Append a (non-terminated) string with passed length.

Definition at line 131 of file tlstring.cc.
References _detachN(), TLString::SData::_EnsureSize(), _storeN(), d, TLString::SData::len, and TLString::SData::str.

void TLString::append ( const char * str )

Append a NUL-terminated string.

Definition at line 115 of file tlstring.cc.
References _detachN(), TLString::SData::_EnsureSize(), _storeN(), d, TLString::SData::len, and TLString::SData::str.
Referenced by operator+=(), and StringTreeDump::write().

void TLString::assign ( const char * str,

size_t len

) [inline]

Assign a string with specified length.

Definition at line 181 of file tlstring.h.
References _deref(), and d.
Referenced by VM::InstructionStorage::DumpInstruction(), VM::VarType::TypeString(), and VM::FuncType::TypeString().

int TLString::compare ( const TLString & strB )

Compare two strings.
This function returns -1, 0, +1 depending on whether strB is <, == or > than *this. This is much like strcmp(3).
Returns -2 or +2 if *this or strB is NULL.
Returns 0 if both are NULL.
Definition at line 225 of file tlstring.cc.
References _aqrefN(), _derefN(), d, TLString::SData::len, and TLString::SData::str.

void TLString::deref ( ) [inline]

This is like assigning a NULL ref,.

Definition at line 185 of file tlstring.h.
References _deref(), and d.
Referenced by VM::AssemblerFile_Plaintext::_WriteSymbols_Recursive(), VM::NamespaceInfo::DumpTree(), and VM::ClassInfo::DumpTree().

ssize_t TLString::find ( const TLString & str ) const

Definition at line 632 of file tlstring.cc.
References _aqrefN(), _derefN(), d, TLString::SData::len, ssize_t, and TLString::SData::str.

ssize_t TLString::find ( const char * str ) const

Find first occurance of str in this string; return index or -1.
Todo:
Implement fancy Boyer-Moore searching for longer strings :)

Definition at line 623 of file tlstring.cc.
References d, TLString::SData::len, memfind(), ssize_t, and TLString::SData::str.

ssize_t TLString::index ( char c ) const

Return index of first occurance of passed character in string.
Returns -1 if not found.
Definition at line 585 of file tlstring.cc.
References d, TLString::SData::len, ssize_t, and TLString::SData::str.

size_t TLString::length ( ) const [inline]

Get length of string; 0 for NULL refs.

Definition at line 193 of file tlstring.h.
References d, and TLString::SData::len.
Referenced by StringTreeDump::Entry::RemoveEnd(), and StringTreeDump::write().

TLString::operator bool ( ) const [inline]

This can be used to check for NULL refs.

Definition at line 190 of file tlstring.h.
References d.

bool TLString::operator! ( ) const [inline]

This can be used to check for NULL refs.

Definition at line 188 of file tlstring.h.
References d.

TLString& TLString::operator+= ( const TLString & str ) [inline]

Append string.

Definition at line 221 of file tlstring.h.
References append().

TLString& TLString::operator+= ( const char * str ) [inline]

Append a NUL-terminated string.

Definition at line 215 of file tlstring.h.
References append().

TLString& TLString::operator= ( const char * str ) [inline]

Assign a NUL-terminated string.

Definition at line 178 of file tlstring.h.
References _deref(), and d.

TLString& TLString::operator= ( const TLString & s ) [inline]

Normal assignment, i.e. reference.

Definition at line 174 of file tlstring.h.
References _aqref(), _deref(), and d.

char TLString::operator[] ( size_t idx ) const [inline]

Get one char in the string. Returns NUL if out of range.

Definition at line 207 of file tlstring.h.
References d, TLString::SData::len, and TLString::SData::str.

TLString TLString::ParseString ( const char * instr,

ssize_t inlen,

SError & error

) [static]

Parse C-like string.

Author:
Klaus Sausen (nicolasius § users.sourceforge.net), Wolfgang Wieser ] wwieser (a) gmx <*> de [
This function will parse a C-like string by substituting escape sequences and even allows for NUL chars inside the output string. The input string is NUL-terminated but may contain embedded NUL chars if the length is specified.
If an error occurs, the error is returned in the passed SError class using the [FIXME] default domain and the code 1 (FIXME).
All characters in the input with the exception of the escape char "\" (and possibly the first and last double quote as well as whitespace in between, see below) are copied into the destination string.
The following escape sequences are recognized:

the usual ones: \a \b \f \n \r \t \v \\ \' \" \0

hexadecimal character spec ala \x1f

hex dword ala \Xcafe

octal character spec like \0123

control sequences aka \^A .. \^Z

Note that there is a potential pitfall with octal and hexadecimal character specification. E.g. \x1f could be read as a 1-char followed by a 'f' or as a 0x1f-char. Such ambiguities are resolved in that the longest _valid_ escape sequence is read. For example "\x1ff" is '\x1f' and 'f' while "\x1gf" is '\x1', 'g' and 'f'. Similarly, "\0123a" is '\0123' and 'a' while "\0423a" is '\042', '3' and 'a' since octal 0423 = 257 and out of character range (0..255). Hex digits can be specified as upper or lower case, however at least one must be there. Unknown escape sequences cause an error (and are copied unchanged) the escape \ is ignored in this case.
Normally, the input string will start with a double quote as the first character and end with one as the last character. The first and last double quotes will then not be part of the parsed string. Furthermore, if non-escaped double quotes are found in the text, then the text between them is ignored if it is whitespace or a single '\' followed by a newline (otherwise an error occurs). This can be used to parse continued strings like:
"this is the string which"
"stretches over two lines"
Hence, both the inner double quotes and the whitespace between them are not part of the parsed string. (Of course, whitespace after the last double quote until the end of the input buffer is ignored as well.)
In case the _first_ char is _not_ a double quote, the double quote recognition is not performed and any double quote is copied into the destination string just as any other normal character.

Parameters:

instr: The string to parse, something like "the\\nstring".

inlen: Length of the string to parse or <0 if strlen() shall be used.

error: In case an error occurs, it is stored here, otherwise it contains success.

Returns:
The parsed string is returned. Note that it can contain embedded NUL chars.

Todo:
ParseString(): Improve error handling (accumulation of errors); also remove some comments about fixed bugs...

Definition at line 22 of file parsestring.cc.
References TLString::SData::asize, Assert, SError::clear(), d, TLString::SData::DownSizeIfNeeded(), int8, TLString::SData::len, ssize_t, TLString::SData::str, and TLString().

void TLString::prepend ( const TLString & str )

Prepend string.

Definition at line 197 of file tlstring.cc.
References _detachN(), TLString::SData::_EnsureSize(), _referenceN(), d, TLString::SData::len, and TLString::SData::str.

void TLString::prepend ( const char * str )

Prepend string.

Definition at line 180 of file tlstring.cc.
References _detachN(), TLString::SData::_EnsureSize(), _storeN(), d, TLString::SData::len, and TLString::SData::str.
Referenced by _ParseInt(), _ParseUInt(), and VM::NamespaceInfo::CompleteName().

ssize_t TLString::rfind ( const TLString & str ) const

Definition at line 675 of file tlstring.cc.
References _aqrefN(), _derefN(), d, TLString::SData::len, ssize_t, and TLString::SData::str.

ssize_t TLString::rfind ( const char * str ) const

Like find() but from backwards.

Definition at line 659 of file tlstring.cc.
References d, TLString::SData::len, ssize_t, and TLString::SData::str.

ssize_t TLString::rindex ( char c ) const

Return index of last occurance of passed character in string.
Returns -1 if not found.
Definition at line 593 of file tlstring.cc.
References d, TLString::SData::len, ssize_t, and TLString::SData::str.

void TLString::skip ( size_t n )

Skip the first n chars in the string.

Definition at line 459 of file tlstring.cc.
References _derefN(), _storeN(), d, TLString::SData::DownSizeIfNeeded(), TLString::SData::len, TLString::SData::refcnt, TLString::SData::str, and AtomicInt::val().

void TLString::sprintf ( const char * fmt,

...

)

sprintf() functionality.
Like printf() for TLString. The passed format string and args are formatted into the string, replacing the current value of the string.
The string is first formatted into a 64 bytes prealloc buffer via vsnprintf() to see how long it will get. If less that 64 bytes, the result is simply copied otherwise it is re-formatted using vsnprintf() again.
Definition at line 576 of file tlstring.cc.
References vsprintf().
Referenced by _ParseFloat(), _ParseInt(), VM::AssemblerFile_Plaintext::_ParseProgram_Label(), VM::AssemblerFile_Plaintext::_ParseSymbols_Symbols(), _ParseUInt(), VM::AssemblerFile_Plaintext::_WriteSymbols_Global(), VM::AssemblerFile_Plaintext::_WriteSymbols_Recursive(), VM::NamespaceInfo::DumpTree(), VM::ClassInfo::DumpTree(), _InternalSourceFileNode::IncludeHierarchyStr(), _InternalSourcePosition::PosRangeString(), _InternalSourcePosition::PosString(), and _InternalSourcePosition::PosStringRelative().

const char* TLString::str ( ) const [inline]

Get pointer to internally stored string.
Be very careful with what you do with it.
The returned string is NUL-terminated with str[length()]=NUL or NULL in case of a NULL ref.
Definition at line 203 of file tlstring.h.
References d, and TLString::SData::str.
Referenced by VM::VMLinker::_CheckBaseRecursion_Recursive(), VM::VMLinker::_CheckNamespaceInfo_Recursive(), _DoParseFile(), VM::VMLinker::_GenerateSymbolProvideMap(), VM::VMLinker::_GenerateSymbolProvideMap_AddGlobal(), VM::VMLinker::_LinkerNeedClassConstruct(), VM::VMLinker::_LinkFunction(), VM::VMLinker::_LinkGlobalStorage(), VM::VMLinker::_MergeNamespaceInfo_Recursive(), VM::AssemblerFile_Plaintext::_ParseSymbols_Symbols(), VM::AssemblerFile::_ResolveIDsNamespaceLocal_Recursive(), VM::VMLinker::_SQPush(), VM::AssemblerFile_Plaintext::_WriteFunctionProgram(), VM::AssemblerFile_Plaintext::_WriteSymbols_Recursive(), VM::NamespaceInfo::DumpTree(), VM::ClassInfo::DumpTree(), MessageHandler_Console::HandleMessage(), VM::VMLinker::LinkAll(), main(), _InternalFlexScannerBase::LexerInput::OpenFile(), _InternalFlexScannerBase::LexerInput::read(), StringTreeDump::write(), and VM::AssemblerFile_Plaintext::WriteFile().

size_t TLString::TightenSize ( )

Make sure the string does not consume more memory than needed.
Returns amount of memory allocated (including overhead).
NOTE: Does actually nothing if this is not the only reference to the string. (The only thing we could do was to detach thereby allocation additional memory which is not what we are about when calling this.)
Definition at line 500 of file tlstring.cc.
References TLString::SData::asize, d, TLString::SData::refcnt, TLString::SData::TightenSize(), and AtomicInt::val().
Referenced by StringTreeDump::append(), and StringTreeDump::Entry::TightenSize().

void TLString::trunc ( size_t len,

bool do_not_shrink = 0

)

Truncate the string to specified length.
If the length is longer than the string, nothing is done.
If do_not_shrink is set, the memory chunk will NOT be shrinked. This is useful when new data is to be appended immediately. Only effective if this is the only reference to the string.
Definition at line 434 of file tlstring.cc.
References _derefN(), d, TLString::SData::DownSizeIfNeeded(), TLString::SData::len, TLString::SData::refcnt, TLString::SData::str, and AtomicInt::val().
Referenced by StringTreeDump::write().

void TLString::vsprintf ( const char * fmt,

va_list ap

)

Version of sprintf() with va_list argument.

Definition at line 509 of file tlstring.cc.
References _deref(), TLString::SData::asize, CritAssert, d, TLString::SData::EnsureSize(), TLString::SData::len, TLString::SData::refcnt, ssize_t, TLString::SData::str, and AtomicInt::val().
Referenced by _vaMessage(), and sprintf().

int TLString::zero ( )

Zero out the string.
Only effective, if this is the only reference to the string.
Does a deref() after zeroing.

Returns:
0 -> zeroed out or NULL ref; 1 -> only deref()

Definition at line 423 of file tlstring.cc.
References _derefN(), d, TLString::SData::len, TLString::SData::refcnt, TLString::SData::str, and AtomicInt::val().

Friends And Related Function Documentation

bool operator< ( const TLString & strA,

const char * strB

) [friend]

Definition at line 315 of file tlstring.cc.

bool operator< ( const TLString & strA,

const TLString & strB

) [friend]

The < and > operators return 0 if at least one string is NULL.
Definition at line 293 of file tlstring.cc.

bool operator<= ( const TLString & strA,

const char * strB

) [friend]

Definition at line 380 of file tlstring.cc.

bool operator<= ( const TLString & strA,

const TLString & strB

) [friend]

Definition at line 358 of file tlstring.cc.

bool operator== ( const TLString & strA,

const char * strB

) [friend]

Definition at line 270 of file tlstring.cc.

bool operator== ( const TLString & strA,

const TLString & strB

) [friend]

NOTE that two NULL refs are always equal; NULL strings behave like NULL refs.
Definition at line 253 of file tlstring.cc.

bool operator> ( const TLString & strA,

const char * strB

) [friend]

Definition at line 336 of file tlstring.cc.

bool operator>= ( const TLString & strA,

const char * strB

) [friend]

Definition at line 401 of file tlstring.cc.

Member Data Documentation

SData* TLString::d [private]

Internally used ref-counting data structure.

Definition at line 115 of file tlstring.h.
Referenced by _aqref(), _aqrefN(), _deref(), _derefN(), _detach(), _detachN(), _referenceN(), _storeN(), append(), assign(), compare(), deref(), find(), index(), length(), operator bool(), operator!(), operator<(), operator<=(), operator=(), operator==(), operator>(), operator>=(), operator[](), ParseString(), prepend(), rfind(), rindex(), skip(), str(), TightenSize(), TLString(), trunc(), vsprintf(), and zero().

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

/ray/src/lib/tl/tlstring.h
/ray/src/lib/tl/parsestring.cc
/ray/src/lib/tl/tlstring.cc

Generated on Sat Feb 19 22:35:52 2005 for Ray by

1.3.5

TLString Class Reference

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation