cu/str.h: Multi-Byte Strings
[Data Types]

Data Structures
struct	cu_str
Defines
#define	cu_str_init_copy   cu_str_assign
#define	cu_str_charr(str)   (CU_MARG(cu_str_t, (str))->arr)
#define	cu_str_index_none   ((size_t)-1)
#define	cu_str_cct   cu_str_init
#define	cu_str_cct_cstr_static   cu_str_init_static_cstr
#define	cu_str_cct_uninit   cu_str_init_uninit
#define	cu_str_cct_copy   cu_str_init_copy
#define	cu_str_new_cstr_static   cu_str_new_static_cstr
#define	cu_str_onew_cstr_static   cu_str_onew_static_cstr
Functions
cuoo_type_t	cu_str_type ()
cu_bool_t	cu_is_str (void *s)
cu_bool_t	cu_str_is_empty (cu_str_t str)
size_t	cu_str_size (cu_str_t str)
char	cu_str_at (cu_str_t str, size_t i)
cu_str_t	cu_str_new (void)
cu_str_t	cu_str_onew (void)
void	cu_str_init (cu_str_t dest)
cu_str_t	cu_str_new_charr (char const *cstr, size_t len)
cu_str_t	cu_str_onew_charr (char const *cstr, size_t len)
cu_str_t	cu_str_new_cstr (char const *cstr)
cu_str_t	cu_str_onew_cstr (char const *cstr)
cu_str_t	cu_str_new_static_cstr (char const *cstr)
cu_str_t	cu_str_onew_static_cstr (char const *cstr)
void	cu_str_init_static_cstr (cu_str_t str, char const *cstr)
cu_str_t	cu_str_new_fmt (char const *fmt,...)
cu_str_t	cu_str_onew_fmt (char const *fmt,...)
cu_str_t	cu_str_new_vfmt (char const *fmt, va_list va)
cu_str_t	cu_str_onew_vfmt (char const *fmt, va_list va)
void	cu_str_init_uninit (cu_str_t str, size_t n)
cu_str_t	cu_str_new_uninit (size_t n)
cu_str_t	cu_str_onew_uninit (size_t n)
cu_str_t	cu_str_new_copy (cu_str_t str)
cu_str_t	cu_str_onew_copy (cu_str_t str)
void	cu_str_assign (cu_str_t dest, cu_str_t src)
cu_str_t	cu_str_new_2str (cu_str_t x, cu_str_t y)
cu_str_t	cu_str_onew_2str (cu_str_t x, cu_str_t y)
cu_str_t	cu_str_new_str_char (cu_str_t x, char y)
cu_str_t	cu_str_onew_str_char (cu_str_t x, char y)
cu_str_t	cu_str_new_str_cstr (cu_str_t x, char const *y)
cu_str_t	cu_str_onew_str_cstr (cu_str_t x, char const *y)
cu_str_t	cu_str_new_cstr_str (char const *x, cu_str_t y)
cu_str_t	cu_str_onew_cstr_str (char const *x, cu_str_t y)
cu_str_t	cu_str_new_2cstr (char const *x, char const *y)
cu_str_t	cu_str_onew_2cstr (char const *x, char const *y)
cu_str_t	cu_str_new_2charr (char const *s0, size_t n0, char const *s1, size_t n1)
cu_str_t	cu_str_onew_2charr (char const *s0, size_t n0, char const *s1, size_t n1)
cu_str_t	cu_str_new_3charr (char const *s0, size_t n0, char const *s1, size_t n1, char const *s2, size_t n2)
cu_str_t	cu_str_onew_3charr (char const *s0, size_t n0, char const *s1, size_t n1, char const *s2, size_t n2)
cu_str_t	cu_str_new_idr (cu_idr_t idr)
cu_str_t	cu_str_onew_idr (cu_idr_t idr)
void	cu_str_assign_substr (cu_str_t dest, size_t pos, size_t len)
cu_str_t	cu_str_substr (cu_str_t x, size_t pos, size_t len)
cu_str_t	cu_str_suffix (cu_str_t x, size_t pos)
void	cu_str_append_str (cu_str_t dest, cu_str_t src)
void	cu_str_append_char (cu_str_t dest, char ch)
void	cu_str_append_charr (cu_str_t dest, char const *s, size_t n)
void	cu_str_append_cstr (cu_str_t dest, char const *cstr)
void	cu_str_append_vfmt (cu_str_t dst, char const *fmt, va_list va)
void	cu_str_append_fmt (cu_str_t dst, char const *fmt,...)
void	cu_str_unappend (cu_str_t str, size_t char_count)
void	cu_str_insert_substr (cu_str_t dst, cu_str_t src, size_t pos)
void	cu_str_erase_substr (cu_str_t dst, size_t pos, size_t len)
char const *	cu_str_to_cstr (cu_str_t x)
cu_idr_t	cu_str_to_idr (cu_str_t str)
char const *	cu_str_charr (cu_str_t str)
cu_bool_t	cu_str_eq (cu_str_t x, cu_str_t y)
cu_hash_t	cu_str_hash (cu_str_t x)
int	cu_str_cmp (cu_str_t x, cu_str_t y)
int	cu_str_cmp_charr (cu_str_t x, char const *y_arr, size_t y_size)
int	cu_str_cmp_cstr (cu_str_t x, char const *y)
cu_bool_t	cu_str_subeq (cu_str_t x, size_t pos, cu_str_t y)
cu_bool_t	cu_str_subeq_cstr (cu_str_t x, size_t pos, char const *y)
cu_bool_t	cu_str_subeq_charr (cu_str_t x, size_t pos, char const *y_arr, size_t y_size)
int	cu_str_coll (cu_str_t x, cu_str_t y)
int	cu_str_coll_charr (cu_str_t x, char const *y_arr, size_t y_size)
int	cu_str_coll_cstr (cu_str_t x, char const *y)
size_t	cu_str_chr (cu_str_t str, char ch)
size_t	cu_str_rchr (cu_str_t str, char ch)
size_t	cu_str_chr_in_substr (cu_str_t str, size_t pos, size_t len, char ch)
size_t	cu_str_rchr_in_substr (cu_str_t str, size_t pos, size_t len, char ch)
void	cu_str_chop_space (cu_str_t str)
cu_str_t	cu_str_toupper (cu_str_t str)
cu_str_t	cu_str_tolower (cu_str_t str)
cu_bool_t	cu_str_next_space_delimited (cu_str_t str, size_t *pos_io, size_t *len_io)
cu_str_t	cu_str_quote (cu_str_t str)
	cu_clop (cu_str_eq_clop, cu_bool_t, cu_str_t, cu_str_t)
	cu_clop (cu_str_hash_clop, cu_hash_t, cu_str_t)
	cu_clop (cu_str_cmp_clop, int, cu_str_t, cu_str_t)
	cu_clop (cu_str_coll_clop, int, cu_str_t, cu_str_t)
Variables
cuoo_type_t	cuP_str_type

---

Define Documentation

#define cu_str_cct   cu_str_init

Deprecated:

Use cu_str_init.

#define cu_str_cct_copy   cu_str_init_copy

Deprecated:

#define cu_str_cct_cstr_static   cu_str_init_static_cstr

Deprecated:

Use cu_str_init_static_cstr.

#define cu_str_cct_uninit   cu_str_init_uninit

Deprecated:

#define cu_str_new_cstr_static   cu_str_new_static_cstr

Deprecated:

#define cu_str_onew_cstr_static   cu_str_onew_static_cstr

Deprecated:

---

Function Documentation

cu_bool_t cu_is_str

(

void *

s

)

True iff s is a cu_str_t.

Precondition:

s is a dynamically typed object.

void cu_str_append_char	(	cu_str_t	dest,
		char	ch
	)

Append a character to dest.

void cu_str_append_charr	(	cu_str_t	dest,
		char const *	s,
		size_t	n
	)

Append to dest the characters from s to s + n.

void cu_str_append_cstr	(	cu_str_t	dest,
		char const *	cstr
	)

Append the C string cstr to dest.

void cu_str_append_fmt	(	cu_str_t	dst,
		char const *	fmt,
			...
	)

Append a formatted string to dst.

void cu_str_append_str	(	cu_str_t	dest,
		cu_str_t	src
	)

Assign to dest the concatenation of itself with src.

void cu_str_append_vfmt	(	cu_str_t	dst,
		char const *	fmt,
		va_list	va
	)

Append a formatted string to dst.

void cu_str_assign	(	cu_str_t	dest,
		cu_str_t	src
	)

Assing src to dest. The capacity remains in src.

void cu_str_assign_substr	(	cu_str_t	dest,
		size_t	pos,
		size_t	len
	)

Assign to dest the substring of dest from pos to 'pos + len'.

char cu_str_at	(	cu_str_t	str,
		size_t	i
	)

The byte at position i in str.

Precondition:

0 ≤ i < cu_str_size(str)

char const* cu_str_charr

(

cu_str_t

str

)

Return the possibly not null-terminated array of character data of str.

void cu_str_chop_space

(

cu_str_t

str

)

Chop spaces from beginning and end of str. Currently only ASCII spaces are stripped.

size_t cu_str_chr	(	cu_str_t	str,
		char	ch
	)

Index of the first occurrence of ch in str or cu_str_index_none if not found.

size_t cu_str_chr_in_substr	(	cu_str_t	str,
		size_t	pos,
		size_t	len,
		char	ch
	)

Index of the first occurrence of ch in str in the range pos to pos + len, or cu_str_index_none if none.

int cu_str_cmp	(	cu_str_t	x,
		cu_str_t	y
	)

Return a zero if x and y are equal, otherwise return a negative or a positive number if x is, respectively, less than or greater than y according to some arbitrary ordering over strings. Use cu_str_coll for a specified ordering.

int cu_str_cmp_charr	(	cu_str_t	x,
		char const *	y_arr,
		size_t	y_size
	)

As cu_str_cmp, except with a character array RHS.

int cu_str_cmp_cstr	(	cu_str_t	x,
		char const *	y
	)

As cu_str_cmp, except with a C string RHS.

int cu_str_coll	(	cu_str_t	x,
		cu_str_t	y
	)

Return the result of strcoll on the C representations of x and y. XX This only works if LC_CTYPE refers to an UTF-8 locale.

int cu_str_coll_charr	(	cu_str_t	x,
		char const *	y_arr,
		size_t	y_size
	)

As cu_str_coll, except with a character array RHS.

int cu_str_coll_cstr	(	cu_str_t	x,
		char const *	y
	)

As cu_str_coll, except with a C string RHS.

cu_bool_t cu_str_eq	(	cu_str_t	x,
		cu_str_t	y
	)

True iff x and y are equal.

void cu_str_erase_substr	(	cu_str_t	dst,
		size_t	pos,
		size_t	len
	)

Erase chars pos to pos + len from dst.

cu_hash_t cu_str_hash

(

cu_str_t

x

)

A hash of x.

void cu_str_init

(

cu_str_t

dest

)

Construct an empty string. Can be used to create a string on the stack, in static memory or to inline a string in another struct.

void cu_str_init_static_cstr	(	cu_str_t	str,
		char const *	cstr
	)

Create a string from a statically stored C string.

void cu_str_init_uninit	(	cu_str_t	str,
		size_t	n
	)

Create a string of n uninitialised characters.

void cu_str_insert_substr	(	cu_str_t	dst,
		cu_str_t	src,
		size_t	pos
	)

Insert src into dst at 'pos.

cu_bool_t cu_str_is_empty

(

cu_str_t

str

)

True iff str is empty.

cu_str_t cu_str_new

(

void

)

Create an empty string with no capacity.

cu_str_t cu_str_new_2charr	(	char const *	s0,
		size_t	n0,
		char const *	s1,
		size_t	n1
	)

Return a string which is the concatenation of the substrings from s0 to s0 + n0 and from s1 to s1 + n1.

cu_str_t cu_str_new_2cstr	(	char const *	x,
		char const *	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_new_2str	(	cu_str_t	x,
		cu_str_t	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_new_3charr	(	char const *	s0,
		size_t	n0,
		char const *	s1,
		size_t	n1,
		char const *	s2,
		size_t	n2
	)

Return a string which is the concatenation of the substrings from s0 to s0 + n0, from s1 to s1 + n1, and from s2 to s2 + n2.

cu_str_t cu_str_new_charr	(	char const *	cstr,
		size_t	len
	)

Return a string containing the characters cstr to 'cstr + len'.

cu_str_t cu_str_new_copy

(

cu_str_t

str

)

Return a copy of str.

cu_str_t cu_str_new_cstr

(

char const *

cstr

)

Create a string from the C string (0-terminated) cstr.

cu_str_t cu_str_new_cstr_str	(	char const *	x,
		cu_str_t	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_new_fmt	(	char const *	fmt,
			...
	)

Create a string and format the contents as sprintf.

cu_str_t cu_str_new_idr

(

cu_idr_t

idr

)

Convert idr to a string.

cu_str_t cu_str_new_static_cstr

(

char const *

cstr

)

Create a string from a statically stored C string.

cu_str_t cu_str_new_str_char	(	cu_str_t	x,
		char	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_new_str_cstr	(	cu_str_t	x,
		char const *	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_new_uninit

(

size_t

n

)

Create a string of n uninitialised characters.

cu_str_t cu_str_new_vfmt	(	char const *	fmt,
		va_list	va
	)

Create a string and format the contents as vsprintf.

cu_bool_t cu_str_next_space_delimited	(	cu_str_t	str,
		size_t *	pos_io,
		size_t *	len_io
	)

Searches for the next white-space separated component of str, starting at *pos_io + *len_io. If there are only whitespace characters following this start position, returns false, else sets *pos_io to point to the first non-whitespace character, and *len_io to the number on non-whitespace characters, and returns true. Typical usage:

 size_t pos = 0;
 size_t len = 0;
 while (cu_str_next_space_delimited(str, &pos, &len))
     some_code(cu_str_substr(str, pos, len));

cu_str_t cu_str_onew

(

void

)

Create a dynamically typed empty string.

cu_str_t cu_str_onew_2charr	(	char const *	s0,
		size_t	n0,
		char const *	s1,
		size_t	n1
	)

Return a string which is the concatenation of the substrings from s0 to s0 + n0 and from s1 to s1 + n1.

cu_str_t cu_str_onew_2cstr	(	char const *	x,
		char const *	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_onew_2str	(	cu_str_t	x,
		cu_str_t	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_onew_3charr	(	char const *	s0,
		size_t	n0,
		char const *	s1,
		size_t	n1,
		char const *	s2,
		size_t	n2
	)

Return a string which is the concatenation of the substrings from s0 to s0 + n0, from s1 to s1 + n1, and from s2 to s2 + n2.

cu_str_t cu_str_onew_charr	(	char const *	cstr,
		size_t	len
	)

Return a string containing the characters cstr to 'cstr + len'.

cu_str_t cu_str_onew_copy

(

cu_str_t

str

)

Return a dynamically typed copy of str.

cu_str_t cu_str_onew_cstr

(

char const *

cstr

)

Create a string from the C string (0-terminated) cstr.

cu_str_t cu_str_onew_cstr_str	(	char const *	x,
		cu_str_t	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_onew_fmt	(	char const *	fmt,
			...
	)

Create a string and format the contents as sprintf.

cu_str_t cu_str_onew_idr

(

cu_idr_t

idr

)

Convert idr to a string.

cu_str_t cu_str_onew_static_cstr

(

char const *

cstr

)

Create a string from a statically stored C string.

cu_str_t cu_str_onew_str_char	(	cu_str_t	x,
		char	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_onew_str_cstr	(	cu_str_t	x,
		char const *	y
	)

Return a new string which is the concatenation of x and y. The returned string will use the capacity of x if sufficient.

cu_str_t cu_str_onew_uninit

(

size_t

n

)

Create a string of n uninitialised characters.

cu_str_t cu_str_onew_vfmt	(	char const *	fmt,
		va_list	va
	)

Create a string and format the contents as vsprintf.

cu_str_t cu_str_quote

(

cu_str_t

str

)

Return a quoted representation of str. This is a limited implementation as it only handles a few ASCII control characters. It uses the unual C format.

size_t cu_str_rchr	(	cu_str_t	str,
		char	ch
	)

Index of the last occurrence of ch in str or cu_str_index_none if not found.

size_t cu_str_rchr_in_substr	(	cu_str_t	str,
		size_t	pos,
		size_t	len,
		char	ch
	)

Index of the last occurrence of ch in str in the range pos to pos + len, or cu_str_index_none if none.

size_t cu_str_size

(

cu_str_t

str

)

The number of bytes contained in str.

cu_bool_t cu_str_subeq	(	cu_str_t	x,
		size_t	pos,
		cu_str_t	y
	)

True iff x has a substring y starting at pos.

cu_bool_t cu_str_subeq_charr	(	cu_str_t	x,
		size_t	pos,
		char const *	y_arr,
		size_t	y_size
	)

True iff x has a substring starting at pos which matches y_size characters from y_arr.

cu_bool_t cu_str_subeq_cstr	(	cu_str_t	x,
		size_t	pos,
		char const *	y
	)

True iff x has a substring y starting at pos.

cu_str_t cu_str_substr	(	cu_str_t	x,
		size_t	pos,
		size_t	len
	)

Return a new string which is the substring of x from pos to pos + len.

cu_str_t cu_str_suffix	(	cu_str_t	x,
		size_t	pos
	)

Return cu_str_substr(x, pos, cu_str_size(x) - pos).

char const* cu_str_to_cstr

(

cu_str_t

x

)

Return a null-terminated C string equal to x.

cu_idr_t cu_str_to_idr

(

cu_str_t

str

)

Convert to an identifier.

cuoo_type_t cu_str_type

(

)

The dynamic type of cu_str_t.

void cu_str_unappend	(	cu_str_t	str,
		size_t	char_count
	)

Drop char_count characters from the end of str.