cgul_wstring.h File Reference

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

#include "cgul_common.h"
#include "cgul_exception.h"
#include "cgul_wchar.h"

Include dependency graph for cgul_wstring.h:

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

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_wstring *	cgul_wstring_t

Functions
CGUL_EXPORT cgul_wstring_t	cgul_wstring__new (cgul_exception_t *cex)
CGUL_EXPORT cgul_wstring_t	cgul_wstring__new_from_wcstring (cgul_exception_t *cex, const cgul_wchar_t *value)
CGUL_EXPORT void	cgul_wstring__delete (cgul_wstring_t ws)
CGUL_EXPORT cgul_wchar_t *	cgul_wstring__get_value (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT cgul_wchar_t *	cgul_wstring__take_value (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__set_value (cgul_exception_t *cex, cgul_wstring_t ws, const cgul_wchar_t *value)
CGUL_EXPORT cgul_wchar_t	cgul_wstring__get_value_at (cgul_exception_t *cex, cgul_wstring_t ws, size_t index)
CGUL_EXPORT void	cgul_wstring__set_value_at (cgul_exception_t *cex, cgul_wstring_t ws, size_t index, cgul_wchar_t wc)
CGUL_EXPORT void	cgul_wstring__clear (cgul_wstring_t ws)
CGUL_EXPORT signed char	cgul_wstring__to_schar (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT unsigned char	cgul_wstring__to_uchar (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT short int	cgul_wstring__to_short (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT unsigned short int	cgul_wstring__to_ushort (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT int	cgul_wstring__to_int (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT unsigned int	cgul_wstring__to_unsigned (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT long int	cgul_wstring__to_long (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT unsigned long int	cgul_wstring__to_unsigned_long (cgul_exception_t *cex, cgul_wstring_t ws, int base)
CGUL_EXPORT double	cgul_wstring__to_double (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__append (cgul_exception_t *cex, cgul_wstring_t ws, const cgul_wchar_t *value)
CGUL_EXPORT void	cgul_wstring__append_block (cgul_exception_t *cex, cgul_wstring_t ws, const void *block, size_t block_size)
CGUL_EXPORT void	cgul_wstring__append_char (cgul_exception_t *cex, cgul_wstring_t ws, cgul_wchar_t wc)
CGUL_EXPORT void	cgul_wstring__insert (cgul_exception_t *cex, cgul_wstring_t ws, size_t index, const cgul_wchar_t *value, size_t value_length)
CGUL_EXPORT void	cgul_wstring__insert_char (cgul_exception_t *cex, cgul_wstring_t ws, size_t index, cgul_wchar_t value)
CGUL_EXPORT void	cgul_wstring__pad_right (cgul_exception_t *cex, cgul_wstring_t ws, size_t width, cgul_wchar_t pad)
CGUL_EXPORT void	cgul_wstring__pad_left (cgul_exception_t *cex, cgul_wstring_t ws, size_t width, cgul_wchar_t pad)
CGUL_EXPORT void	cgul_wstring__trim (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__trim_left (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__trim_right (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__reverse (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT size_t	cgul_wstring__get_length (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT size_t	cgul_wstring__set_length (cgul_exception_t *cex, cgul_wstring_t ws, size_t length)
CGUL_EXPORT void	cgul_wstring__externally_adjusted (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__trim_capacity (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT size_t	cgul_wstring__get_minimum_capacity (cgul_exception_t *cex, cgul_wstring_t ws)
CGUL_EXPORT void	cgul_wstring__set_minimum_capacity (cgul_exception_t *cex, cgul_wstring_t ws, size_t minimum_capacity)
CGUL_EXPORT int	cgul_wstring__compare (cgul_exception_t *cex, cgul_wstring_t ws1, cgul_wstring_t ws2)
CGUL_EXPORT void	cgul_wstring__swap (cgul_exception_t *cex, cgul_wstring_t ws1, cgul_wstring_t ws2)

Detailed Description

Simple 32-bit wide-character string class. Unlike the cgul_string class, this class and cgul_hstring 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_wchar_t to always be an unsigned 32-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__mbstowcs().

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

Author

Paul Serice

Typedef Documentation

cgul_wstring_t

typedef typedefCGUL_BEGIN_C struct cgul_wstring* cgul_wstring_t

Opaque pointer to cgul_wstring instance.

Function Documentation

cgul_wstring__new()

CGUL_EXPORT cgul_wstring_t cgul_wstring__new

(

cgul_exception_t *

cex

)

Create a new cgul_wstring object that holds an empty string. The caller is responsible for freeing the object by calling cgul_wstring__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_wstring__new()
    cgul_wstring__delete()
    cgul_wstring__clear()

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_wstring instance

Referenced by cgul_wstring_cxx::cgul_wstring_cxx().

cgul_wstring__new_from_wcstring()

CGUL_EXPORT cgul_wstring_t cgul_wstring__new_from_wcstring	(	cgul_exception_t *	cex,
		const cgul_wchar_t *	value
	)

Create a new cgul_wstring object that is initialized with a copy of value. The caller is responsible for freeing the object by calling cgul_wstring__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_wstring instance

Referenced by cgul_wstring_cxx::cgul_wstring_cxx().

cgul_wstring__delete()

CGUL_EXPORT void cgul_wstring__delete

(

cgul_wstring_t

ws

)

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

Parameters

[in]

ws

cgul_wstring instance

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

cgul_wstring__get_value()

CGUL_EXPORT cgul_wchar_t* cgul_wstring__get_value	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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_wstring__externally_adjusted() afterward. Compare this method to cgul_wstring__take_value().

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Returns

underlying wide-character string

See also

cgul_wstring__externally_adjusted

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

cgul_wstring__take_value()

CGUL_EXPORT cgul_wchar_t* cgul_wstring__take_value	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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_wstring that you then pass to cgul_hash or cgul_rbtree. Compare this function with cgul_wstring__get_value().

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Returns

underlying wide-character string

Referenced by cgul_wstring_cxx::take_value().

cgul_wstring__set_value()

CGUL_EXPORT void cgul_wstring__set_value	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		const cgul_wchar_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_WCHAR__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]	ws	cgul_wstring instance
[in]	value	new value

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

cgul_wstring__get_value_at()

CGUL_EXPORT cgul_wchar_t cgul_wstring__get_value_at	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	index
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance
[in]	index	index into ws

Returns

wide character at index

Referenced by cgul_wstring_cxx::get_value_at().

cgul_wstring__set_value_at()

CGUL_EXPORT void cgul_wstring__set_value_at	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	index,
		cgul_wchar_t	wc
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance
[in]	index	index into s
[in]	wc	character

cgul_wstring__clear()

CGUL_EXPORT void cgul_wstring__clear

(

cgul_wstring_t

ws

)

This method is equivalent to calling cgul_wstring__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]

ws

cgul_wstring instance

Referenced by cgul_wstring_cxx::clear().

cgul_wstring__to_schar()

CGUL_EXPORT signed char cgul_wstring__to_schar	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

See also

cgul_wstring__get_value_at()

Referenced by cgul_wstring_cxx::to_schar().

cgul_wstring__to_uchar()

CGUL_EXPORT unsigned char cgul_wstring__to_uchar	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

See also

cgul_wstring__get_value_at()

Referenced by cgul_wstring_cxx::to_uchar().

cgul_wstring__to_short()

CGUL_EXPORT short int cgul_wstring__to_short	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_short().

cgul_wstring__to_ushort()

CGUL_EXPORT unsigned short int cgul_wstring__to_ushort	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_ushort().

cgul_wstring__to_int()

CGUL_EXPORT int cgul_wstring__to_int	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_int().

cgul_wstring__to_unsigned()

CGUL_EXPORT unsigned int cgul_wstring__to_unsigned	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_unsigned().

cgul_wstring__to_long()

CGUL_EXPORT long int cgul_wstring__to_long	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_long().

cgul_wstring__to_unsigned_long()

CGUL_EXPORT unsigned long int cgul_wstring__to_unsigned_long	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	base	base to use for the conversion

Returns

converted value

Referenced by cgul_wstring_cxx::to_unsigned_long().

cgul_wstring__to_double()

CGUL_EXPORT double cgul_wstring__to_double	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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]	ws	cgul_wstring instance

Returns

converted value

Referenced by cgul_wstring_cxx::to_double().

cgul_wstring__append()

CGUL_EXPORT void cgul_wstring__append	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		const cgul_wchar_t *	value
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	ws	cgul_wstring instance
[in]	value	value to append

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

cgul_wstring__append_block()

CGUL_EXPORT void cgul_wstring__append_block	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		const void *	block,
		size_t	block_size
	)

Append a block of non-CGUL_WCHAR__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]	ws	cgul_wstring instance
[in]	block	block to append
[in]	block_size	size of block to append

Referenced by cgul_wstring_cxx::append_block().

cgul_wstring__append_char()

CGUL_EXPORT void cgul_wstring__append_char	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		cgul_wchar_t	wc
	)

Append wc to ws.

Parameters

[in,out]	cex	c-style exception
[in]	ws	cgul_wstring instance
[in]	wc	wide character to append

Referenced by cgul_wstring_cxx::append_char().

cgul_wstring__insert()

CGUL_EXPORT void cgul_wstring__insert	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	index,
		const cgul_wchar_t *	value,
		size_t	value_length
	)

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

Parameters

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

Referenced by cgul_wstring_cxx::insert().

cgul_wstring__insert_char()

CGUL_EXPORT void cgul_wstring__insert_char	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	index,
		cgul_wchar_t	value
	)

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

Parameters

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

Referenced by cgul_wstring_cxx::insert_char().

cgul_wstring__pad_right()

CGUL_EXPORT void cgul_wstring__pad_right	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	width,
		cgul_wchar_t	pad
	)

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

Parameters

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

Referenced by cgul_wstring_cxx::pad_right().

cgul_wstring__pad_left()

CGUL_EXPORT void cgul_wstring__pad_left	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	width,
		cgul_wchar_t	pad
	)

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

Parameters

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

Referenced by cgul_wstring_cxx::pad_left().

cgul_wstring__trim()

CGUL_EXPORT void cgul_wstring__trim	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Referenced by cgul_wstring_cxx::trim().

cgul_wstring__trim_left()

CGUL_EXPORT void cgul_wstring__trim_left	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Referenced by cgul_wstring_cxx::trim_left().

cgul_wstring__trim_right()

CGUL_EXPORT void cgul_wstring__trim_right	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Referenced by cgul_wstring_cxx::trim_right().

cgul_wstring__reverse()

CGUL_EXPORT void cgul_wstring__reverse	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

Reverse the order of the characaters in ws.

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Referenced by cgul_wstring_cxx::reverse().

cgul_wstring__get_length()

CGUL_EXPORT size_t cgul_wstring__get_length	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

This method returns the length of the string. This is the number of wide characters in the string, not the number of bytes.

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Returns

length of the string

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

cgul_wstring__set_length()

CGUL_EXPORT size_t cgul_wstring__set_length	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		size_t	length
	)

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

Parameters

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

Returns

previous length of the string

Referenced by cgul_wstring_cxx::set_length().

cgul_wstring__externally_adjusted()

CGUL_EXPORT void cgul_wstring__externally_adjusted	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

See also

cgul_wstring__get_value

Referenced by cgul_wstring_cxx::externally_adjusted().

cgul_wstring__trim_capacity()

CGUL_EXPORT void cgul_wstring__trim_capacity	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

Trim the string by returning excess capacity to the heap.

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Referenced by cgul_wstring_cxx::trim_capacity().

cgul_wstring__get_minimum_capacity()

CGUL_EXPORT size_t cgul_wstring__get_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws
	)

Get the minimum capacity.

Parameters

[in]	cex	c-style exception
[in]	ws	cgul_wstring instance

Returns

minimum capacity

Referenced by cgul_wstring_cxx::get_minimum_capacity().

cgul_wstring__set_minimum_capacity()

CGUL_EXPORT void cgul_wstring__set_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws,
		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]	ws	cgul_wstring instance
[in]	minimum_capacity	minimum capacity

Referenced by cgul_wstring_cxx::set_minimum_capacity().

cgul_wstring__compare()

CGUL_EXPORT int cgul_wstring__compare	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws1,
		cgul_wstring_t	ws2
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws1	left-hand side
[in]	ws2	right-hand side

Returns

-1, 0, or 1 if ws1 is less than, equal to, or greater than ws2 respectively

See also

cgul_wchar__wcscmp()

Referenced by cgul_wstring_cxx::compare().

cgul_wstring__swap()

CGUL_EXPORT void cgul_wstring__swap	(	cgul_exception_t *	cex,
		cgul_wstring_t	ws1,
		cgul_wstring_t	ws2
	)

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

Parameters

[in]	cex	c-style exception
[in]	ws1	cgul_wstring instance
[in]	ws2	cgul_wstring instance

Referenced by cgul_wstring_cxx::swap().