cgul_wstring_cxx Class Reference

C++ bindings for cgul_wstring More...

#include <cgul_wstring_cxx.h>

Collaboration diagram for cgul_wstring_cxx:
Collaboration graph

Public Member Functions

 cgul_wstring_cxx ()
 
 cgul_wstring_cxx (const cgul_wstring_cxx &rhs)
 
 cgul_wstring_cxx (const cgul_wchar_t *rhs)
 
virtual ~cgul_wstring_cxx ()
 
virtual cgul_wstring_cxxoperator= (const cgul_wstring_cxx &rhs)
 
virtual cgul_wstring_cxxoperator= (const cgul_wchar_t *rhs)
 
virtual cgul_wstring_cxxoperator+= (const cgul_wstring_cxx &rhs)
 
virtual cgul_wstring_cxxoperator+= (const cgul_wchar_t *rhs)
 
virtual cgul_wchar_toperator[] (size_t index)
 
virtual const cgul_wchar_toperator[] (size_t index) const
 
virtual operator cgul_wchar_t * () const
 
virtual cgul_wchar_tget_value () const
 
virtual cgul_wchar_ttake_value ()
 
virtual cgul_wchar_t get_value_at (size_t index) const
 
virtual void set_value (const cgul_wchar_t *value)
 
virtual void clear ()
 
virtual signed char to_schar (int base=0)
 
virtual unsigned char to_uchar (int base=0)
 
virtual short int to_short (int base=0)
 
virtual unsigned short int to_ushort (int base=0)
 
virtual int to_int (int base=0)
 
virtual unsigned int to_unsigned (int base=0)
 
virtual long int to_long (int base=0)
 
virtual unsigned long int to_unsigned_long (int base=0)
 
virtual double to_double ()
 
virtual void append (const cgul_wchar_t *value)
 
virtual void append_block (const void *block, size_t block_size)
 
virtual void append_char (cgul_wchar_t c)
 
virtual void insert (size_t index, const cgul_wchar_t *value, size_t value_length)
 
virtual void insert_char (size_t index, cgul_wchar_t value)
 
virtual void pad_right (size_t width, cgul_wchar_t pad)
 
virtual void pad_left (size_t width, cgul_wchar_t pad)
 
virtual void trim ()
 
virtual void trim_left ()
 
virtual void trim_right ()
 
virtual void reverse ()
 
virtual size_t get_length () const
 
virtual size_t set_length (size_t length)
 
virtual void externally_adjusted ()
 
virtual void trim_capacity ()
 
virtual size_t get_minimum_capacity () const
 
virtual void set_minimum_capacity (size_t minimum_capacity)
 
virtual int compare (const cgul_wstring_cxx &rhs)
 
virtual void swap (cgul_wstring_cxx &rhs)
 
virtual cgul_wstring_t get_obj () const
 
virtual cgul_wstring_t take_obj ()
 
virtual void set_obj (cgul_wstring_t rhs)
 

Detailed Description

This class provides the C++ bindings for C cgul_wstring objects. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_wstring into C++-style function calls and exception handling.

Constructor & Destructor Documentation

§ cgul_wstring_cxx() [1/3]

cgul_wstring_cxx::cgul_wstring_cxx ( )
inline

Default constructor that creates a new instance with an empty string.

References cgul_wstring__new().

§ cgul_wstring_cxx() [2/3]

cgul_wstring_cxx::cgul_wstring_cxx ( const cgul_wstring_cxx rhs)
inline

Copy constructor that creates a new instance by copying the value from rhs.

Parameters
[in]rhsright-hand side

References cgul_wstring__new_from_wcstring(), and get_value().

§ cgul_wstring_cxx() [3/3]

cgul_wstring_cxx::cgul_wstring_cxx ( const cgul_wchar_t rhs)
inline

Copy constructor that creates a new instance by copying the value from rhs.

Parameters
[in]rhsright-hand side

References cgul_wstring__new_from_wcstring().

§ ~cgul_wstring_cxx()

virtual cgul_wstring_cxx::~cgul_wstring_cxx ( )
inlinevirtual

Destructor.

References cgul_wstring__delete().

Member Function Documentation

§ operator=() [1/2]

virtual cgul_wstring_cxx& cgul_wstring_cxx::operator= ( const cgul_wstring_cxx rhs)
inlinevirtual

Assign the value from rhs to this object and return this object.

Parameters
[in]rhsright-hand side
Returns
*this

References cgul_wstring__set_value(), and get_value().

§ operator=() [2/2]

virtual cgul_wstring_cxx& cgul_wstring_cxx::operator= ( const cgul_wchar_t rhs)
inlinevirtual

Assign the value from rhs to this object and return this object.

Parameters
[in]rhsright-hand side
Returns
*this

References cgul_wstring__set_value().

§ operator+=() [1/2]

virtual cgul_wstring_cxx& cgul_wstring_cxx::operator+= ( const cgul_wstring_cxx rhs)
inlinevirtual

Append the value from rhs to this object and return this object.

Parameters
[in]rhsright-hand side
Returns
*this

References cgul_wstring__append(), and get_value().

§ operator+=() [2/2]

virtual cgul_wstring_cxx& cgul_wstring_cxx::operator+= ( const cgul_wchar_t rhs)
inlinevirtual

Append the value from rhs to this object and return this object.

Parameters
[in]rhsright-hand side
Returns
*this

References cgul_wchar_t, and cgul_wstring__append().

§ operator[]() [1/2]

virtual cgul_wchar_t& cgul_wstring_cxx::operator[] ( size_t  index)
inlinevirtual

Index operator that returns the wide character at index. If index is out of bounds, an exception is thrown.

References cgul_exception__new(), cgul_wchar_t, cgul_wstring__get_length(), and cgul_wstring__get_value().

§ operator[]() [2/2]

virtual const cgul_wchar_t& cgul_wstring_cxx::operator[] ( size_t  index) const
inlinevirtual

Index operator that returns the wide character at index. If index is out of bounds, an exception is thrown. This is the overloaded operator[]() that is necessary for use with const objects.

References cgul_exception__new(), cgul_wchar_t, cgul_wstring__get_length(), and cgul_wstring__get_value().

§ operator cgul_wchar_t *()

virtual cgul_wstring_cxx::operator cgul_wchar_t * ( ) const
inlinevirtual

This method allows instances of this class to be cast to C-style strings.

Returns
underlying c-style string

References cgul_wchar_t, and get_value().

§ get_value()

virtual cgul_wchar_t* cgul_wstring_cxx::get_value ( ) const
inlinevirtual

This method returns a pointer to the internal C-style string. You are allowed to manually set individual characters in the string. Just remember to call externally_adjusted() afterward. Compare this method to the take_value() method.

Returns
underlying c-style string

References cgul_wchar_t, and cgul_wstring__get_value().

Referenced by cgul_wstring_cxx(), operator cgul_wchar_t *(), operator+=(), and operator=().

§ take_value()

virtual cgul_wchar_t* cgul_wstring_cxx::take_value ( )
inlinevirtual

This method lets you take ownership of the underlying C-style string which is returned. Immediately upon taking ownership, the internal state of this class is reset including resetting a new underlying C-style string to be empty. One use of this function is to build up a string using cgul_wstring that you then pass to cgul_hash or cgul_rbtree. Compare this function with get_value().

Returns
underlying c-style string

References cgul_wchar_t, and cgul_wstring__take_value().

§ get_value_at()

virtual cgul_wchar_t cgul_wstring_cxx::get_value_at ( size_t  index) const
inlinevirtual

This method returns the character indicated by index where index is zero-based. If index is out of bounds, an exception is thrown.

Parameters
[in]indexindex into the string
Returns
character at index

References cgul_wchar_t, and cgul_wstring__get_value_at().

§ set_value()

virtual void cgul_wstring_cxx::set_value ( const cgul_wchar_t value)
inlinevirtual

Set the value of the underlying c-style string to value. If an error occurs, an exception is thrown.

Parameters
[in]valuenew value

References cgul_wstring__set_value().

§ clear()

virtual void cgul_wstring_cxx::clear ( )
inlinevirtual

This method is equivalent to calling set_value() where value is an empty string.

References cgul_wstring__clear().

§ to_schar()

virtual signed char cgul_wstring_cxx::to_schar ( int  base = 0)
inlinevirtual

This method converts the string to a signed char. Typically, "base" will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading character in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value
See also
get_value_at()

References cgul_wstring__to_schar().

§ to_uchar()

virtual unsigned char cgul_wstring_cxx::to_uchar ( int  base = 0)
inlinevirtual

This method converts the string to an unsigned char. Typically, base will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading characters in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value
See also
get_value_at()

References cgul_wstring__to_uchar().

§ to_short()

virtual short int cgul_wstring_cxx::to_short ( int  base = 0)
inlinevirtual

This method converts the string to a short. Typically, "base" will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading character in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_short().

§ to_ushort()

virtual unsigned short int cgul_wstring_cxx::to_ushort ( int  base = 0)
inlinevirtual

This method converts the string to an unsigned short. Typically, base will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading characters in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_ushort().

§ to_int()

virtual int cgul_wstring_cxx::to_int ( int  base = 0)
inlinevirtual

This method converts the string to an int. Typically, "base" will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading character in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_int().

§ to_unsigned()

virtual unsigned int cgul_wstring_cxx::to_unsigned ( int  base = 0)
inlinevirtual

This method converts the string to an unsigned. Typically, base will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading characters in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_unsigned().

§ to_long()

virtual long int cgul_wstring_cxx::to_long ( int  base = 0)
inlinevirtual

This method converts the string to a long. Typically, base will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading characters in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_long().

§ to_unsigned_long()

virtual unsigned long int cgul_wstring_cxx::to_unsigned_long ( int  base = 0)
inlinevirtual

This method converts the string to an unsigned long. Typically, base will be set to 0 to allow conversion for decimal, hexadecimal, and octal based on the leading characters in the string. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0 is returned and an exception is thrown.

Parameters
[in]basebase to use for the conversion
Returns
converted value

References cgul_wstring__to_unsigned_long().

§ to_double()

virtual double cgul_wstring_cxx::to_double ( )
inlinevirtual

This method converts the string to a double. The string cannot have any extraneous characters. If it does, the conversion will fail. On success, the converted value is returned; otherwise, 0.0 is returned and an exception is thrown.

Returns
converted value

References cgul_wstring__to_double().

§ append()

virtual void cgul_wstring_cxx::append ( const cgul_wchar_t value)
inlinevirtual

Appends value to the string. If an error occurs, an exception is thrown.

Parameters
[in]valuevalue to append

References cgul_wstring__append().

§ append_block()

virtual void cgul_wstring_cxx::append_block ( const void *  block,
size_t  block_size 
)
inlinevirtual

Append a block of non-CGUL_WCHAR__NUL characters. The caller should verify that there are no embedded NUL characters in the string. If an error occurs, an exception is thrown.

Parameters
[in]blockblock to append
[in]block_sizesize of block to append

References cgul_wstring__append_block().

§ append_char()

virtual void cgul_wstring_cxx::append_char ( cgul_wchar_t  c)
inlinevirtual

Append c to the string.

Parameters
[in]cwide character to append

References cgul_wstring__append_char().

§ insert()

virtual void cgul_wstring_cxx::insert ( size_t  index,
const cgul_wchar_t value,
size_t  value_length 
)
inlinevirtual

Inserts value at index which can range from 0 to the length (inclusive) of this string. If index is out of bounds or if memory cannot be allocated, an exception is thrown.

Parameters
[in]indexindex where value is inserted
[in]valuevalue to insert
[in]value_lengthlength of value

References cgul_wstring__insert().

§ insert_char()

virtual void cgul_wstring_cxx::insert_char ( size_t  index,
cgul_wchar_t  value 
)
inlinevirtual

Inserts value at index which can range from 0 to the length (inclusive) of this string. If index is out of bounds or if memory cannot be allocated, an exception is thrown.

Parameters
[in]indexindex where value is inserted
[in]valuevalue to insert

References cgul_wstring__insert_char().

§ pad_right()

virtual void cgul_wstring_cxx::pad_right ( size_t  width,
cgul_wchar_t  pad 
)
inlinevirtual

Pad the current string such that it is at least width characters wide using the pad character. The string will be right aligned.

Parameters
[in]widthpadding width
[in]padcharacter to use for padding

References cgul_wstring__pad_right().

§ pad_left()

virtual void cgul_wstring_cxx::pad_left ( size_t  width,
cgul_wchar_t  pad 
)
inlinevirtual

Pad the current string such that it is at least width characters wide using the pad character. The string will be left aligned.

Parameters
[in]widthpadding width
[in]padcharacter to use for padding

References cgul_wstring__pad_left().

§ trim()

virtual void cgul_wstring_cxx::trim ( )
inlinevirtual

Trim the string by removing leading and trailing white-space where white-space is definded by cgul_wchar::isspace().

References cgul_wstring__trim().

§ trim_left()

virtual void cgul_wstring_cxx::trim_left ( )
inlinevirtual

Trim the string by removing leading white-space where white-space is definded by cgul_wchar::isspace().

References cgul_wstring__trim_left().

§ trim_right()

virtual void cgul_wstring_cxx::trim_right ( )
inlinevirtual

Trim the string by removing trailing white-space where white-space is definded by cgul_wchar::isspace().

References cgul_wstring__trim_right().

§ reverse()

virtual void cgul_wstring_cxx::reverse ( )
inlinevirtual

Reverse the order of the characters in the string.

References cgul_wstring__reverse().

§ get_length()

virtual size_t cgul_wstring_cxx::get_length ( ) const
inlinevirtual

This method returns the length of the string.

Returns
length of the string

References cgul_wstring__get_length().

§ set_length()

virtual size_t cgul_wstring_cxx::set_length ( size_t  length)
inlinevirtual

This method can be used to set the length of the string. It can only be used to make the string shorter. If it is used in an attempt to make the string longer, an exception is thrown. If the length of the string is successfully changed, the previous length of the string is returned.

Parameters
[in]lengthnew, shorter length of the string
Returns
previous length of the string

References cgul_wstring__set_length().

§ externally_adjusted()

virtual void cgul_wstring_cxx::externally_adjusted ( )
inlinevirtual

If you manually alter the underlying buffer by modifying the cgul_wchar_t* string returned by get_value(), you'll need to manually have the class reset its internal state.

See also
get_value

References cgul_wstring__externally_adjusted().

§ trim_capacity()

virtual void cgul_wstring_cxx::trim_capacity ( )
inlinevirtual

Trim the string by returning excess capacity to the heap.

References cgul_wstring__trim_capacity().

§ get_minimum_capacity()

virtual size_t cgul_wstring_cxx::get_minimum_capacity ( ) const
inlinevirtual

Get the minimum capacity.

Returns
minimum capacity

References cgul_wstring__get_minimum_capacity().

§ set_minimum_capacity()

virtual void cgul_wstring_cxx::set_minimum_capacity ( size_t  minimum_capacity)
inlinevirtual

Set the minimum capacity. The default value is 128 which means there is always capacity for 127 characters plus one NUL-terminator. Decreasing the capacity will decrease the amount of space used and (typically) also decrease performance. If an error occurs, an exception is thrown.

Parameters
[in]minimum_capacityminimum capacity

References cgul_wstring__set_minimum_capacity().

§ compare()

virtual int cgul_wstring_cxx::compare ( const cgul_wstring_cxx rhs)
inlinevirtual

Perform a case-significant wide-character string comparison of *this and rhs. Return -1, 0, or 1 if *this is less than, equal to, or greater than rhs respectively.

For simplicity, this function compares strings stricly by the ordinal value of each character which should be sufficient, for example, when inserting entire cgul_wstring_cxx objects as keys into a cgul_rbtree_cxx object; however, the comparison results are not likely to be the same as what strcoll() would return if used on the UTF-8 version of the strings.

Note
Use cgul_wchar_cxx::wcscmp() instead if inserting raw cgul_wchar strings as keys into a cgul_rbtree_cxx object.
Parameters
[in]rhsright-hand side
Returns
-1, 0, or 1 if *this is less than, equal to, or greater than rhs respectively
See also
cgul_wchar_cxx::wcscmp()

References cgul_wstring__compare().

§ swap()

virtual void cgul_wstring_cxx::swap ( cgul_wstring_cxx rhs)
inlinevirtual

Swap the underlying data for this object and rhs. For large strings, this should be much faster than trying to do the same thing using set_value().

Parameters
[in]rhsright-hand side

References cgul_wstring__swap().

§ get_obj()

virtual cgul_wstring_t cgul_wstring_cxx::get_obj ( ) const
inlinevirtual

§ take_obj()

virtual cgul_wstring_t cgul_wstring_cxx::take_obj ( )
inlinevirtual

Take the underlying cgul_wstring object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling cgul_wstring__delete().

Returns
underlying object

§ set_obj()

virtual void cgul_wstring_cxx::set_obj ( cgul_wstring_t  rhs)
inlinevirtual

Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object.

This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.

Parameters
[in]rhsright-hand side

References cgul_wstring__delete().


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