sstring.h File Reference

sstring.h interface. More...

#include <string.h>
#include <stdlib.h>
#include <stdbool.h>
#include <cwist/err/cwist_err.h>

Include dependency graph for sstring.h:

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

Go to the source code of this file.

Classes
struct	cwist_sstring

Typedefs
typedef struct cwist_sstring	cwist_sstring

Enumerations
enum	cwist_sstring_error_t {   ERR_SSTRING_OKAY , ERR_SSTRING_ZERO_LENGTH , ERR_SSTRING_NULL_STRING , ERR_SSTRING_CONSTANT ,   ERR_SSTRING_RESIZE_TOO_SMALL , ERR_SSTRING_RESIZE_TOO_LARGE , ERR_SSTRING_OUTOFBOUND }

Functions
cwist_sstring *	cwist_sstring_create (void)
	Allocate and initialize a new heap-owned CWIST string object.
void	cwist_sstring_destroy (cwist_sstring *str)
	Destroy a heap-owned CWIST string and its backing buffer.
String manipulation API
cwist_error_t	cwist_sstring_append_len (cwist_sstring *str, const char *data, size_t len)
	Append raw bytes with length.
cwist_error_t	cwist_sstring_assign_len (cwist_sstring *str, const char *data, size_t len)
	Assign raw bytes with length.
cwist_error_t	cwist_sstring_borrow (cwist_sstring *str, const char *data, size_t len)
	Borrow an external buffer without copying; detached to heap on first mutation.
cwist_error_t	cwist_sstring_adopt_len (cwist_sstring *str, char *buf, size_t len)
	Adopt a cwist_alloc'd heap buffer, taking ownership without copying.
cwist_error_t	cwist_sstring_adopt_region (cwist_sstring *str, char *base, size_t offset, size_t len)
	Adopt a cwist_alloc'd heap buffer as a region view without copying.
cwist_error_t	cwist_sstring_init (cwist_sstring *str)
	Initialize an sstring.
cwist_error_t	cwist_sstring_ltrim (cwist_sstring *str)
	Left-trim whitespace.
cwist_error_t	cwist_sstring_rtrim (cwist_sstring *str)
	Right-trim whitespace.
cwist_error_t	cwist_sstring_trim (cwist_sstring *str)
	Trim whitespace from both ends.
cwist_error_t	cwist_sstring_change_size (cwist_sstring *str, size_t size, bool blow_data)
	Change the internal buffer size.
cwist_error_t	cwist_sstring_assign (cwist_sstring *str, const char *data)
	Assign a C string.
cwist_error_t	cwist_sstring_append (cwist_sstring *str, const char *data)
	Append a C string.
cwist_error_t	cwist_sstring_append_sstring (cwist_sstring *str, const cwist_sstring *from)
	Append another sstring.
cwist_error_t	cwist_sstring_seek (cwist_sstring *str, char *substr, int location)
	Seek a substring at a location.
cwist_error_t	cwist_sstring_copy (cwist_sstring *origin, char *destination)
	Copy to a C string buffer.
cwist_error_t	cwist_sstring_copy_sstring (cwist_sstring *origin, const cwist_sstring *from)
	Copy from another sstring.
int	cwist_sstring_compare (cwist_sstring *str, const char *compare_to)
	Compare with a C string.
int	cwist_sstring_compare_sstring (cwist_sstring *left, const cwist_sstring *right)
	Compare two sstrings.
size_t	cwist_sstring_get_size (cwist_sstring *str)
	Get the current size.
cwist_sstring *	cwist_sstring_substr (cwist_sstring *str, int start, int length)
	Extract a substring.

Detailed Description

sstring.h interface.

Definition in file sstring.h.

Typedef Documentation

cwist_sstring

typedef struct cwist_sstring cwist_sstring

Enumeration Type Documentation

cwist_sstring_error_t

enum cwist_sstring_error_t

Enumerator
ERR_SSTRING_OKAY
ERR_SSTRING_ZERO_LENGTH
ERR_SSTRING_NULL_STRING
ERR_SSTRING_CONSTANT
ERR_SSTRING_RESIZE_TOO_SMALL
ERR_SSTRING_RESIZE_TOO_LARGE
ERR_SSTRING_OUTOFBOUND

Definition at line 156 of file sstring.h.

Function Documentation

cwist_sstring_adopt_len()

cwist_error_t cwist_sstring_adopt_len	(	cwist_sstring *	str,
		char *	buf,
		size_t	len
	)

Adopt a cwist_alloc'd heap buffer, taking ownership without copying.

Adopt a cwist_alloc'd heap buffer, taking ownership without copying.

Adopt a heap buffer, taking ownership without copying.

Parameters

str	Target string object; any owned buffer it holds is released.
buf	cwist_alloc'd buffer with room for a NUL at buf[len]; ownership transfers to the string (freed on destroy/reassign). NULL clears.
len	Payload length in bytes.

Returns

ERR_SSTRING_OKAY on success, or ERR_SSTRING_NULL_STRING for NULL input.

< adopted buffer size is unknown beyond len + NUL

Definition at line 151 of file sstring.c.

cwist_sstring_adopt_region()

cwist_error_t cwist_sstring_adopt_region	(	cwist_sstring *	str,
		char *	base,
		size_t	offset,
		size_t	len
	)

Adopt a cwist_alloc'd heap buffer as a region view without copying.

Parameters

str	Target string object; any owned buffer it holds is released.
base	Allocation base (cwist_alloc'd); ownership transfers to the string.
offset	Payload start relative to base.
len	Payload length in bytes.

Note

base must have room for a NUL at base[offset + len]. Growth reallocs base and preserves the offset.

Adopt a cwist_alloc'd heap buffer as a region view without copying.

Parameters

str	Target string object; any owned buffer it holds is released.
base	cwist_alloc'd allocation base; ownership transfers to the string (freed on destroy/reassign). NULL clears.
offset	Payload start relative to base.
len	Payload length in bytes; base[offset + len] must be the NUL slot.

Returns

ERR_SSTRING_OKAY on success, or ERR_SSTRING_NULL_STRING for NULL input.

Note

Growth reallocs base and preserves the offset, so data keeps viewing the same region.

< adopted region size is unknown beyond len + NUL

Definition at line 183 of file sstring.c.

cwist_sstring_append()

cwist_error_t cwist_sstring_append	(	cwist_sstring *	str,
		const char *	data
	)

Append a C string.

Append a C string.

Parameters

str	Target string object.
data	Source string to append.

Returns

ERR_SSTRING_OKAY on success, or an error payload describing the failure.

Definition at line 559 of file sstring.c.

Referenced by cwist_sstring_append(), and cwist_sstring_append_sstring().

cwist_sstring_append_len()

cwist_error_t cwist_sstring_append_len	(	cwist_sstring *	str,
		const char *	data,
		size_t	len
	)

Append raw bytes with length.

Append raw bytes with length.

Parameters

str	Target string object.
data	Source bytes to append.
len	Number of source bytes to append.

Returns

ERR_SSTRING_OKAY on success, or an error payload describing the failure.

Definition at line 212 of file sstring.c.

cwist_sstring_append_sstring()

cwist_error_t cwist_sstring_append_sstring	(	cwist_sstring *	str,
		const cwist_sstring *	from
	)

Append another sstring.

Append another sstring.

Append the contents of one CWIST string onto another.

Parameters

str	Destination string.
from	Source CWIST string.

Returns

ERR_SSTRING_OKAY on success, or an error describing invalid input.

Definition at line 700 of file sstring.c.

Referenced by cwist_sstring_create(), and cwist_sstring_init().

cwist_sstring_assign()

cwist_error_t cwist_sstring_assign	(	cwist_sstring *	str,
		const char *	data
	)

Assign a C string.

Assign a C string.

Parameters

str	Target string object.
data	Source string, or NULL to clear the value.

Returns

ERR_SSTRING_OKAY on success, or an error payload describing the failure.

Definition at line 504 of file sstring.c.

Referenced by cwist_sstring_assign(), and cwist_sstring_copy_sstring().

cwist_sstring_assign_len()

cwist_error_t cwist_sstring_assign_len	(	cwist_sstring *	str,
		const char *	data,
		size_t	len
	)

Assign raw bytes with length.

Assign raw bytes with length.

Parameters

str	Target string object.
data	Source bytes to copy.
len	Number of source bytes to copy.

Returns

ERR_SSTRING_OKAY on success, or an error payload describing the failure.

Definition at line 88 of file sstring.c.

cwist_sstring_borrow()

cwist_error_t cwist_sstring_borrow	(	cwist_sstring *	str,
		const char *	data,
		size_t	len
	)

Borrow an external buffer without copying; detached to heap on first mutation.

Borrow an external buffer without copying; detached to heap on first mutation.

Borrow an external buffer without copying.

Parameters

str	Target string object; any owned buffer it holds is released.
data	Borrowed bytes; must outlive the string (literal, arena chunk, ...).
len	Length of the borrowed bytes.

Returns

ERR_SSTRING_OKAY on success, or ERR_SSTRING_NULL_STRING for NULL input.

Note

The first mutating call detaches the contents into owned heap storage, so the borrowed source is never written through.

< borrowed capacity is unknown until detach

Definition at line 122 of file sstring.c.

cwist_sstring_change_size()

cwist_error_t cwist_sstring_change_size	(	cwist_sstring *	str,
		size_t	new_size,
		bool	blow_data
	)

Change the internal buffer size.

Change the internal buffer size.

Parameters

str	String object to resize.
new_size	Requested new size in bytes.
blow_data	When true, allow shrinking below the current content length.

Returns

ERR_SSTRING_OKAY on success, or an error describing the resize failure.

Definition at line 417 of file sstring.c.

Referenced by cwist_sstring_assign().

cwist_sstring_compare()

int cwist_sstring_compare	(	cwist_sstring *	str,
		const char *	compare_to
	)

Compare with a C string.

Compare with a C string.

Parameters

str	Left-hand CWIST string.
compare_to	Right-hand raw C string.

Returns

Negative, zero, or positive depending on lexical ordering.

Definition at line 852 of file sstring.c.

cwist_sstring_compare_sstring()

int cwist_sstring_compare_sstring	(	cwist_sstring *	left,
		const cwist_sstring *	right
	)

Compare two sstrings.

Compare two sstrings.

Compare two CWIST string objects using strcmp semantics.

Parameters

left	Left-hand string.
right	Right-hand string.

Returns

Negative, zero, or positive depending on lexical ordering.

Definition at line 320 of file sstring.c.

Referenced by cwist_sstring_create(), cwist_sstring_init(), and cwist_sstring_init_escaped().

cwist_sstring_copy()

cwist_error_t cwist_sstring_copy	(	cwist_sstring *	origin,
		char *	destination
	)

Copy to a C string buffer.

Copy to a C string buffer.

Parameters

origin	Source string object.
destination	Destination C buffer.

Returns

ERR_SSTRING_OKAY on success, or an error describing invalid input.

Definition at line 766 of file sstring.c.

cwist_sstring_copy_sstring()

cwist_error_t cwist_sstring_copy_sstring	(	cwist_sstring *	origin,
		const cwist_sstring *	from
	)

Copy from another sstring.

Copy from another sstring.

Copy one CWIST string into another.

Parameters

origin	Destination string object.
from	Source string object, or NULL to clear the destination.

Returns

ERR_SSTRING_OKAY on success, or an error describing invalid input.

Definition at line 786 of file sstring.c.

Referenced by cwist_sstring_create(), cwist_sstring_init(), and cwist_sstring_init_escaped().

cwist_sstring_create()

cwist_sstring * cwist_sstring_create

(

void

)

Allocate and initialize a new heap-owned CWIST string object.

Create a new sstring instance.

Returns

Newly allocated string object, or NULL on allocation failure.

Definition at line 802 of file sstring.c.

Referenced by cwist_sstring_substr().

cwist_sstring_destroy()

void cwist_sstring_destroy

(

cwist_sstring *

str

)

Destroy a heap-owned CWIST string and its backing buffer.

Destroy an sstring instance.

Parameters

str	String object to destroy.

Definition at line 823 of file sstring.c.

Referenced by cwist_sstring_substr().

cwist_sstring_get_size()

size_t cwist_sstring_get_size

(

cwist_sstring *

str

)

Get the current size.

Get the current size.

Return the cached string size in bytes.

Parameters

str	String object to inspect.

Returns

Stored size, or 0 when the string is NULL.

Definition at line 306 of file sstring.c.

Referenced by cwist_sstring_create(), cwist_sstring_init(), and cwist_sstring_init_escaped().

cwist_sstring_init()

cwist_error_t cwist_sstring_init

(

cwist_sstring *

str

)

Initialize an sstring.

Initialize an sstring.

Parameters

str	String object to initialize in caller-owned storage.

Returns

ERR_SSTRING_OKAY on success, or ERR_SSTRING_NULL_STRING for NULL input.

Definition at line 250 of file sstring.c.

cwist_sstring_ltrim()

cwist_error_t cwist_sstring_ltrim

(

cwist_sstring *

str

)

Left-trim whitespace.

Left-trim whitespace.

Parameters

str	String object to mutate.

Returns

ERR_SSTRING_OKAY on success, or ERR_SSTRING_NULL_STRING for invalid input.

Definition at line 329 of file sstring.c.

Referenced by cwist_sstring_trim().

cwist_sstring_rtrim()

cwist_error_t cwist_sstring_rtrim

(

cwist_sstring *

str

)

Right-trim whitespace.

Right-trim whitespace.

Parameters

str	String object to mutate.

Returns

ERR_SSTRING_OKAY on success, or an error describing invalid input.

Definition at line 365 of file sstring.c.

Referenced by cwist_sstring_trim().

cwist_sstring_seek()

cwist_error_t cwist_sstring_seek	(	cwist_sstring *	str,
		char *	substr,
		int	location
	)

Seek a substring at a location.

Seek a substring at a location.

Parameters

str	Source string object.
substr	Destination C buffer.
location	Starting offset inside the source string.

Returns

ERR_SSTRING_OKAY on success, or an error describing invalid bounds/input.

Definition at line 741 of file sstring.c.

cwist_sstring_substr()

cwist_sstring * cwist_sstring_substr	(	cwist_sstring *	str,
		int	start,
		int	length
	)

Extract a substring.

Extract a substring.

Parameters

str	Source string object.
start	Zero-based starting index.
length	Requested substring length.

Returns

Newly allocated substring, or NULL when the range is invalid or OOM occurs.

Definition at line 863 of file sstring.c.

cwist_sstring_trim()

cwist_error_t cwist_sstring_trim

(

cwist_sstring *

str

)

Trim whitespace from both ends.

Trim whitespace from both ends.

Parameters

str	String object to mutate.

Returns

ERR_SSTRING_OKAY on success, or the first trim error encountered.

Definition at line 404 of file sstring.c.