C++ bindings for cgul_hstring More...

#include <cgul_hstring_cxx.h>

Collaboration diagram for cgul_hstring_cxx:

Public Member Functions
	cgul_hstring_cxx ()

	cgul_hstring_cxx (const cgul_hstring_cxx &rhs)

	cgul_hstring_cxx (const cgul_hchar_t *rhs)

virtual	~cgul_hstring_cxx ()

virtual cgul_hstring_cxx &	operator= (const cgul_hstring_cxx &rhs)

virtual cgul_hstring_cxx &	operator= (const cgul_hchar_t *rhs)

virtual cgul_hstring_cxx &	operator+= (const cgul_hstring_cxx &rhs)

virtual cgul_hstring_cxx &	operator+= (const cgul_hchar_t *rhs)

virtual cgul_hchar_t &	operator[] (size_t index)

virtual const cgul_hchar_t &	operator[] (size_t index) const

virtual	operator cgul_hchar_t * () const

virtual cgul_hchar_t *	get_value () const

virtual cgul_hchar_t *	take_value ()

virtual cgul_hchar_t	get_value_at (size_t index) const

virtual void	set_value (const cgul_hchar_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_hchar_t *value)

virtual void	append_block (const void *block, size_t block_size)

virtual void	append_char (cgul_hchar_t c)

virtual void	insert (size_t index, const cgul_hchar_t *value, size_t value_length)

virtual void	insert_char (size_t index, cgul_hchar_t value)

virtual void	pad_right (size_t width, cgul_hchar_t pad)

virtual void	pad_left (size_t width, cgul_hchar_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_hstring_cxx &rhs)

virtual void	swap (cgul_hstring_cxx &rhs)

virtual cgul_hstring_t	get_obj () const

virtual cgul_hstring_t	take_obj ()

virtual void	set_obj (cgul_hstring_t rhs)

Detailed Description

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

Constructor & Destructor Documentation

§ cgul_hstring_cxx() [1/3]

cgul_hstring_cxx::cgul_hstring_cxx ( )

inline

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

References cgul_hstring__new().

§ cgul_hstring_cxx() [2/3]

cgul_hstring_cxx::cgul_hstring_cxx ( const cgul_hstring_cxx & rhs )

inline

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

Parameters

[in] rhs right-hand side

References cgul_hstring__new_from_hcstring(), and get_value().

§ cgul_hstring_cxx() [3/3]

cgul_hstring_cxx::cgul_hstring_cxx ( const cgul_hchar_t * rhs )

inline

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

Parameters

[in] rhs right-hand side

References cgul_hstring__new_from_hcstring().

§ ~cgul_hstring_cxx()

virtual cgul_hstring_cxx::~cgul_hstring_cxx ( )

inlinevirtual

Destructor.

References cgul_hstring__delete().

Member Function Documentation

§ operator=() [1/2]

virtual cgul_hstring_cxx& cgul_hstring_cxx::operator= ( const cgul_hstring_cxx & rhs )

inlinevirtual

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

Parameters

[in] rhs right-hand side

Returns: *this

References cgul_hstring__set_value(), and get_value().

§ operator=() [2/2]

virtual cgul_hstring_cxx& cgul_hstring_cxx::operator= ( const cgul_hchar_t * rhs )

inlinevirtual

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

Parameters

[in] rhs right-hand side

Returns: *this

References cgul_hstring__set_value().

§ operator+=() [1/2]

virtual cgul_hstring_cxx& cgul_hstring_cxx::operator+= ( const cgul_hstring_cxx & rhs )

inlinevirtual

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

Parameters

[in] rhs right-hand side

Returns: *this

References cgul_hstring__append(), and get_value().

§ operator+=() [2/2]

virtual cgul_hstring_cxx& cgul_hstring_cxx::operator+= ( const cgul_hchar_t * rhs )

inlinevirtual

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

Parameters

[in] rhs right-hand side

Returns: *this

References cgul_hchar_t, and cgul_hstring__append().

§ operator[]() [1/2]

virtual cgul_hchar_t& cgul_hstring_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_hchar_t, cgul_hstring__get_length(), and cgul_hstring__get_value().

§ operator[]() [2/2]

virtual const cgul_hchar_t& cgul_hstring_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_hchar_t, cgul_hstring__get_length(), and cgul_hstring__get_value().

§ operator cgul_hchar_t *()

virtual cgul_hstring_cxx::operator cgul_hchar_t * ( ) const

inlinevirtual

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

Returns: underlying c-style string

References cgul_hchar_t, and get_value().

§ get_value()

virtual cgul_hchar_t* cgul_hstring_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_hchar_t, and cgul_hstring__get_value().

Referenced by cgul_hstring_cxx(), operator cgul_hchar_t *(), operator+=(), and operator=().

§ take_value()

virtual cgul_hchar_t* cgul_hstring_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_hstring that you then pass to cgul_hash or cgul_rbtree. Compare this function with get_value().

Returns: underlying c-style string

References cgul_hchar_t, and cgul_hstring__take_value().

§ get_value_at()

virtual cgul_hchar_t cgul_hstring_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] index index into the string

Returns: character at index

References cgul_hchar_t, and cgul_hstring__get_value_at().

§ set_value()

virtual void cgul_hstring_cxx::set_value ( const cgul_hchar_t * value )

inlinevirtual

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

Parameters

[in] value new value

References cgul_hstring__set_value().

§ clear()

virtual void cgul_hstring_cxx::clear ( )

inlinevirtual

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

References cgul_hstring__clear().

§ to_schar()

virtual signed char cgul_hstring_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] base base to use for the conversion

Returns: converted value

See also: get_value_at()

References cgul_hstring__to_schar().

§ to_uchar()

virtual unsigned char cgul_hstring_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] base base to use for the conversion

Returns: converted value

See also: get_value_at()

References cgul_hstring__to_uchar().

§ to_short()

virtual short int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_short().

§ to_ushort()

virtual unsigned short int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_ushort().

§ to_int()

virtual int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_int().

§ to_unsigned()

virtual unsigned int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_unsigned().

§ to_long()

virtual long int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_long().

§ to_unsigned_long()

virtual unsigned long int cgul_hstring_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] base base to use for the conversion

Returns: converted value

References cgul_hstring__to_unsigned_long().

§ to_double()

virtual double cgul_hstring_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_hstring__to_double().

§ append()

virtual void cgul_hstring_cxx::append ( const cgul_hchar_t * value )

inlinevirtual

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

Parameters

[in] value value to append

References cgul_hstring__append().

§ append_block()

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

inlinevirtual

Append a block of non-CGUL_HCHAR__NUL characters 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]	block	block to append
[in]	block_size	size of block to append

References cgul_hstring__append_block().

§ append_char()

virtual void cgul_hstring_cxx::append_char ( cgul_hchar_t c )

inlinevirtual

Append c to the string.

Parameters

[in] c wide character to append

References cgul_hstring__append_char().

§ insert()

virtual void cgul_hstring_cxx::insert	(	size_t	index,
		const cgul_hchar_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]	index	index where `value` is inserted
[in]	value	value to insert
[in]	value_length	length of value

References cgul_hstring__insert().

§ insert_char()

virtual void cgul_hstring_cxx::insert_char	(	size_t	index,
		cgul_hchar_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]	index	index where `value` is inserted
[in]	value	value to insert

References cgul_hstring__insert_char().

§ pad_right()

virtual void cgul_hstring_cxx::pad_right	(	size_t	width,
		cgul_hchar_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]	width	padding width
[in]	pad	character to use for padding

References cgul_hstring__pad_right().

§ pad_left()

virtual void cgul_hstring_cxx::pad_left	(	size_t	width,
		cgul_hchar_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]	width	padding width
[in]	pad	character to use for padding

References cgul_hstring__pad_left().

§ trim()

virtual void cgul_hstring_cxx::trim ( )

inlinevirtual

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

References cgul_hstring__trim().

§ trim_left()

virtual void cgul_hstring_cxx::trim_left ( )

inlinevirtual

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

References cgul_hstring__trim_left().

§ trim_right()

virtual void cgul_hstring_cxx::trim_right ( )

inlinevirtual

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

References cgul_hstring__trim_right().

§ reverse()

virtual void cgul_hstring_cxx::reverse ( )

inlinevirtual

Reverse the order of the characters in the string.

References cgul_hstring__reverse().

§ get_length()

virtual size_t cgul_hstring_cxx::get_length ( ) const

inlinevirtual

This method returns the length of the string.

Returns: length of the string

References cgul_hstring__get_length().

§ set_length()

virtual size_t cgul_hstring_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] length new, shorter length of the string

Returns: previous length of the string

References cgul_hstring__set_length().

§ externally_adjusted()

virtual void cgul_hstring_cxx::externally_adjusted ( )

inlinevirtual

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

See also: get_value

References cgul_hstring__externally_adjusted().

§ trim_capacity()

virtual void cgul_hstring_cxx::trim_capacity ( )

inlinevirtual

Trim the string by returning excess capacity to the heap.

References cgul_hstring__trim_capacity().

§ get_minimum_capacity()

virtual size_t cgul_hstring_cxx::get_minimum_capacity ( ) const

inlinevirtual

Get the minimum capacity.

Returns: minimum capacity

References cgul_hstring__get_minimum_capacity().

§ set_minimum_capacity()

virtual void cgul_hstring_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_capacity minimum capacity

References cgul_hstring__set_minimum_capacity().

§ compare()

virtual int cgul_hstring_cxx::compare ( const cgul_hstring_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_hstring_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_hchar_cxx::hcscmp() instead if inserting raw cgul_hchar strings as keys into a cgul_rbtree_cxx object.

Parameters

[in] rhs right-hand side

Returns: -1, 0, or 1 if *this is less than, equal to, or greater than rhs respectively

See also: cgul_hchar_cxx::hcscmp()

References cgul_hstring__compare().

§ swap()

virtual void cgul_hstring_cxx::swap ( cgul_hstring_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] rhs right-hand side

References cgul_hstring__swap().

§ get_obj()

virtual cgul_hstring_t cgul_hstring_cxx::get_obj ( ) const

inlinevirtual

Get the underlying cgul_hstring object.

Returns: underlying object

Referenced by cgul_unicode_cxx::mbstohcs(), and cgul_unicode_cxx::wcstohcs().

§ take_obj()

virtual cgul_hstring_t cgul_hstring_cxx::take_obj ( )

inlinevirtual

Take the underlying cgul_hstring 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_hstring__delete().

Returns: underlying object

§ set_obj()

virtual void cgul_hstring_cxx::set_obj ( cgul_hstring_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] rhs right-hand side

References cgul_hstring__delete().

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

cgul_hstring_cxx.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ cgul_hstring_cxx() [1/3]

§ cgul_hstring_cxx() [2/3]

§ cgul_hstring_cxx() [3/3]

§ ~cgul_hstring_cxx()

Member Function Documentation

§ operator=() [1/2]

§ operator=() [2/2]

§ operator+=() [1/2]

§ operator+=() [2/2]

§ operator[]() [1/2]

§ operator[]() [2/2]

§ operator cgul_hchar_t *()

§ get_value()

§ take_value()

§ get_value_at()

§ set_value()

§ clear()

§ to_schar()

§ to_uchar()

§ to_short()

§ to_ushort()

§ to_int()

§ to_unsigned()

§ to_long()

§ to_unsigned_long()

§ to_double()

§ append()

§ append_block()

§ append_char()

§ insert()

§ insert_char()

§ pad_right()

§ pad_left()

§ trim()

§ trim_left()

§ trim_right()

§ reverse()

§ get_length()

§ set_length()

§ externally_adjusted()

§ trim_capacity()

§ get_minimum_capacity()

§ set_minimum_capacity()

§ compare()

§ swap()

§ get_obj()

§ take_obj()

§ set_obj()