sstr_t are objects that represent sequences of characters. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for sstr.h:

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

Classes
struct	sstr_s

Macros
#define	SHORT_STR_CAPACITY 25

#define	CAP_ADD_DELTA 256

#define	SSTR_TYPE_SHORT 0

#define	SSTR_TYPE_LONG 1

#define	SSTR_TYPE_REF 2

#define	sstr_length(s) ((struct sstr_s*)s)->length
	Return the length of s, in terms of bytes.

#define	sstr_append_cstr_if(dst, src, cond) sstr_append_of_if(dst, src, strlen(src), cond)
	Append C style string if cond is true, otherwise do nothing.

Typedefs
typedef void *	sstr_t
	sstr_t are objects that represent sequences of characters.

Functions
sstr_t	sstr_new (void)
	Create an empty sstr_t.

void	sstr_free (sstr_t s)
	delete a sstr_t.

sstr_t	sstr_of (const void *data, size_t length)
	Create a sstr_t from data with length bytes.

sstr_t	sstr_ref (const void *data, size_t length)
	Create a sstr_t from data with length bytes. The data is not copied, but have a pointer to data.

sstr_t	sstr (const char *cstr)
	Create a sstr_t from C-style (NULL-terminated) string str.

char *	sstr_cstr (sstr_t s)
	Return C-style string representation of s.

int	sstr_compare (sstr_t a, sstr_t b)
	Compare a and b return 0 if equal, <0 if a < b, >0 if a > b.

int	sstr_compare_c (sstr_t a, const char *b)
	compare sstr_t a and c-style string b

void	sstr_append_zero (sstr_t s, size_t length)
	Extends the sstr_t by appending additional '\0' characters at the end of its current value.

void	sstr_append_of (sstr_t s, const void *data, size_t length)
	Extends the sstr_t by appending additional characters in data with length of length at the end of its current value .

void	sstr_append (sstr_t dst, sstr_t src)
	Extends the sstr_t by appending additional characters contained in src.

void	sstr_append_cstr (sstr_t dst, const char *src)
	Extends the sstr_t by appending additional characters contained in src.

sstr_t	sstr_dup (sstr_t s)
	Duplicate s and return.

sstr_t	sstr_substr (sstr_t s, size_t index, size_t len)
	Get substring of s starting at index with length bytes.

void	sstr_clear (sstr_t s)
	clear the sstr_t. After this call, the sstr_t is empty.

sstr_t	sstr_vslprintf (const char *fmt, va_list args)
	Printf implement.

sstr_t	sstr_vslprintf_append (sstr_t buf, const char *fmt, va_list args)
	Same as sstr_vslprintf, but print to buf instead of create a new one.

sstr_t	sstr_printf (const char *fmt,...)
	printf implement.

sstr_t	sstr_printf_append (sstr_t buf, const char *fmt,...)
	Same as sstr_printf(), but but print to buf instead of create a new one.

void	sstr_append_of_if (sstr_t s, const void *data, size_t length, bool cond)
	Append if cond is true, otherwise do nothing.

int	sstr_json_escape_string_append (sstr_t out, sstr_t in)
	Escape a string for JSON output and append it to a buffer.

void	sstr_append_indent (sstr_t s, size_t indent)
	append spaces at the end of the sstr_t.

const char *	sstr_version (void)
	return version string.

Numeric conversion helpers
Convert between sstr_t and numeric types.
void	sstr_append_int_str (sstr_t s, int i)
	Append the decimal string representation of an int to a string.

int	sstr_parse_long (sstr_t s, long *v)
	Parse a string as a long integer.

int	sstr_parse_int (sstr_t s, int v)
	Parse a string as an int, consuming the parsed portion.

void	sstr_append_long_str (sstr_t s, long l)
	Append the decimal string representation of a long to a string.

void	sstr_append_uint32_str (sstr_t s, uint32_t u)
	Append the decimal string representation of a uint32_t to a string.

void	sstr_append_uint64_str (sstr_t s, uint64_t u)
	Append the decimal string representation of a uint64_t to a string.

void	sstr_append_float_str (sstr_t s, float f, int precission)
	Append the string representation of a float to a string.

void	sstr_append_double_str (sstr_t s, double f, int precision)
	Append the string representation of a double to a string.

int	sstr_parse_double (sstr_t s, double *v)
	Parse a string as a double.

Detailed Description

sstr_t are objects that represent sequences of characters.

The standard C style string is a sequence of characters terminated by a null character, which is easy to cause buffer overflow. And it's annoying to pass pointer and length of string to every whare.

The sequence of characters just like a string in C++, inside the sstr_t struct, it also has a null character at the end, so that we can use sstr_t as a C style string.

sstr_t contains a pointer to char sequence and its length, solves the security problems of standard C string. With functions bundle with sstr_t, you can easily manipulate the string just like standard C string, but in a safer way:

sstr_t stotal = sstr_new();
sstr_t s1 = sstr("hello");
sstr_t s2 = sstr("world");
sstr_append(stotal, s1);
sstr_append_of(stotal, " ", 1);
sstr_append(stotal, s2);
sstr_free(s1);
sstr_free(s2);

sstr_t result = sstr_printf("stotal=%S, c-str=%s, int=%d, long=%ld",
    stotal, stotal, 123, (long)456);

puts(sstr_cstr(result));

sstr_free(result);
sstr_free(stotal);

Macro Definition Documentation

◆ sstr_append_cstr_if

#define sstr_append_cstr_if	(	dst,
		src,
		cond
	)	sstr_append_of_if(dst, src, strlen(src), cond)

Append C style string if cond is true, otherwise do nothing.

Parameters

dst	destination sstr_t to append to.
src	source C-style string to append
cond	condition

◆ sstr_length

#define sstr_length ( s ) ((struct sstr_s*)s)->length

Return the length of s, in terms of bytes.

This is the number of actual bytes that conform the contents of the sstr_t, which is not necessarily equal to its storage capacity.

Note that sstr_t objects handle bytes without knowledge of the encoding that may eventually be used to encode the characters it contains. Therefore, the value returned may not correspond to the actual number of encoded characters in sequences of multi-byte or variable-length characters (such as UTF-8).

Parameters

s	sstr_t instance to get length of.

Returns: size_t The number of bytes of s.

Function Documentation

◆ sstr()

sstr_t sstr ( const char * cstr )

extern

Create a sstr_t from C-style (NULL-terminated) string str.

The cstr is copied to the new sstr_t, so you can free cstr after calling this function.

Parameters

cstr	C-style string to copy to the result sstr_t.

Returns: sstr_t containing data copied from cstr.

◆ sstr_append()

void sstr_append	(	sstr_t	dst,
		sstr_t	src
	)

extern

Extends the sstr_t by appending additional characters contained in src.

Parameters

dst	destination sstr_t.
src	source sstr_t.

◆ sstr_append_cstr()

void sstr_append_cstr	(	sstr_t	dst,
		const char *	src
	)

extern

Extends the sstr_t by appending additional characters contained in src.

Parameters

dst	destination sstr_t.
src	source C-style string.

◆ sstr_append_double_str()

void sstr_append_double_str	(	sstr_t	s,
		double	f,
		int	precision
	)

extern

Append the string representation of a double to a string.

Parameters

s	the sstr_t to append to.
f	the double value to convert and append.
precision	number of decimal places to output.

◆ sstr_append_float_str()

void sstr_append_float_str	(	sstr_t	s,
		float	f,
		int	precission
	)

extern

Append the string representation of a float to a string.

Parameters

s	the sstr_t to append to.
f	the float value to convert and append.
precission	number of decimal places to output.

◆ sstr_append_indent()

void sstr_append_indent	(	sstr_t	s,
		size_t	indent
	)

extern

append spaces at the end of the sstr_t.

Parameters

s	the sstr_t to append spaces to.
indent	numbers of spaces to append.

◆ sstr_append_int_str()

void sstr_append_int_str	(	sstr_t	s,
		int	i
	)

extern

Append the decimal string representation of an int to a string.

Parameters

s	the sstr_t to append to.
i	the integer value to convert and append.

◆ sstr_append_long_str()

void sstr_append_long_str	(	sstr_t	s,
		long	l
	)

extern

Append the decimal string representation of a long to a string.

Parameters

s	the sstr_t to append to.
l	the long value to convert and append.

◆ sstr_append_of()

void sstr_append_of	(	sstr_t	s,
		const void *	data,
		size_t	length
	)

extern

Extends the sstr_t by appending additional characters in data with length of length at the end of its current value .

Parameters

s	destination sstr_t.
data	data to append.
length	length of data.

◆ sstr_append_of_if()

void sstr_append_of_if	(	sstr_t	s,
		const void *	data,
		size_t	length,
		bool	cond
	)

extern

Append if cond is true, otherwise do nothing.

Parameters

s	the sstr_t to append to.
data	data to append.
length	length of data.
cond	condition

◆ sstr_append_uint32_str()

void sstr_append_uint32_str	(	sstr_t	s,
		uint32_t	u
	)

extern

Append the decimal string representation of a uint32_t to a string.

Parameters

s	the sstr_t to append to.
u	the uint32_t value to convert and append.

◆ sstr_append_uint64_str()

void sstr_append_uint64_str	(	sstr_t	s,
		uint64_t	u
	)

extern

Append the decimal string representation of a uint64_t to a string.

Parameters

s	the sstr_t to append to.
u	the uint64_t value to convert and append.

◆ sstr_append_zero()

void sstr_append_zero	(	sstr_t	s,
		size_t	length
	)

extern

Extends the sstr_t by appending additional '\0' characters at the end of its current value.

Parameters

s	destination sstr_t.
length	length of '\0' to append.

◆ sstr_clear()

void sstr_clear ( sstr_t s )

extern

clear the sstr_t. After this call, the sstr_t is empty.

Parameters

s	sstr_t instance to clear.

◆ sstr_compare()

int sstr_compare	(	sstr_t	a,
		sstr_t	b
	)

extern

Compare a and b return 0 if equal, <0 if a < b, >0 if a > b.

Parameters

a	sstr_t to be compared.
b	sstr_t to be compared to.

Returns: int the compare result.; 0 They compare equal.; <0 Either the value of the first character that does not match is lower in the compared string, or all compared characters match but the compared string is shorter.; >0 Either the value of the first character that does not match is greater in the compared string, or all compared characters match but the compared string is longer.

Note: This function is case sensitive.

◆ sstr_compare_c()

int sstr_compare_c	(	sstr_t	a,
		const char *	b
	)

extern

compare sstr_t a and c-style string b

just like sstr_compare, but compare a and c-style string b.

Returns: int

◆ sstr_cstr()

char * sstr_cstr ( sstr_t s )

extern

Return C-style string representation of s.

This function return a pointer to the internal C-style string, it has a null-terminal character at the end. So you can use it as a C-style string. The returned pointer is valid until sstr_free()/sstr_append()/sstr_append_of() or any functions that may modify the contents of sstr_t is called.

Parameters

s	sstr_t instance to convert to C-style string.

Returns: char* C-style string representation of s.

Note: The returned string is reused by s, do not free it yourself.

◆ sstr_dup()

sstr_t sstr_dup ( sstr_t s )

extern

Duplicate s and return.

Parameters

s	sstr_t to duplicate.

Returns: sstr_t duplicate of s.

◆ sstr_free()

void sstr_free ( sstr_t s )

extern

delete a sstr_t.

Parameters

s	sstr_t instance to delete.

◆ sstr_json_escape_string_append()

int sstr_json_escape_string_append	(	sstr_t	out,
		sstr_t	in
	)

extern

Escape a string for JSON output and append it to a buffer.

Converts special characters (\, ", newlines, tabs, etc.) to their JSON escape sequences and appends the result to out.

Parameters

out	the output sstr_t to append the escaped string to.
in	the input sstr_t containing the raw string to escape.

Returns: 0 on success, non-zero on error.

◆ sstr_new()

sstr_t sstr_new ( void )

extern

Create an empty sstr_t.

Returns: sstr_t

◆ sstr_of()

sstr_t sstr_of	(	const void *	data,
		size_t	length
	)

extern

Create a sstr_t from data with length bytes.

The data is copied to the new sstr_t, so you can free data after calling this function.

Parameters

data	data to copy to the result sstr_t.
length	length of data.

Returns: sstr_t containing data copied from data.

◆ sstr_parse_double()

int sstr_parse_double	(	sstr_t	s,
		double *	v
	)

extern

Parse a string as a double.

Parameters

s	the sstr_t to parse.
v	pointer to receive the parsed value.

Returns: 0 on success, non-zero on parse error.

◆ sstr_parse_int()

int sstr_parse_int	(	sstr_t *	s,
		int *	v
	)

extern

Parse a string as an int, consuming the parsed portion.

Parameters

s	pointer to the sstr_t to parse (advanced past consumed input).
v	pointer to receive the parsed value.

Returns: 0 on success, non-zero on parse error or overflow.

◆ sstr_parse_long()

int sstr_parse_long	(	sstr_t	s,
		long *	v
	)

extern

Parse a string as a long integer.

Parameters

s	the sstr_t to parse.
v	pointer to receive the parsed value.

Returns: 0 on success, non-zero on parse error or overflow.

◆ sstr_printf()

sstr_t sstr_printf	(	const char *	fmt,
			...
	)

extern

printf implement.

Parameters

fmt	format, like C printf()
...	arguments, like C printf()

Returns: sstr_t result string.

◆ sstr_printf_append()

sstr_t sstr_printf_append	(	sstr_t	buf,
		const char *	fmt,
			...
	)

extern

Same as sstr_printf(), but but print to buf instead of create a new one.

Parameters

buf	buffer to print to.
fmt	format string.
...	arguments.

Returns: sstr_t the result string.

◆ sstr_ref()

sstr_t sstr_ref	(	const void *	data,
		size_t	length
	)

extern

Create a sstr_t from data with length bytes. The data is not copied, but have a pointer to data.

Parameters

data	data of the result sstr_t.
length	length of data.

Returns: sstr_t

Note: The result sstr_t does not own data, but have a pointer to data. It is a reference, not a copy.; You cannot append a sstr_ref() result.

◆ sstr_substr()

sstr_t sstr_substr	(	sstr_t	s,
		size_t	index,
		size_t	len
	)

extern

Get substring of s starting at index with length bytes.

Parameters

s	sstr_t instance to get substring of.
index	index of the first byte of the substring.
len	number of bytes of the substring.

Returns: sstr_t substring of s. if index is out of range, return an empty string.

◆ sstr_version()

const char * sstr_version ( void )

extern

return version string.

Returns: const char* static version string.

◆ sstr_vslprintf()

sstr_t sstr_vslprintf	(	const char *	fmt,
		va_list	args
	)

extern

Printf implement.

supported formats:

%[0][width]T time_t
%[0][width][u][x|X]z ssize_t/size_t
%[0][width][u][x|X]d int/u_int
%[0][width][u][x|X]l long
%[0][width][u][x|X]D int32_t/uint32_t
%[0][width][u][x|X]L int64_t/uint64_t
%[0][width][.width]f double, max valid number fits to %18.15f
p void *
%[x|X]S sstr_t, if x, print as hexadecimal
s null-terminated string
%*s length and string
Z '\0'
N '
'
c char
%% %

reserved:

C wchar

if u/x/X, tailing d can be ignore

◆ sstr_vslprintf_append()

sstr_t sstr_vslprintf_append	(	sstr_t	buf,
		const char *	fmt,
		va_list	args
	)

extern

Same as sstr_vslprintf, but print to buf instead of create a new one.

Parameters

buf	result sstr_t to print to.
fmt	format string.
args	arguments.

Returns: sstr_t the result string.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ sstr_append_cstr_if

◆ sstr_length

Function Documentation

◆ sstr()

◆ sstr_append()

◆ sstr_append_cstr()

◆ sstr_append_double_str()

◆ sstr_append_float_str()

◆ sstr_append_indent()

◆ sstr_append_int_str()

◆ sstr_append_long_str()

◆ sstr_append_of()

◆ sstr_append_of_if()

◆ sstr_append_uint32_str()

◆ sstr_append_uint64_str()

◆ sstr_append_zero()

◆ sstr_clear()

◆ sstr_compare()

◆ sstr_compare_c()

◆ sstr_cstr()

◆ sstr_dup()

◆ sstr_free()

◆ sstr_json_escape_string_append()

◆ sstr_new()

◆ sstr_of()

◆ sstr_parse_double()

◆ sstr_parse_int()

◆ sstr_parse_long()

◆ sstr_printf()

◆ sstr_printf_append()

◆ sstr_ref()

◆ sstr_substr()

◆ sstr_version()

◆ sstr_vslprintf()

◆ sstr_vslprintf_append()