string class More...

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

Include dependency graph for cgul_string.h:

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

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_string *	cgul_string_t

Functions
CGUL_EXPORT cgul_string_t	cgul_string__new (cgul_exception_t *cex)

CGUL_EXPORT cgul_string_t	cgul_string__new_from_cstring (cgul_exception_t cex, const char value)

CGUL_EXPORT void	cgul_string__delete (cgul_string_t s)

CGUL_EXPORT char *	cgul_string__get_value (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT char *	cgul_string__take_value (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__set_value (cgul_exception_t cex, cgul_string_t s, const char value)

CGUL_EXPORT char	cgul_string__get_value_at (cgul_exception_t *cex, cgul_string_t s, size_t index)

CGUL_EXPORT void	cgul_string__set_value_at (cgul_exception_t *cex, cgul_string_t s, size_t index, char c)

CGUL_EXPORT void	cgul_string__clear (cgul_string_t s)

CGUL_EXPORT signed char	cgul_string__to_schar (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT unsigned char	cgul_string__to_uchar (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT short int	cgul_string__to_short (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT unsigned short int	cgul_string__to_ushort (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT int	cgul_string__to_int (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT unsigned int	cgul_string__to_unsigned (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT long int	cgul_string__to_long (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT unsigned long int	cgul_string__to_unsigned_long (cgul_exception_t *cex, cgul_string_t s, int base)

CGUL_EXPORT double	cgul_string__to_double (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__append (cgul_exception_t cex, cgul_string_t s, const char value)

CGUL_EXPORT void	cgul_string__append_block (cgul_exception_t cex, cgul_string_t s, const void block, size_t block_size)

CGUL_EXPORT int	cgul_string__append_sprintf (cgul_exception_t cex, cgul_string_t s, const char format,...)

CGUL_EXPORT int	cgul_string__append_vsprintf (cgul_exception_t cex, cgul_string_t s, const char format, va_list args)

CGUL_EXPORT void	cgul_string__append_char (cgul_exception_t *cex, cgul_string_t s, char c)

CGUL_EXPORT void	cgul_string__append_hchar (cgul_exception_t cex, cgul_string_t s, cgul_hchar_t utf16, size_t utf16_length)

CGUL_EXPORT void	cgul_string__append_wchar (cgul_exception_t *cex, cgul_string_t s, cgul_wchar_t utf32)

CGUL_EXPORT void	cgul_string__append_decimal (cgul_exception_t *cex, cgul_string_t s, long int value)

CGUL_EXPORT void	cgul_string__append_unsigned_decimal (cgul_exception_t *cex, cgul_string_t s, size_t value)

CGUL_EXPORT void	cgul_string__append_octal (cgul_exception_t *cex, cgul_string_t s, size_t value)

CGUL_EXPORT void	cgul_string__append_hexadecimal (cgul_exception_t *cex, cgul_string_t s, size_t value, int caps)

CGUL_EXPORT void	cgul_string__append_double (cgul_exception_t *cex, cgul_string_t s, double value, int precision)

CGUL_EXPORT void	cgul_string__append_pointer (cgul_exception_t cex, cgul_string_t s, const void ptr)

CGUL_EXPORT void	cgul_string__insert (cgul_exception_t cex, cgul_string_t s, size_t index, const char value, size_t value_length)

CGUL_EXPORT void	cgul_string__insert_char (cgul_exception_t *cex, cgul_string_t s, size_t index, char value)

CGUL_EXPORT void	cgul_string__pad_right (cgul_exception_t *cex, cgul_string_t s, size_t width, cgul_wchar_t pad)

CGUL_EXPORT void	cgul_string__pad_left (cgul_exception_t *cex, cgul_string_t s, size_t width, cgul_wchar_t pad)

CGUL_EXPORT void	cgul_string__trim (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__trim_left (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__trim_right (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__reverse (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT size_t	cgul_string__get_length (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT size_t	cgul_string__set_length (cgul_exception_t *cex, cgul_string_t s, size_t length)

CGUL_EXPORT void	cgul_string__externally_adjusted (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__trim_capacity (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT size_t	cgul_string__get_minimum_capacity (cgul_exception_t *cex, cgul_string_t s)

CGUL_EXPORT void	cgul_string__set_minimum_capacity (cgul_exception_t *cex, cgul_string_t s, size_t minimum_capacity)

CGUL_EXPORT int	cgul_string__compare (cgul_exception_t *cex, cgul_string_t s1, cgul_string_t s2)

CGUL_EXPORT int	cgul_string__icompare (cgul_exception_t *cex, cgul_string_t s1, cgul_string_t s2)

CGUL_EXPORT void	cgul_string__swap (cgul_exception_t *cex, cgul_string_t s1, cgul_string_t s2)

Detailed Description

Simple string class. The idea behind this class is to not co-opt the role of c-style strings. Rather the idea is that you can use this class to safely generate c-style strings and then use cgul_string__take_value() (or maybe cgul_string__get_value()) once your string has the desired value. You can then use the resulting char* with any of the standard c library calls that require a string.

Author: Paul Serice

Typedef Documentation

§ cgul_string_t

typedef typedefCGUL_BEGIN_C struct cgul_string* cgul_string_t

Opaque pointer to a cgul_string instance.

Function Documentation

§ cgul_string__new()

CGUL_EXPORT cgul_string_t cgul_string__new ( cgul_exception_t * cex )

Create a new cgul_string object that holds an empty string. The caller is responsible for freeing the object by calling cgul_string__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_string__new()
    cgul_string__delete()
    cgul_string__clear()

Parameters

[in,out] cex c-style exception

Returns: new cgul_string instance

Referenced by cgul_string_cxx::cgul_string_cxx().

§ cgul_string__new_from_cstring()

CGUL_EXPORT cgul_string_t cgul_string__new_from_cstring	(	cgul_exception_t *	cex,
		const char *	value
	)

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

Referenced by cgul_string_cxx::cgul_string_cxx().

§ cgul_string__delete()

CGUL_EXPORT void cgul_string__delete ( cgul_string_t s )

This method frees all internally allocated memory. Do not try to use s after calling this method.

Parameters

[in] s cgul_string instance

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

§ cgul_string__get_value()

CGUL_EXPORT char* cgul_string__get_value	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Returns: underlying c-style string

See also: cgul_string__externally_adjusted

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

§ cgul_string__take_value()

CGUL_EXPORT char* cgul_string__take_value	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

This method lets you take ownership of the underlying C-style string which is returned. The client is responsible for calling free() on the pointer returned.

Just prior to taking ownership, the internal state of s is reset. If an error occurs when attempting to reset s, s is left unaltered, NULL is returned, and an exception is thrown.

One use of this function is to build up a string using cgul_string that you then pass to cgul_hash or cgul_rbtree. Compare this function with cgul_string__get_value().

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance

Returns: underlying c-style string

Referenced by cgul_string_cxx::take_value().

§ cgul_string__set_value()

CGUL_EXPORT void cgul_string__set_value	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const char *	value
	)

Set the value of the underlying c-style string by copying characters from value to s. The caller is responsible for making sure value is terminated with a NULL 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]	s	`cgul_string` instance
[in]	value	new value

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

§ cgul_string__get_value_at()

CGUL_EXPORT char cgul_string__get_value_at	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	index
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	index	index into `s`

Returns: character at index

Referenced by cgul_string_cxx::get_value_at().

§ cgul_string__set_value_at()

CGUL_EXPORT void cgul_string__set_value_at	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	index,
		char	c
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	index	index into `s`
[in]	c	character

Referenced by cgul_string_cxx::set_value_at().

§ cgul_string__clear()

CGUL_EXPORT void cgul_string__clear ( cgul_string_t s )

This method is equivalent to calling cgul_string__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] s cgul_string instance

Referenced by cgul_string_cxx::clear().

§ cgul_string__to_schar()

CGUL_EXPORT signed char cgul_string__to_schar	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

See also: cgul_string__get_value_at()

Referenced by cgul_string_cxx::to_schar().

§ cgul_string__to_uchar()

CGUL_EXPORT unsigned char cgul_string__to_uchar	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

See also: cgul_string__get_value_at()

Referenced by cgul_string_cxx::to_uchar().

§ cgul_string__to_short()

CGUL_EXPORT short int cgul_string__to_short	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_short().

§ cgul_string__to_ushort()

CGUL_EXPORT unsigned short int cgul_string__to_ushort	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_ushort().

§ cgul_string__to_int()

CGUL_EXPORT int cgul_string__to_int	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_int().

§ cgul_string__to_unsigned()

CGUL_EXPORT unsigned int cgul_string__to_unsigned	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_unsigned().

§ cgul_string__to_long()

CGUL_EXPORT long int cgul_string__to_long	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_long().

§ cgul_string__to_unsigned_long()

CGUL_EXPORT unsigned long int cgul_string__to_unsigned_long	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	base	base to use for the conversion

Returns: converted value

Referenced by cgul_string_cxx::to_unsigned_long().

§ cgul_string__to_double()

CGUL_EXPORT double cgul_string__to_double	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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]	s	`cgul_string` instance

Returns: converted value

Referenced by cgul_string_cxx::to_double().

§ cgul_string__append()

CGUL_EXPORT void cgul_string__append	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const char *	value
	)

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

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	value to append

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

§ cgul_string__append_block()

CGUL_EXPORT void cgul_string__append_block	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const void *	block,
		size_t	block_size
	)

Append a block of non-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,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	block	block to append
[in]	block_size	size of block to append

Referenced by cgul_string_cxx::append_block().

§ cgul_string__append_sprintf()

CGUL_EXPORT int cgul_string__append_sprintf	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const char *	format,
			...
	)

This function is a thin wrapper around cgul_string__append_vsprintf().

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
	format	format string
	...	variable number of arguments that satisfy `format`

Returns: number of characters appended

§ cgul_string__append_vsprintf()

CGUL_EXPORT int cgul_string__append_vsprintf	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const char *	format,
		va_list	args
	)

This function substitutes the conversion specifications in the format string and appends them to s. If an error occurs, an exception is thrown.

The format string is the same as what you pass into sprintf() or snprintf(). The following length modifiers are honored: l, h, z.

Any string associated with a "%s" conversion specification is assumed to be a UTF-8 string. The main difference that this makes is that, if a field width is specified, it specifies the number of characters, not bytes, in the field.

The "%ls" conversion specification is honored, but instead of converting a string composed of wchar_t characters to a multi-byte string encoded according to the current locale, it converts a string composed of Unicode UTF-32 cgul_wchar_t characters to a UTF-8 string. The "%ls" conversions also differ in that, if a precision is given, it determines the number of characters appended not the number of bytes.

The "%lc" conversion specification is honored, but like the "%ls" conversion specification, it converts from UTF-32 to UTF-8 exclusively. Also, it expects the associated argument to be cgul_wchar_t, not wchar_t.

The GNU "%m" conversion specification is honored. This conversion specification appends the result of strerror(errno).

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
	format	format string
	args	variable number of arguments that satisfy `format`

Returns: number of characters appended

Referenced by cgul_string_cxx::append_vsprintf().

§ cgul_string__append_char()

CGUL_EXPORT void cgul_string__append_char	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		char	c
	)

Append c to s.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	c	character to append

Referenced by cgul_string_cxx::append_char().

§ cgul_string__append_hchar()

CGUL_EXPORT void cgul_string__append_hchar	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		cgul_hchar_t *	utf16,
		size_t	utf16_length
	)

Append the UTF-16 character utf16 to s as a UTF-8 sequence. Because utf16 could be a surrogate pair, to avoid reading off the end of the sequence, the number of cgul_hchar_t elements (i.e., 16-bit elements) in the utf16 buffer must be specified using utf16_length. If more than one UTF-16 character is present in the utf16 buffer, only the first character is appended.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	utf16	UTF-16 character to append
[in]	utf16_length	length of `utf16` in `cgul_hchar_t` elements

Referenced by cgul_string_cxx::append_hchar().

§ cgul_string__append_wchar()

CGUL_EXPORT void cgul_string__append_wchar	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		cgul_wchar_t	utf32
	)

Append the UTF-32 character utf32 to s as a UTF-8 sequence.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	utf32	UTF-32 character to append

Referenced by cgul_string_cxx::append_wchar().

§ cgul_string__append_decimal()

CGUL_EXPORT void cgul_string__append_decimal	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		long int	value
	)

Append value to s in decimal format.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	to append

Referenced by cgul_string_cxx::append_decimal().

§ cgul_string__append_unsigned_decimal()

CGUL_EXPORT void cgul_string__append_unsigned_decimal	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	value
	)

Append value to s in decimal format.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	to append

Referenced by cgul_string_cxx::append_unsigned_decimal().

§ cgul_string__append_octal()

CGUL_EXPORT void cgul_string__append_octal	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	value
	)

Append value to s in octal format.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	to append

Referenced by cgul_string_cxx::append_octal().

§ cgul_string__append_hexadecimal()

CGUL_EXPORT void cgul_string__append_hexadecimal	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	value,
		int	caps
	)

Append value to s in hexadecimal format using "abcdef".

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	to append
[in]	caps	whether to capitalize the hex digits

Referenced by cgul_string_cxx::append_hexadecimal().

§ cgul_string__append_double()

CGUL_EXPORT void cgul_string__append_double	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		double	value,
		int	precision
	)

Append value to s. "precision" determines the number of significant digits that are printed. Zeros after the decimal point at the end of number are not printed.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	value	to append
[in]	precision	precision

Referenced by cgul_string_cxx::append_double().

§ cgul_string__append_pointer()

CGUL_EXPORT void cgul_string__append_pointer	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		const void *	ptr
	)

Append ptr to s.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	ptr	pointer to append

Referenced by cgul_string_cxx::append_pointer().

§ cgul_string__insert()

CGUL_EXPORT void cgul_string__insert	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	index,
		const char *	value,
		size_t	value_length
	)

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

Parameters

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

Referenced by cgul_string_cxx::insert().

§ cgul_string__insert_char()

CGUL_EXPORT void cgul_string__insert_char	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	index,
		char	value
	)

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

Parameters

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

Referenced by cgul_string_cxx::insert_char().

§ cgul_string__pad_right()

CGUL_EXPORT void cgul_string__pad_right	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	width,
		cgul_wchar_t	pad
	)

Pad the current string in s such that it is at least width characters (not bytes) wide using the pad character. s will be right aligned. Note that this method assumes that s is in UTF-8 format and counts characters accordingly.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	width	padding width
[in]	pad	character to use for padding

Referenced by cgul_string_cxx::pad_right().

§ cgul_string__pad_left()

CGUL_EXPORT void cgul_string__pad_left	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	width,
		cgul_wchar_t	pad
	)

Pad the current string in s such that it is at least width characters (not bytes) wide using the pad character. s will be left aligned. Note that this method assumes that s is in UTF-8 format and counts characters accordingly.

Parameters

[in,out]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	width	padding width
[in]	pad	character to use for padding

Referenced by cgul_string_cxx::pad_left().

§ cgul_string__trim()

CGUL_EXPORT void cgul_string__trim	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Referenced by cgul_string_cxx::trim().

§ cgul_string__trim_left()

CGUL_EXPORT void cgul_string__trim_left	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Referenced by cgul_string_cxx::trim_left().

§ cgul_string__trim_right()

CGUL_EXPORT void cgul_string__trim_right	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Referenced by cgul_string_cxx::trim_right().

§ cgul_string__reverse()

CGUL_EXPORT void cgul_string__reverse	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

Reverse the order of the characters in s.

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Referenced by cgul_string_cxx::reverse().

§ cgul_string__get_length()

CGUL_EXPORT size_t cgul_string__get_length	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

This method returns the length of the string sin bytes. If s is a UTF-8 string, call cgul_unicode__get_char_count() to get the length of the string in characters.

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Returns: length of the string

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

§ cgul_string__set_length()

CGUL_EXPORT size_t cgul_string__set_length	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		size_t	length
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance
[in]	length	new, shorter length of the string

Returns: previous length of the string

Referenced by cgul_string_cxx::set_length().

§ cgul_string__externally_adjusted()

CGUL_EXPORT void cgul_string__externally_adjusted	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

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

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

See also: cgul_string__get_value

Referenced by cgul_string_cxx::externally_adjusted().

§ cgul_string__trim_capacity()

CGUL_EXPORT void cgul_string__trim_capacity	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

Trim the string by returning excess capacity to the heap.

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Referenced by cgul_string_cxx::trim_capacity().

§ cgul_string__get_minimum_capacity()

CGUL_EXPORT size_t cgul_string__get_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_string_t	s
	)

Get the minimum capacity.

Parameters

[in]	cex	c-style exception
[in]	s	`cgul_string` instance

Returns: minimum capacity

Referenced by cgul_string_cxx::get_minimum_capacity().

§ cgul_string__set_minimum_capacity()

CGUL_EXPORT void cgul_string__set_minimum_capacity	(	cgul_exception_t *	cex,
		cgul_string_t	s,
		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]	s	`cgul_string` instance
[in]	minimum_capacity	minimum capacity

Referenced by cgul_string_cxx::set_minimum_capacity().

§ cgul_string__compare()

CGUL_EXPORT int cgul_string__compare	(	cgul_exception_t *	cex,
		cgul_string_t	s1,
		cgul_string_t	s2
	)

Perform a case-significant string comparison of s1 and s2 using the current locale. Return -1, 0, or 1 if s1 is less than, equal to, or greater than s2 respectively.

Note that this method can throw an exception if either string contains a character that is not part of the current locale's collating sequence.

Parameters

[in,out]	cex	c-style exception
[in]	s1	left-hand side
[in]	s2	right-hand side

Returns: -1, 0, or 1 if s1 is less than, equal to, or greater than s2 respectively

See also: cgul_char__strcmp()

Referenced by cgul_string_cxx::compare().

§ cgul_string__icompare()

CGUL_EXPORT int cgul_string__icompare	(	cgul_exception_t *	cex,
		cgul_string_t	s1,
		cgul_string_t	s2
	)

Perform a case-insensitive string comparison of string s1 and s2 using the current locale. Return -1, 0, or 1 if s1 is less than, equal to, or greater than s2 respectively.

Note that this method can throw an exception if either string contains a character that is not part of the current locale's collating sequence.

Parameters

[in,out]	cex	c-style exception
[in]	s1	left-hand side
[in]	s2	right-hand side

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

See also: cgul_create_ivalue

Referenced by cgul_string_cxx::icompare().

§ cgul_string__swap()

CGUL_EXPORT void cgul_string__swap	(	cgul_exception_t *	cex,
		cgul_string_t	s1,
		cgul_string_t	s2
	)

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

Parameters

[in]	cex	c-style exception
[in]	s1	`cgul_string` instance
[in]	s2	`cgul_string` instance

Referenced by cgul_string_cxx::swap().

Typedefs

Functions

Detailed Description

Typedef Documentation

§ cgul_string_t

Function Documentation

§ cgul_string__new()

§ cgul_string__new_from_cstring()

§ cgul_string__delete()

§ cgul_string__get_value()

§ cgul_string__take_value()

§ cgul_string__set_value()

§ cgul_string__get_value_at()

§ cgul_string__set_value_at()

§ cgul_string__clear()

§ cgul_string__to_schar()

§ cgul_string__to_uchar()

§ cgul_string__to_short()

§ cgul_string__to_ushort()

§ cgul_string__to_int()

§ cgul_string__to_unsigned()

§ cgul_string__to_long()

§ cgul_string__to_unsigned_long()

§ cgul_string__to_double()

§ cgul_string__append()

§ cgul_string__append_block()

§ cgul_string__append_sprintf()

§ cgul_string__append_vsprintf()

§ cgul_string__append_char()

§ cgul_string__append_hchar()

§ cgul_string__append_wchar()

§ cgul_string__append_decimal()

§ cgul_string__append_unsigned_decimal()

§ cgul_string__append_octal()

§ cgul_string__append_hexadecimal()

§ cgul_string__append_double()

§ cgul_string__append_pointer()

§ cgul_string__insert()

§ cgul_string__insert_char()

§ cgul_string__pad_right()

§ cgul_string__pad_left()

§ cgul_string__trim()

§ cgul_string__trim_left()

§ cgul_string__trim_right()

§ cgul_string__reverse()

§ cgul_string__get_length()

§ cgul_string__set_length()

§ cgul_string__externally_adjusted()

§ cgul_string__trim_capacity()

§ cgul_string__get_minimum_capacity()

§ cgul_string__set_minimum_capacity()

§ cgul_string__compare()

§ cgul_string__icompare()

§ cgul_string__swap()