cgul_string.h File Reference

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]cexc-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]cexc-style exception
[in]valueinitial 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]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_string instance
[in]valuenew 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]cexc-style exception
[in]scgul_string instance
[in]indexindex 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]cexc-style exception
[in]scgul_string instance
[in]indexindex into s
[in]ccharacter

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]scgul_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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_string instance
[in]basebase 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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_string instance
[in]valuevalue 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]cexc-style exception
[in]scgul_string instance
[in]blockblock to append
[in]block_sizesize 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]cexc-style exception
[in]scgul_string instance
formatformat 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]cexc-style exception
[in]scgul_string instance
formatformat string
argsvariable 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]cexc-style exception
[in]scgul_string instance
[in]ccharacter 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]cexc-style exception
[in]scgul_string instance
[in]utf16UTF-16 character to append
[in]utf16_lengthlength 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]cexc-style exception
[in]scgul_string instance
[in]utf32UTF-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]cexc-style exception
[in]scgul_string instance
[in]valueto 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]cexc-style exception
[in]scgul_string instance
[in]valueto 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]cexc-style exception
[in]scgul_string instance
[in]valueto 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]cexc-style exception
[in]scgul_string instance
[in]valueto append
[in]capswhether 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]cexc-style exception
[in]scgul_string instance
[in]valueto append
[in]precisionprecision

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]cexc-style exception
[in]scgul_string instance
[in]ptrpointer 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]cexc-style exception
[in]scgul_string instance
[in]indexindex in s where value is inserted
[in]valuevalue to insert
[in]value_lengthlength 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]cexc-style exception
[in]scgul_string instance
[in]indexindex in s where value is inserted
[in]valuevalue 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]cexc-style exception
[in]scgul_string instance
[in]widthpadding width
[in]padcharacter 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]cexc-style exception
[in]scgul_string instance
[in]widthpadding width
[in]padcharacter 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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_string instance
[in]lengthnew, 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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_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]cexc-style exception
[in]scgul_string instance
[in]minimum_capacityminimum 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]cexc-style exception
[in]s1left-hand side
[in]s2right-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]cexc-style exception
[in]s1left-hand side
[in]s2right-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]cexc-style exception
[in]s1cgul_string instance
[in]s2cgul_string instance

Referenced by cgul_string_cxx::swap().