ucommon::UString Class Reference

A copy-on-write utf8 string class that operates by reference count. More...

#include <unicode.h>

Inheritance diagram for ucommon::UString:

Collaboration diagram for ucommon::UString:

Protected Member Functions
void	add (const unicode_t unicode)
	Add (append) unicode to a utf8 encoded string. More...
ucs4_t	at (int position) const
	Return unicode character found at a specific codepoint in the string. More...
unsigned	ccount (ucs4_t character) const
	Count occurrences of a unicode character in string. More...
UString	copy (strsize_t offset, strsize_t size) const
	Convenience method for substring extraction. More...
strsize_t	count (void) const
	Count codepoints in current string. More...
void	cut (strsize_t offset, strsize_t size=0)
	Cut (remove) text from string using codepoint offsets. More...
const char *	find (ucs4_t character, strsize_t start=0) const
	Find first occurrence of character in string. More...
UString	get (strsize_t codepoint, strsize_t size=0) const
	Get a new string object as a substring of the current object. More...
size_t	get (unicode_t unicode, size_t size) const
	Extract a unicode byte sequence from utf8 object. More...
UString	left (strsize_t size) const
	Convenience method for left of string. More...
size_t	operator() (unicode_t unicode, size_t size) const
	Extract a unicode byte sequence from utf8 object. More...
UString	operator() (int codepoint, strsize_t size) const
	Get a new substring through object expression. More...
const char *	operator() (int offset) const
	Reference a string in the object by codepoint offset. More...
ucs4_t	operator[] (int position) const
	Reference a unicode character in string object by array offset. More...
void	paste (strsize_t offset, const char *text, strsize_t size=0)
	Insert (paste) text into string using codepoint offsets. More...
const char *	rfind (ucs4_t character, strsize_t end=npos) const
	Find last occurrence of character in string. More...
UString	right (strsize_t offset) const
	Convenience method for right of string. More...
void	set (const unicode_t unicode)
	Set a utf8 encoded string based on unicode data. More...
	UString ()
	Create a new empty utf8 aware string object.
	UString (strsize_t size)
	Create an empty string with a buffer pre-allocated to a specified size. More...
	UString (const unicode_t text)
	Create a utf8 aware string for a null terminated unicode string. More...
	UString (const char *text, strsize_t size)
	Create a string from null terminated text up to a maximum specified size. More...
	UString (const unicode_t *text, const unicode_t *end)
	Create a string for a substring. More...
	UString (const UString &existing)
	Construct a copy of a string object. More...
virtual	~UString ()
	Destroy string. More...
Protected Member Functions inherited from ucommon::String
virtual cstring *	c_copy (void) const
	Return cstring to use in copy constructors. More...
virtual void	cow (strsize_t size=0)
	Copy on write operation for cstring. More...
cstring *	create (strsize_t size, char fill=0) const
	Factory create a cstring object of specified size. More...
bool	equal (const char *string) const
	Test if two string values are equal. More...
strsize_t	getStringSize (void)
virtual void	release (void)
	Decrease retention of our reference counted cstring. More...
virtual void	retain (void)
	Increase retention of our reference counted cstring. More...

Additional Inherited Members
Public Types inherited from ucommon::String
enum	{ SENSITIVE = 0x00, INSENSITIVE = 0x01 }
	This is an internal class which contains the actual string data along with some control fields. More...
Public Member Functions inherited from ucommon::String
int	__isoc99_scanf (const char *format,...)
	Scan input items from a string object. More...
int	__isoc99_vscanf (const char *format, va_list args)
	Scan input items from a string object. More...
void	add (const char *text)
	Append null terminated text to our string buffer. More...
void	add (char character)
	Append a single character to our string buffer. More...
char	at (int position) const
	Return character found at a specific position in the string. More...
const char *	begin (void) const
	Get pointer to first character in string for iteration. More...
char *	c_mem (void) const
	Get memory text buffer of string object. More...
const char *	c_str (void) const
	Get character text buffer of string object. More...
strsize_t	ccount (const char *list) const
	Count number of occurrences of characters in string. More...
void	chop (const char *list)
	Chop trailing characters from the string. More...
void	chop (strsize_t count=1)
	Chop trailing characters from text. More...
const char *	chr (char character) const
	Find pointer in string where specified character appears. More...
void	clear (strsize_t offset, strsize_t size=0)
	Clear a field of a filled string with filler. More...
void	clear (void)
	Clear string by setting to empty.
int	collate (const char *string) const
virtual int	compare (const char *string) const
	Compare the values of two string. More...
String	copy (strsize_t offset, strsize_t size) const
	Convenience method for substring extraction. More...
strsize_t	count (void) const
	Count all characters in the string (strlen). More...
void	cut (strsize_t offset, strsize_t size=0)
	Cut (remove) text from string. More...
const char *	end (void) const
	Get pointer to last character in string for iteration. More...
void	erase (void)
	Erase string memory.
char	fill (void)
	Get filler character used for field array strings. More...
const char *	find (const char *list, strsize_t offset=0) const
	Find a character in the string. More...
bool	full (void) const
	Test if the string's allocated space is all used up. More...
String	get (strsize_t offset, strsize_t size=0) const
	Get a new string object as a substring of the current object. More...
String	left (strsize_t size) const
	Convenience method for left of string. More...
strsize_t	len (void) const
	Get length of string. More...
void	lower (void)
	Convert string to lower case.
strsize_t	offset (const char *pointer) const
	Find offset of a pointer into our string buffer. More...
	operator bool () const
	Test if string has data. More...
	operator const char * () const
	Casting reference to raw text string. More...
bool	operator! () const
	Test if string is empty. More...
bool	operator!= (const char *text) const
	Compare our object with null terminated text. More...
String &	operator% (short &value)
	Parse short integer value from a string. More...
String &	operator% (unsigned short &value)
	Parse long integer value from a string. More...
String &	operator% (long &value)
	Parse long integer value from a string. More...
String &	operator% (unsigned long &value)
	Parse long integer value from a string. More...
String &	operator% (double &value)
	Parse double value from a string. More...
String &	operator% (const char *text)
	Parse text from a string in a scan expression. More...
String &	operator& (const char *text)
	Concatenate null terminated text to our object. More...
String &	operator&= (const char *text)
String	operator() (int offset, strsize_t size) const
	Get a new substring through object expression. More...
const char *	operator() (int offset) const
	Reference a string in the object by relative offset. More...
const char *	operator* () const
	Reference raw text buffer by pointer operator. More...
bool	operator*= (const char *substring)
bool	operator*= (regex &expr)
String &	operator*= (strsize_t number)
	Delete a specified number of characters from start of string. More...
String	operator+ (const char *text)
	Concatenate null terminated text to our object. More...
String &	operator++ (void)
	Delete first character from string.
String &	operator+= (const char *text)
	Concatenate text to an existing string object. More...
String &	operator+= (strsize_t number)
	Delete a specified number of characters from start of string. More...
String &	operator-- (void)
	Delete last character from string.
String &	operator-= (strsize_t number)
	Delete a specified number of characters from end of string. More...
bool	operator< (const char *text) const
	Compare our object with null terminated text. More...
String &	operator<< (const char *text)
String &	operator<< (char code)
bool	operator<= (const char *text) const
	Compare our object with null terminated text. More...
String &	operator= (const String &object)
	Assign our string with the cstring of another object. More...
String &	operator= (const char *text)
	Assign text to our existing buffer. More...
bool	operator== (const char *text) const
	Compare our object with null terminated text. More...
bool	operator> (const char *text) const
	Compare our object with null terminated text. More...
bool	operator>= (const char *text) const
	Compare our object with null terminated text. More...
const char	operator[] (int offset) const
	Reference a single character in string object by array offset. More...
String &	operator^= (const String &object)
	Create new cow instance and assign value from another string object. More...
String &	operator^= (const char *text)
	Create new cow instance and assign value from null terminated text. More...
String &	operator| (const char *text)
	Concatenate null terminated text to our object. More...
String &	operator|= (const char *text)
	Concatenate text to an existing string object. More...
void	paste (strsize_t offset, const char *text, strsize_t size=0)
	Insert (paste) text into string. More...
strsize_t	printf (const char *format,...)
	Print items into a string object. More...
const char *	rchr (char character) const
	Find pointer in string where specified character last appears. More...
unsigned	replace (const char *string, const char *text=((void *) 0), unsigned flags=0)
unsigned	replace (regex &expr, const char *text=((void *) 0), unsigned flags=0)
virtual bool	resize (strsize_t size)
	Resize and re-allocate string memory. More...
const char *	rfind (const char *list, strsize_t offset=npos) const
	Find last occurrence of character in the string. More...
String	right (strsize_t offset) const
	Convenience method for right of string. More...
void	rset (const char *text, char overflow, strsize_t offset, strsize_t size=0)
	Set a text field within our string object offset from the end of buffer. More...
const char *	rskip (const char *list, strsize_t offset=npos) const
	Skip trailing characters in the string. More...
void	rsplit (const char *pointer)
	Split the string by a pointer position. More...
void	rsplit (strsize_t offset)
	Split the string at a specific offset. More...
const char *	search (const char *string, unsigned instance=0, unsigned flags=0) const
	Search for a substring in the string. More...
const char *	search (regex &expr, unsigned instance=0, unsigned flags=0) const
void	set (const char *text)
	Set string object to text of a null terminated string. More...
void	set (strsize_t offset, const char *text, strsize_t size=0)
	Set a portion of the string object at a specified offset to a text string. More...
void	set (const char *text, char overflow, strsize_t offset, strsize_t size=0)
	Set a text field within our string object. More...
strsize_t	size (void) const
	Get the size of currently allocated space for string. More...
const char *	skip (const char *list, strsize_t offset=0) const
	Skip lead characters in the string. More...
void	split (const char *pointer)
	Split the string by a pointer position. More...
void	split (strsize_t offset)
	Split the string at a specific offset. More...
	String ()
	Create a new empty string object.
	String (long value)
	Create a string from a long integer. More...
	String (double value)
	Create a string from a floating point. More...
	String (strsize_t size)
	Create an empty string with a buffer pre-allocated to a specified size. More...
	String (strsize_t size, char fill)
	Create a filled string with a buffer pre-allocated to a specified size. More...
	String (strsize_t size, const char *format,...)
	Create a string by printf-like formating into a pre-allocated space of a specified size. More...
	String (const char *text)
	Create a string from null terminated text. More...
	String (const char *text, strsize_t size)
	Create a string from null terminated text up to a maximum specified size. More...
	String (const char *text, const char *end)
	Create a string for a substring. More...
	String (const String &existing)
	Construct a copy of a string object. More...
void	strip (const char *list)
	Strip lead and trailing characters from the string. More...
double	tod (char **pointer=((void *) 0))
	Convert string to a double value. More...
char *	token (char **last, const char *list, const char *quote=((void *) 0), const char *end=((void *) 0))
	A thread-safe token parsing routine for strings objects. More...
long	tol (char **pointer=((void *) 0))
	Convert string to a long value. More...
void	trim (const char *list)
	Trim lead characters from the string. More...
void	trim (strsize_t count=1)
	Trim lead characters from text. More...
bool	unquote (const char *quote)
	Unquote a quoted string. More...
void	upper (void)
	Convert string to upper case.
strsize_t	vprintf (const char *format, va_list args)
	Print items into a string object. More...
virtual	~String ()
	Destroy string. More...
Static Public Member Functions inherited from ucommon::String
static char *	add (char *buffer, size_t size, const char *text)
	Safely append a null terminated string into an existing string in memory. More...
static char *	add (char *buffer, size_t size, const char *text, size_t max)
	Safely append a null terminated string into an existing string in memory. More...
static size_t	b64decode (uint8_t *binary, const char *string, size_t size)
	Standard radix 64 decoding. More...
static size_t	b64encode (char *string, const uint8_t *binary, size_t size, size_t width=0)
	Standard radix 64 encoding. More...
static int	case_compare (const char *text1, const char *text2)
	Depreciated case insensitive string comparison function. More...
static int	case_compare (const char *text1, const char *text2, size_t size)
	Depreciated case insensitive string comparison function. More...
static unsigned	ccount (const char *text, const char *list)
	Count instances of characters in a list in a text buffer. More...
static char *	chop (char *text, const char *list)
	Strip trailing characters from the text string. More...
static int	collate (const char *text1, const char *text2)
static int	compare (const char *text1, const char *text2)
	Safe string collation function. More...
static int	compare (const char *text1, const char *text2, size_t size)
	Depreciated string comparison function. More...
static char *	copy (const char *text, size_t offset, size_t len)
static size_t	count (const char *text)
	Safe version of strlen function. More...
static uint16_t	crc16 (uint8_t *binary, size_t size)
	ccitt 16 bit crc for binary data. More...
static uint32_t	crc24 (uint8_t *binary, size_t size)
	24 bit crc as used in openpgp. More...
static void	cut (char *text, size_t offset, size_t len)
static char *	dup (const char *text)
	Duplicate null terminated text into the heap. More...
static bool	eq_case (const char *text1, const char *text2)
	Simple case insensitive equal test for strings. More...
static bool	eq_case (const char *text1, const char *text2, size_t size)
	Simple case insensitive equal test for strings. More...
static bool	equal (const char *text1, const char *text2)
	Simple equal test for strings. More...
static bool	equal (const char *text1, const char *text2, size_t size)
	Simple equal test for strings. More...
static void	erase (char *text)
	Erase string memory. More...
static char *	fill (char *text, size_t size, char character)
	Fill a section of memory with a fixed text character. More...
static const char *	find (const char *text, const char *key, const char *optional)
	Find position of substring within a string. More...
static char *	find (char *text, const char *list)
	Find the first occurrence of a character in a text buffer. More...
static void	fix (String &object)
	Fix and reset string object filler. More...
static unsigned	hexdump (const unsigned char *binary, char *string, const char *format)
	Dump hex data to a string buffer. More...
static unsigned	hexpack (unsigned char *binary, const char *string, const char *format)
	Pack hex data from a string buffer. More...
static unsigned	hexsize (const char *format)
static const char *	ifind (const char *text, const char *key, const char *optional)
	Find position of case insensitive substring within a string. More...
static char *	left (const char *text, size_t size)
	Duplicate null terminated text of specific size to heap. More...
static void	lower (char *text)
	Convert null terminated text to lower case. More...
static void	paste (char *text, size_t max, size_t offset, const char *data, size_t len=0)
static const char *	pos (const char *text, ssize_t offset)
	Compute position in string. More...
static char *	rfind (char *text, const char *list)
	Find the last occurrence of a character in a text buffer. More...
static char *	right (const char *text, size_t size)
static char *	rset (char *buffer, size_t size, const char *text)
	Set a field in a null terminated string relative to the end of text. More...
static char *	rskip (char *text, const char *list)
	Skip before trailing characters in a null terminated string. More...
static size_t	seek (char *text, const char *list)
	Offset until next occurrence of character in a text or length. More...
static char *	set (char *buffer, size_t size, const char *text)
	Safely set a null terminated string buffer in memory. More...
static char *	set (char *buffer, size_t size, const char *text, size_t max)
	Safely set a null terminated string buffer in memory. More...
static char *	skip (char *text, const char *list)
	Skip after lead characters in a null terminated string. More...
static char *	strip (char *text, const char *list)
	Skip lead and remove trailing characters from a text string. More...
static void	swap (String &object1, String &object2)
	Swap the cstring references between two strings. More...
static double	tod (const char *text, char **pointer=((void *) 0))
	Convert text to a double value. More...
static char *	token (char *text, char **last, const char *list, const char *quote=((void *) 0), const char *end=((void *) 0))
	A thread-safe token parsing routine for null terminated strings. More...
static long	tol (const char *text, char **pointer=((void *) 0))
	Convert text to a long value. More...
static char *	trim (char *text, const char *list)
	Return start of string after characters to trim from beginning. More...
static char *	unquote (char *text, const char *quote)
	Unquote a quoted null terminated string. More...
static void	upper (char *text)
	Convert null terminated text to upper case. More...
Static Public Member Functions inherited from ucommon::utf8
static unsigned	ccount (const char *string, ucs4_t character)
	Count occurrences of a unicode character in string. More...
static size_t	chars (const unicode_t string)
	How many chars requires to encode a given wchar string. More...
static size_t	chars (ucs4_t character)
	How many chars requires to encode a given unicode character. More...
static ucs4_t	codepoint (const char *encoded)
	Convert a utf8 encoded codepoint to a ucs4 character value. More...
static size_t	count (const char *string)
	Count ut8 encoded ucs4 codepoints in string. More...
static const char *	find (const char *string, ucs4_t character, size_t start=0)
	Find first occurance of character in string. More...
static ucs4_t	get (CharacterProtocol &buffer)
	Get a unicode character from a character protocol. More...
static char *	offset (char *string, ssize_t position)
	Get codepoint offset in a string. More...
static size_t	pack (unicode_t unicode, CharacterProtocol &buffer, size_t size)
	Convert a utf8 string into a unicode data buffer. More...
static ucs4_t	put (ucs4_t character, CharacterProtocol &buffer)
	Push a unicode character to a character protocol. More...
static const char *	rfind (const char *string, ucs4_t character, size_t end=(size_t)-1l)
	Find last occurrence of character in string. More...
static unsigned	size (const char *codepoint)
	Compute character size of utf8 string codepoint. More...
static ucs4_t *	udup (const char *string)
	Dup a utf8 string into a ucs4_t string.
static size_t	unpack (const unicode_t string, CharacterProtocol &buffer)
	Convert a unicode string into utf8. More...
static ucs2_t *	wdup (const char *string)
	Dup a utf8 string into a ucs2_t representation.
Static Public Attributes inherited from ucommon::String
static const strsize_t	npos
	A constant for an invalid position value.
Static Public Attributes inherited from ucommon::utf8
static const char *	nil
	A convenient NULL pointer value.
static const unsigned	ucsize
	Size of "unicode_t" character codes, may not be ucs4_t size.
Protected Attributes inherited from ucommon::String
cstring *	str
	cstring instance our object references. More...

Detailed Description

A copy-on-write utf8 string class that operates by reference count.

This is derived from the classic uCommon String class by adding operations that are utf8 encoding aware.

Author

David Sugar dyfet.nosp@m.@gnu.nosp@m.telep.nosp@m.hony.nosp@m..org

Definition at line 193 of file unicode.h.

Constructor & Destructor Documentation

ucommon::UString::UString ( strsize_t  size)

protected

Create an empty string with a buffer pre-allocated to a specified size.

Parameters

size	of buffer to allocate.

ucommon::UString::UString ( const unicode_t  text)

protected

Create a utf8 aware string for a null terminated unicode string.

Parameters

text	of ucs4 encoded data.

ucommon::UString::UString ( const char *  text, strsize_t  size  )

protected

Create a string from null terminated text up to a maximum specified size.

Parameters

text	to use for string.
size	limit of new string.

ucommon::UString::UString ( const unicode_t *  text, const unicode_t *  end  )

protected

Create a string for a substring.

The end of the substring is a pointer within the substring itself.

Parameters

text	to use for string.
end	of text in substring.

ucommon::UString::UString ( const UString &  existing)

protected

Construct a copy of a string object.

Our copy inherits the same reference counted instance of cstring as in the original.

Parameters

existing

string to copy from.

virtual ucommon::UString::~UString ( )

protectedvirtual

Destroy string.

De-reference cstring. If last reference to cstring, then also remove cstring from heap.

Member Function Documentation

void ucommon::UString::add ( const unicode_t  unicode)

protected

Add (append) unicode to a utf8 encoded string.

Parameters

unicode

text to add.

ucs4_t ucommon::UString::at ( int  position) const

protected

Return unicode character found at a specific codepoint in the string.

Parameters

position

of codepoint in string, negative values computed from end.

Returns

character code at specified position in string.

unsigned ucommon::UString::ccount ( ucs4_t  character) const

protected

Count occurrences of a unicode character in string.

Parameters

character

code to search for.

Returns

count of occurrences.

UString ucommon::UString::copy ( strsize_t  offset, strsize_t  size  ) const

inlineprotected

Convenience method for substring extraction.

Parameters

offset	into string.
size	of string to return.

Returns

string object holding substring.

Definition at line 316 of file unicode.h.

Here is the call graph for this function:

strsize_t ucommon::UString::count ( void  ) const

inlineprotected

Count codepoints in current string.

Returns

count of codepoints.

Definition at line 355 of file unicode.h.

Here is the call graph for this function:

void ucommon::UString::cut ( strsize_t  offset, strsize_t  size = 0  )

protected

Cut (remove) text from string using codepoint offsets.

Parameters

offset	to start of text field to remove.
size	of text field to remove or 0 to remove to end of string.

const char* ucommon::UString::find ( ucs4_t  character, strsize_t  start = 0  ) const

protected

Find first occurrence of character in string.

Parameters

character	code to search for.
start	offset in string in codepoints.

Returns

pointer to first instance or NULL if not found.

UString ucommon::UString::get ( strsize_t  codepoint, strsize_t  size = 0  ) const

protected

Get a new string object as a substring of the current object.

Parameters

codepoint	offset of substring.
size	of substring in codepoints or 0 if to end.

Returns

string object holding substring.

size_t ucommon::UString::get ( unicode_t  unicode, size_t  size  ) const

protected

Extract a unicode byte sequence from utf8 object.

Parameters

unicode	data buffer.
size	of data buffer.

Returns

codepoints copied.

UString ucommon::UString::left ( strsize_t  size) const

inlineprotected

Convenience method for left of string.

Parameters

size	of substring to gather in codepoints.

Returns

string object holding substring.

Definition at line 299 of file unicode.h.

Here is the call graph for this function:

size_t ucommon::UString::operator() ( unicode_t  unicode, size_t  size  ) const

inlineprotected

Extract a unicode byte sequence from utf8 object.

Parameters

unicode	data buffer.
size	of data buffer.

Returns

codepoints copied.

Definition at line 283 of file unicode.h.

Here is the call graph for this function:

UString ucommon::UString::operator() ( int  codepoint, strsize_t  size  ) const

protected

Get a new substring through object expression.

Parameters

codepoint	offset of substring.
size	of substring or 0 if to end.

Returns

string object holding substring.

const char* ucommon::UString::operator() ( int  offset) const

protected

Reference a string in the object by codepoint offset.

Positive offsets are from the start of the string, negative from the end.

Parameters

offset

to string position.

Returns

pointer to string data or NULL if invalid offset.

ucs4_t ucommon::UString::operator[] ( int  position) const

inlineprotected

Reference a unicode character in string object by array offset.

Parameters

position

of codepoint offset to character.

Returns

character value at offset.

Definition at line 348 of file unicode.h.

Here is the call graph for this function:

void ucommon::UString::paste ( strsize_t  offset, const char *  text, strsize_t  size = 0  )

protected

Insert (paste) text into string using codepoint offsets.

Parameters

offset	to start paste.
text	to paste.
size	of text to paste.

const char* ucommon::UString::rfind ( ucs4_t  character, strsize_t  end = npos  ) const

protected

Find last occurrence of character in string.

Parameters

character	code to search for.
end	offset to start from in codepoints.

Returns

pointer to last instance or NULL if not found.

UString ucommon::UString::right ( strsize_t  offset) const

inlineprotected

Convenience method for right of string.

Parameters

offset

of substring from right in codepoints.

Returns

string object holding substring.

Definition at line 307 of file unicode.h.

Here is the call graph for this function:

void ucommon::UString::set ( const unicode_t  unicode)

protected

Set a utf8 encoded string based on unicode data.

Parameters

unicode

text to set.

---

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

• ucommon/unicode.h