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 (unicode_t unicode)
	Add (append) unicode to a utf8 encoded string.
ucs4_t	at (int position)
	Return unicode character found at a specific codepoint in the string.
unsigned	ccount (ucs4_t character)
	Count occurrences of a unicode character in string.
strsize_t	count (void)
	Count codepoints in current string.
char *	find (ucs4_t character, strsize_t start=0)
	Find first occurrence of character in string.
UString	get (strsize_t codepoint, strsize_t size=0)
	Get a new string object as a substring of the current object.
size_t	get (unicode_t unicode, size_t size)
	Extract a unicode byte sequence from utf8 object.
size_t	operator() (unicode_t unicode, size_t size)
	Extract a unicode byte sequence from utf8 object.
UString	operator() (int codepoint, strsize_t size)
	Get a new substring through object expression.
char *	operator() (int offset)
	Reference a string in the object by codepoint offset.
ucs4_t	operator[] (int position)
	Reference a unicode character in string object by array offset.
char *	rfind (ucs4_t character, strsize_t end=npos)
	Find last occurrence of character in string.
void	set (unicode_t unicode)
	Set a utf8 encoded string based on unicode data.
	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.
	UString (unicode_t text)
	Create a utf8 aware string for a null terminated unicode string.
	UString (char *text, strsize_t size)
	Create a string from null terminated text up to a maximum specified size.
	UString (unicode_t *text, unicode_t *end)
	Create a string for a substring.
	UString (UString &existing)
	Construct a copy of a string object.
virtual	~UString ()
	Destroy string.
Protected Member Functions inherited from ucommon::string
virtual cstring *	c_copy (void)
	Return cstring to use in copy constructors.
int	collate (char *string)
virtual int	compare (char *string)
	Compare the values of two string.
virtual void	cow (strsize_t size=0)
	Copy on write operation for cstring.
cstring *	create (strsize_t size, char fill=0)
	Factory create a cstring object of specified size.
bool	equal (char *string)
	Test if two string values are equal.
strsize_t	getStringSize (void)
virtual void	release (void)
	Decrease retention of our reference counted cstring.
virtual void	retain (void)
	Increase retention of our reference counted cstring.

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

---

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 ( unicode_t  text )

protected

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

Parameters:

text	of ucs4 encoded data.

ucommon::UString::UString ( 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 ( unicode_t *  text, 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 ( 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 ( unicode_t  unicode )

protected

Add (append) unicode to a utf8 encoded string.

Parameters:

unicode

text to add.

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

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.

Reimplemented from ucommon::string.

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

protected

Count occurrences of a unicode character in string.

Parameters:

character

code to search for.

Returns:

count of occurrences.

strsize_t ucommon::UString::count ( void  )

inlineprotected

Count codepoints in current string.

Returns:

count of codepoints.

Reimplemented from ucommon::string.

Definition at line 315 of file unicode.h.

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

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  )

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.

Reimplemented from ucommon::string.

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

protected

Extract a unicode byte sequence from utf8 object.

Parameters:

unicode	data buffer.
size	of data buffer.

Returns:

codepoints copied.

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

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  )

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.

Reimplemented from ucommon::string.

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

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.

Reimplemented from ucommon::string.

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

inlineprotected

Reference a unicode character in string object by array offset.

Parameters:

position

of codepoint offset to character.

Returns:

character value at offset.

Reimplemented from ucommon::string.

Definition at line 308 of file unicode.h.

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

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.

void ucommon::UString::set ( 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