string.h File Reference

Sized string helpers. More...

#include <clod/lib.h>
#include <stdarg.h>

Go to the source code of this file.

Classes
struct	clod_string

Macros
#define	CLOD_STRING_NULL   ((struct clod_string){0})
	Null string.
#define	CLOD_STRING_C(cstr)
	String literal constant.
#define	CLOD_STRING_NEW(size)
	Create a new empty string with the given capacity on the stack.
#define	CLOD_STRING_OBJECT(object)
	Get the string representation of an object.

Functions
struct clod_string	clod_string_from_cstr (const char *cstr)
	Make a string from a C string.
size_t	clod_string_cat (struct clod_string *dst, struct clod_string src)
size_t	clod_string_insert (struct clod_string *dst, struct clod_string src)
int	clod_string_cmp (struct clod_string str1, struct clod_string str2)
void	clod_string_put_char (struct clod_string *str, char c)
	Append a single char to the end of the string.
char	clod_string_get_char (struct clod_string *str)
	Remove a single char from the start of the string.
char	clod_string_peek_char (struct clod_string str)
	Get the first char in the string.
CLOD_API int	clod_string_parse (struct clod_string src, struct clod_string fmt,...)
CLOD_API int	clod_string_vparse (struct clod_string src, struct clod_string fmt, va_list args)
	Same as clod_string_parse but takes a va-list argument instead of '...'.
CLOD_API struct clod_string	clod_string_contains (struct clod_string str, struct clod_string elem)
CLOD_API struct clod_string	clod_string_find (struct clod_string str, char elem, int occurrence)
CLOD_API bool	clod_string_remove_prefix (struct clod_string *str, struct clod_string prefix)
CLOD_API size_t	clod_string_put_int (struct clod_string *dst, intmax_t val, struct clod_string alphabet, unsigned char base, unsigned char min_digits, unsigned char max_digits)
CLOD_API intmax_t	clod_string_get_int (struct clod_string *str, struct clod_string alphabet, unsigned char base)
CLOD_API size_t	clod_string_put_uint (struct clod_string *dst, uintmax_t val, struct clod_string alphabet, unsigned char base, unsigned char min_digits, unsigned char max_digits)
CLOD_API uintmax_t	clod_string_get_uint (struct clod_string *str, struct clod_string alphabet, unsigned char base)
CLOD_API size_t	clod_string_put_double (struct clod_string *dst, double val, struct clod_string alphabet, unsigned char base, unsigned char min_digits, unsigned char max_digits)
CLOD_API double	clod_string_get_double (struct clod_string *str, struct clod_string alphabet, unsigned char base)

Detailed Description

Sized string helpers.

A definition of a sized string and a few simple methods for dealing with them. It's C-centric and mostly serves as a helper for some C-centric public libclod methods.

The general approach here is that methods operate on a particular input clod_string, and return that same string but with the length field updated to reflect the result of the operation. Some methods may make other changes, but no memory allocation is ever performed.

Definition in file string.h.

Macro Definition Documentation

CLOD_STRING_NULL

#define CLOD_STRING_NULL   ((struct clod_string){0})

Null string.

Definition at line 40 of file string.h.

CLOD_STRING_C

#define CLOD_STRING_C

(

cstr

)

Value:

((struct clod_string){ .ptr = (char*)(cstr), .len = sizeof((char[]){cstr}) - 1, .cap = 0 })

String literal constant.

Definition at line 43 of file string.h.

CLOD_STRING_NEW

#define CLOD_STRING_NEW

(

size

)

Value:

((struct clod_string){ .ptr = (char[size]){0}, .len = 0, .cap = (size) })

Create a new empty string with the given capacity on the stack.

Definition at line 46 of file string.h.

CLOD_STRING_OBJECT

#define CLOD_STRING_OBJECT

(

object

)

Value:

((struct clod_string){ .ptr = (char*)(object), .len = sizeof(*(object)), .cap = sizeof(*(object)) })

Get the string representation of an object.

Definition at line 49 of file string.h.

Function Documentation

clod_string_from_cstr()

struct clod_string clod_string_from_cstr

(

const char *

cstr

)

Make a string from a C string.

Definition at line 5 of file string.c.

clod_string_cat()

size_t clod_string_cat	(	struct clod_string *	dst,
		struct clod_string	src )

Append a string to another string. The active region in dst is grown to include the appended data.

Parameters

[in,out]	dst	String to append to.
[in]	src	String to be appended.

Returns

Number of bytes written.

Definition at line 17 of file string.c.

clod_string_insert()

size_t clod_string_insert	(	struct clod_string *	dst,
		struct clod_string	src )

Insert a string at the beginning of another string.

Parameters

[in,out]	dst	String to prepend to.
[in]	src	String to prepend.

Returns

Number of bytes written.

Definition at line 44 of file string.c.

clod_string_cmp()

int clod_string_cmp	(	struct clod_string	str1,
		struct clod_string	str2 )

Compare two strings. If str1 > str2 it returns 1, if str1 == str2 it returns 0, and if str1 < str2 it returns -1;

Strings are first compared by their length, longer is larger. Then they are compared bytewise, returning on the first non-equal comparison. Otherwise, they are considered equal and 0 is returned.

Parameters

[in]	str1	1st string.
[in]	str2	2nd string.

Returns

The result of str1 - str2.

Definition at line 75 of file string.c.

clod_string_put_char()

void clod_string_put_char	(	struct clod_string *	str,
		char	c )

Append a single char to the end of the string.

Definition at line 87 of file string.c.

clod_string_get_char()

char clod_string_get_char

(

struct clod_string *

str

)

Remove a single char from the start of the string.

Definition at line 93 of file string.c.

clod_string_peek_char()

char clod_string_peek_char

(

struct clod_string

str

)

Get the first char in the string.

Definition at line 103 of file string.c.

clod_string_parse()

CLOD_API int clod_string_parse	(	struct clod_string	src,
		struct clod_string	fmt,
			... )

Format a string similarly to snprintf. The format specification differs from the standard library in a few ways.

%[flags][width][.precision]<type>

• Flags Options for changing formatting.
• Width the minimum size of the number as formatted.
• Precision the maximum size of the number as formatted.
• Type the type of the value passed as argument.

Flag	Description
0	Pad with zeroes instead of spaces.
X	Base 16, uppercase.
x	Base 16, lowercase.
o	Base 8
b	Base 2

Type	Specifier
int	i
unsigned int	u
long	l
unsigned long	ul
long long	ll
unsigned long long	ull
int32_t	i32
uint32_t	u32
int64_t	i64
uint64_t	u64
size_t	size
ptrdiff_t	ptrdiff
void *	ptr
double	d
struct clod_string *	str
C string	s

Parameters

[in]	dst	Where the formatted string is written to.
[in]	fmt	Format.
[in]	...	Values to format.

Returns

The number of characters that have been, or would have been, written to dst. */ CLOD_API size_t clod_string_format(struct clod_string *dst, struct clod_string fmt, ...);

/ Same as clod_string_format, but takes a va_list argument instead of '...'. CLOD_API size_t clod_string_vformat(struct clod_string *dst, struct clod_string fmt, va_list args);

/** Parses values in a string into the provided arguments. Attempts to be as close to a reverse of clod_string_format as possible.

Parameters

[in]	src	Source string to parse.
[in]	fmt	Format.
[in]	...	Pointers to the types specified in fmt.

Returns

Number of parameters parsed.

clod_string_contains()

CLOD_API struct clod_string clod_string_contains	(	struct clod_string	str,
		struct clod_string	elem )

Find the first instance of a string inside another string.

Parameters

[in]	str	The string to search in.
[in]	elem	String to search for.

Returns

String pointing to the same object str points to at the offset where elem was found and with a size equal to elem's size. If no match was found, it returns null.

Definition at line 123 of file string.c.

clod_string_find()

CLOD_API struct clod_string clod_string_find	(	struct clod_string	str,
		char	elem,
		int	occurrence )

Find the Nth instance of elem in str. When occurrence is positive or negative, it searches from the start or end of str respectively. Then, abs(occurrence) - 1 instances of elem are skipped, and a string pointing to the final instance returned.

Parameters

[in]	str	The string to search in.
[in]	elem	The character to search for.
[in]	occurrence	Which instance of elem to search for.

Returns

String pointing to the found instance of elem, and a length including the rest of str. If occurrence is 0, str is returned.

Definition at line 147 of file string.c.

clod_string_remove_prefix()

CLOD_API bool clod_string_remove_prefix	(	struct clod_string *	str,
		struct clod_string	prefix )

Check if a string has a given prefix, moving the string up to the remaining string following the prefix, if found.

Parameters

[in,out]	str	String to check for and remove prefix from.
[in]	prefix	Prefix to check for.

Returns

True if str had the given prefix.

Definition at line 109 of file string.c.

clod_string_put_int()

CLOD_API size_t clod_string_put_int	(	struct clod_string *	dst,
		intmax_t	val,
		struct clod_string	alphabet,
		unsigned char	base,
		unsigned char	min_digits,
		unsigned char	max_digits )

Writes an integer value to the string. The value is truncated if the destination is not large enough.

Returns

The number of characters that have been, or would have been written to dst.

Definition at line 16 of file serialise.c.

clod_string_get_int()

CLOD_API intmax_t clod_string_get_int	(	struct clod_string *	str,
		struct clod_string	alphabet,
		unsigned char	base )

Consumes an integer value in the string with the given base. If no value could be decoded, the string is not incremented.

Definition at line 31 of file serialise.c.

clod_string_put_uint()

CLOD_API size_t clod_string_put_uint	(	struct clod_string *	dst,
		uintmax_t	val,
		struct clod_string	alphabet,
		unsigned char	base,
		unsigned char	min_digits,
		unsigned char	max_digits )

Writes an unsigned integer value to the string. The value is truncated if the destination is not large enough.

Returns

The number of characters that have been, or would have been written to dst.

Definition at line 50 of file serialise.c.

clod_string_get_uint()

CLOD_API uintmax_t clod_string_get_uint	(	struct clod_string *	str,
		struct clod_string	alphabet,
		unsigned char	base )

Consumes an unsigned integer value in the string with the given base. If no value could be decoded, the string is not incremented.

Definition at line 70 of file serialise.c.

clod_string_put_double()

CLOD_API size_t clod_string_put_double	(	struct clod_string *	dst,
		double	val,
		struct clod_string	alphabet,
		unsigned char	base,
		unsigned char	min_digits,
		unsigned char	max_digits )

Writes a double value to the string. The value is truncated if the destination is not large enough.

Returns

The number of characters that have been, or would have been written to dst.

Definition at line 168 of file string.c.

clod_string_get_double()

CLOD_API double clod_string_get_double	(	struct clod_string *	str,
		struct clod_string	alphabet,
		unsigned char	base )

Consumes a double value in the string with the given base. If no value could be decoded, the string is not incremented.

Definition at line 174 of file string.c.