cgul_hstring.h File Reference

16-bit wide-character string class More...

#include "cgul_common.h"
#include "cgul_exception.h"
#include "cgul_hchar.h"

Include dependency graph for cgul_hstring.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_hstring *	cgul_hstring_t

Functions
CGUL_EXPORT cgul_hstring_t	cgul_hstring__new (cgul_exception_t *cex)
CGUL_EXPORT cgul_hstring_t	cgul_hstring__new_from_hcstring (cgul_exception_t *cex, const cgul_hchar_t *value)
CGUL_EXPORT void	cgul_hstring__delete (cgul_hstring_t hs)
CGUL_EXPORT cgul_hchar_t *	cgul_hstring__get_value (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT cgul_hchar_t *	cgul_hstring__take_value (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__set_value (cgul_exception_t *cex, cgul_hstring_t hs, const cgul_hchar_t *value)
CGUL_EXPORT cgul_hchar_t	cgul_hstring__get_value_at (cgul_exception_t *cex, cgul_hstring_t hs, size_t index)
CGUL_EXPORT void	cgul_hstring__set_value_at (cgul_exception_t *cex, cgul_hstring_t hs, size_t index, cgul_hchar_t hc)
CGUL_EXPORT void	cgul_hstring__clear (cgul_hstring_t hs)
CGUL_EXPORT signed char	cgul_hstring__to_schar (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT unsigned char	cgul_hstring__to_uchar (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT short int	cgul_hstring__to_short (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT unsigned short int	cgul_hstring__to_ushort (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT int	cgul_hstring__to_int (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT unsigned int	cgul_hstring__to_unsigned (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT long int	cgul_hstring__to_long (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT unsigned long int	cgul_hstring__to_unsigned_long (cgul_exception_t *cex, cgul_hstring_t hs, int base)
CGUL_EXPORT double	cgul_hstring__to_double (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__append (cgul_exception_t *cex, cgul_hstring_t hs, const cgul_hchar_t *value)
CGUL_EXPORT void	cgul_hstring__append_block (cgul_exception_t *cex, cgul_hstring_t hs, const void *block, size_t block_size)
CGUL_EXPORT void	cgul_hstring__append_char (cgul_exception_t *cex, cgul_hstring_t hs, cgul_hchar_t hc)
CGUL_EXPORT void	cgul_hstring__insert (cgul_exception_t *cex, cgul_hstring_t hs, size_t index, const cgul_hchar_t *value, size_t value_length)
CGUL_EXPORT void	cgul_hstring__insert_char (cgul_exception_t *cex, cgul_hstring_t hs, size_t index, cgul_hchar_t value)
CGUL_EXPORT void	cgul_hstring__pad_right (cgul_exception_t *cex, cgul_hstring_t hs, size_t width, cgul_hchar_t pad)
CGUL_EXPORT void	cgul_hstring__pad_left (cgul_exception_t *cex, cgul_hstring_t hs, size_t width, cgul_hchar_t pad)
CGUL_EXPORT void	cgul_hstring__trim (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__trim_left (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__trim_right (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__reverse (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT size_t	cgul_hstring__get_length (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT size_t	cgul_hstring__set_length (cgul_exception_t *cex, cgul_hstring_t hs, size_t length)
CGUL_EXPORT void	cgul_hstring__externally_adjusted (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__trim_capacity (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT size_t	cgul_hstring__get_minimum_capacity (cgul_exception_t *cex, cgul_hstring_t hs)
CGUL_EXPORT void	cgul_hstring__set_minimum_capacity (cgul_exception_t *cex, cgul_hstring_t hs, size_t minimum_capacity)
CGUL_EXPORT int	cgul_hstring__compare (cgul_exception_t *cex, cgul_hstring_t hs1, cgul_hstring_t hs2)
CGUL_EXPORT void	cgul_hstring__swap (cgul_exception_t *cex, cgul_hstring_t hs1, cgul_hstring_t hs2)

Detailed Description

Simple 16-bit wide-character string class. Unlike the cgul_string class, this class and cgul_wstring co-opt the role of wchar_t strings in C because, as a practical matter, wchar_t is not portable.

As a result, this class defines cgul_hchar_t to always be an unsigned 16-bit value. This means you cannot portably use any of the standard C functions with these strings, but you can convert these strings to UTF-8 and use the standard char* functions.

If you need to read these strings from file, I recommend that the file be UTF-8 encoded. You can then read the strings from file using cgul_crlf_file. You can then convert them from UTF-8 using cgul_unicode__mbstohcs().

If you need to write these strings to file, I recommend that you convert the string to UTF-8 using cgul_unicode__hcstombs(). You can then write the resulting char* string to file using cgul_fprintf().

Author

Paul Serice

Typedef Documentation

cgul_hstring_t

typedef typedefCGUL_BEGIN_C struct cgul_hstring* cgul_hstring_t

Opaque pointer to cgul_hstring instance.

Function Documentation

cgul_hstring__new()

CGUL_EXPORT cgul_hstring_t cgul_hstring__new

(

cgul_exception_t *

cex

)

Create a new cgul_hstring object that holds an empty string. The caller is responsible for freeing the object by calling cgul_hstring__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

The following three methods implement the "cacheable" interface defined by cgul_cache:

    cgul_hstring__new()
    cgul_hstring__delete()
    cgul_hstring__clear()

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_hstring instance

Referenced by cgul_hstring_cxx::cgul_hstring_cxx().

cgul_hstring__new_from_hcstring()

CGUL_EXPORT cgul_hstring_t cgul_hstring__new_from_hcstring	(	cgul_exception_t *	cex,
		const cgul_hchar_t *	value
	)

Create a new cgul_hstring object that is initialized with a copy of value. The caller is responsible for freeing the object by calling cgul_hstring__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	value	initial value

Returns

new cgul_hstring instance

Referenced by cgul_hstring_cxx::cgul_hstring_cxx().

cgul_hstring__delete()

CGUL_EXPORT void cgul_hstring__delete

(

cgul_hstring_t

hs

)

cgul_hstring__delete() frees all internally allocated memory. Do not try to use hs after calling this method.

Parameters

[in]

hs

cgul_hstring instance

Referenced by cgul_hstring_cxx::set_obj(), and cgul_hstring_cxx::~cgul_hstring_cxx().

cgul_hstring__get_value()

CGUL_EXPORT cgul_hchar_t* cgul_hstring__get_value	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

This method returns a pointer to the internal wide-character string. You are allowed to manually set individual characters in the string. Just remember to call cgul_hstring__externally_adjusted() afterward. Compare this method to cgul_hstring__take_value().

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Returns

underlying wide-character string

See also

cgul_hstring__externally_adjusted

Referenced by cgul_hstring_cxx::get_value(), and cgul_hstring_cxx::operator[]().

cgul_hstring__take_value()

CGUL_EXPORT cgul_hchar_t* cgul_hstring__take_value	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

This method lets you take ownership of the underlying wide-character string which is returned. Immediately upon taking ownership, the internal state of this class is reset including resetting a new underlying wide-character 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 cgul_hstring__get_value().

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Returns

underlying wide-character string

Referenced by cgul_hstring_cxx::take_value().

cgul_hstring__set_value()

CGUL_EXPORT void cgul_hstring__set_value	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		const cgul_hchar_t *	value
	)

Set the value of the underlying wide-character string by copying characters from value to s. The caller is responsible for making sure value is terminated with a CGUL_HCHAR__NUL character. This method does not uses strcpy() or memcpy(). This means that value and s can overlap.

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	value	new value

Referenced by cgul_hstring_cxx::operator=(), and cgul_hstring_cxx::set_value().

cgul_hstring__get_value_at()

CGUL_EXPORT cgul_hchar_t cgul_hstring__get_value_at	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	index
	)

This method returns the character in hs indicated by index where index is zero-based. If index is out of bounds, (cgul_hchar_t)0 is returned and an exception is thrown.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	index	index into hs

Returns

wide character at index

Referenced by cgul_hstring_cxx::get_value_at().

cgul_hstring__set_value_at()

CGUL_EXPORT void cgul_hstring__set_value_at	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	index,
		cgul_hchar_t	hc
	)

This method sets the wide character in hs indicated by index where index is zero-based to hc. If index is out of bounds, an exception is thrown.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_string instance
[in]	index	index into s
[in]	hc	character

cgul_hstring__clear()

CGUL_EXPORT void cgul_hstring__clear

(

cgul_hstring_t

hs

)

This method is equivalent to calling cgul_hstring__set_value() where value is an empty string. This method is designed to be used as the cgul_cache_restructor_t method. This means it is not allowed to throw an exception.

Parameters

[in]

hs

cgul_hstring instance

Referenced by cgul_hstring_cxx::clear().

cgul_hstring__to_schar()

CGUL_EXPORT signed char cgul_hstring__to_schar	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

See also

cgul_hstring__get_value_at()

Referenced by cgul_hstring_cxx::to_schar().

cgul_hstring__to_uchar()

CGUL_EXPORT unsigned char cgul_hstring__to_uchar	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

See also

cgul_hstring__get_value_at()

Referenced by cgul_hstring_cxx::to_uchar().

cgul_hstring__to_short()

CGUL_EXPORT short int cgul_hstring__to_short	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_short().

cgul_hstring__to_ushort()

CGUL_EXPORT unsigned short int cgul_hstring__to_ushort	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_ushort().

cgul_hstring__to_int()

CGUL_EXPORT int cgul_hstring__to_int	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_int().

cgul_hstring__to_unsigned()

CGUL_EXPORT unsigned int cgul_hstring__to_unsigned	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_unsigned().

cgul_hstring__to_long()

CGUL_EXPORT long int cgul_hstring__to_long	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_long().

cgul_hstring__to_unsigned_long()

CGUL_EXPORT unsigned long int cgul_hstring__to_unsigned_long	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		int	base
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_hstring_cxx::to_unsigned_long().

cgul_hstring__to_double()

CGUL_EXPORT double cgul_hstring__to_double	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

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.

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance

Returns

converted value

Referenced by cgul_hstring_cxx::to_double().

cgul_hstring__append()

CGUL_EXPORT void cgul_hstring__append	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		const cgul_hchar_t *	value
	)

Appends value to hs. The implementation of this method is such that it is possible for value to be a substring of hs. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	value	value to append

Referenced by cgul_hstring_cxx::append(), and cgul_hstring_cxx::operator+=().

cgul_hstring__append_block()

CGUL_EXPORT void cgul_hstring__append_block	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		const void *	block,
		size_t	block_size
	)

Append a block of non-CGUL_HCHAR__NUL characters. The block_size is the number of characters (not bytes) in the block. The caller should verify that there are no embedded NUL characters in the string. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	block	block to append
[in]	block_size	size of block to append

Referenced by cgul_hstring_cxx::append_block().

cgul_hstring__append_char()

CGUL_EXPORT void cgul_hstring__append_char	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		cgul_hchar_t	hc
	)

Append hc to hs.

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	hc	wide character to append

Referenced by cgul_hstring_cxx::append_char().

cgul_hstring__insert()

CGUL_EXPORT void cgul_hstring__insert	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	index,
		const cgul_hchar_t *	value,
		size_t	value_length
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	index	index in s where value is inserted
[in]	value	value to insert
[in]	value_length	length of value

Referenced by cgul_hstring_cxx::insert().

cgul_hstring__insert_char()

CGUL_EXPORT void cgul_hstring__insert_char	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	index,
		cgul_hchar_t	value
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	index	index in s where value is inserted
[in]	value	value to insert

Referenced by cgul_hstring_cxx::insert_char().

cgul_hstring__pad_right()

CGUL_EXPORT void cgul_hstring__pad_right	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	width,
		cgul_hchar_t	pad
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	width	padding width
[in]	pad	wide character to use for padding

Referenced by cgul_hstring_cxx::pad_right().

cgul_hstring__pad_left()

CGUL_EXPORT void cgul_hstring__pad_left	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	width,
		cgul_hchar_t	pad
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	width	padding width
[in]	pad	wide character to use for padding

Referenced by cgul_hstring_cxx::pad_left().

cgul_hstring__trim()

CGUL_EXPORT void cgul_hstring__trim	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

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

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Referenced by cgul_hstring_cxx::trim().

cgul_hstring__trim_left()

CGUL_EXPORT void cgul_hstring__trim_left	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

Trim the string by removing leading white-space where white-space is definded by cgul_hchar__isspace().

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Referenced by cgul_hstring_cxx::trim_left().

cgul_hstring__trim_right()

CGUL_EXPORT void cgul_hstring__trim_right	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

Trim the string by removing trailing white-space where white-space is definded by cgul_hchar__isspace().

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Referenced by cgul_hstring_cxx::trim_right().

cgul_hstring__reverse()

CGUL_EXPORT void cgul_hstring__reverse	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

Reverse the order of the characaters in hs.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Referenced by cgul_hstring_cxx::reverse().

cgul_hstring__get_length()

CGUL_EXPORT size_t cgul_hstring__get_length	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

This method returns the length of the string. This is the number of cgul_hchar_t elements in the string, not the number of bytes. If hs is a UTF-16 string, surrogate pairs count as two while all other characters count as one. Call cgul_unicode__get_hchar_count() to get an exact character count for UTF-16 strings.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Returns

length of the string

Referenced by cgul_hstring_cxx::get_length(), and cgul_hstring_cxx::operator[]().

cgul_hstring__set_length()

CGUL_EXPORT size_t cgul_hstring__set_length	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	length
	)

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

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	length	new, shorter length of the string

Returns

previous length of the string

Referenced by cgul_hstring_cxx::set_length().

cgul_hstring__externally_adjusted()

CGUL_EXPORT void cgul_hstring__externally_adjusted	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

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

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

See also

cgul_hstring__get_value

Referenced by cgul_hstring_cxx::externally_adjusted().

cgul_hstring__trim_capacity()

CGUL_EXPORT void cgul_hstring__trim_capacity	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

Trim the string by returning excess capacity to the heap.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Referenced by cgul_hstring_cxx::trim_capacity().

cgul_hstring__get_minimum_capacity()

CGUL_EXPORT size_t cgul_hstring__get_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs
	)

Get the minimum capacity.

Parameters

[in]	cex	c-style exception
[in]	hs	cgul_hstring instance

Returns

minimum capacity

Referenced by cgul_hstring_cxx::get_minimum_capacity().

cgul_hstring__set_minimum_capacity()

CGUL_EXPORT void cgul_hstring__set_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs,
		size_t	minimum_capacity
	)

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,out]	cex	c-style exception
[in]	hs	cgul_hstring instance
[in]	minimum_capacity	minimum capacity

Referenced by cgul_hstring_cxx::set_minimum_capacity().

cgul_hstring__compare()

CGUL_EXPORT int cgul_hstring__compare	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs1,
		cgul_hstring_t	hs2
	)

Perform a case-significant wide-character string comparison of hs1 and hs2. Return -1, 0, or 1 if hs1 is less than, equal to, or greater than hs2 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 objects as keys into a cgul_rbtree 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__hcscmp() instead if inserting raw cgul_hchar strings as keys into a cgul_rbtree object.

Parameters

[in]	cex	c-style exception
[in]	hs1	left-hand side
[in]	hs2	right-hand side

Returns

-1, 0, or 1 if hs1 is less than, equal to, or greater than hs2 respectively

See also

cgul_hchar__hcscmp()

Referenced by cgul_hstring_cxx::compare().

cgul_hstring__swap()

CGUL_EXPORT void cgul_hstring__swap	(	cgul_exception_t *	cex,
		cgul_hstring_t	hs1,
		cgul_hstring_t	hs2
	)

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

Parameters

[in]	cex	c-style exception
[in]	hs1	cgul_hstring instance
[in]	hs2	cgul_hstring instance

Referenced by cgul_hstring_cxx::swap().