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

#include <stdarg.h>
#include <stddef.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. More...

#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. More...

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

Functions
sstr_t	sstr_new ()
	Create an empty sstr_t. More...

void	sstr_free (sstr_t s)
	delete a sstr_t. More...

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

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. More...

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

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

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. More...

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

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. More...

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 . More...

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

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

sstr_t	sstr_dup (sstr_t s)
	Duplicate s and return. More...

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

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

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

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. More...

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

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. More...

void	sstr_append_int_str (sstr_t s, int i)
	convert sstr <-> int,long,float,double

int	sstr_parse_long (sstr_t s, long *v)

int	sstr_parse_int (sstr_t s, int v)

void	sstr_append_long_str (sstr_t s, long l)

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

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

int	sstr_parse_double (sstr_t s, double *v)

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

int	sstr_json_escape_string_append (sstr_t out, sstr_t in)

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

const char *	sstr_version ()
	return version string. More...

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 )

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
	)

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
	)

Extends the sstr_t by appending additional characters contained in src.

Parameters

dst	destination sstr_t.
src	source C-style string.

◆ sstr_append_indent()

void sstr_append_indent	(	sstr_t	s,
		size_t	indent
	)

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_of()

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 .

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,
		int	cond
	)

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_zero()

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.

Parameters

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

◆ sstr_clear()

void sstr_clear ( sstr_t s )

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
	)

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
	)

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 )

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 )

Duplicate s and return.

Parameters

s	sstr_t to duplicate.

Returns: sstr_t duplicate of s.

◆ sstr_free()

void sstr_free ( sstr_t s )

delete a sstr_t.

Parameters

s	sstr_t instance to delete.

◆ sstr_new()

sstr_t sstr_new ( )

Create an empty sstr_t.

Returns: sstr_t

◆ sstr_of()

sstr_t sstr_of	(	const void *	data,
		size_t	length
	)

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_printf()

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

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,
			...
	)

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
	)

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
	)

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 ( )

return version string.

Returns: const char* static version string.

◆ sstr_vslprintf()

sstr_t sstr_vslprintf	(	const char *	fmt,
		va_list	args
	)

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
	)

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_indent()

◆ sstr_append_of()

◆ sstr_append_of_if()

◆ sstr_append_zero()

◆ sstr_clear()

◆ sstr_compare()

◆ sstr_compare_c()

◆ sstr_cstr()

◆ sstr_dup()

◆ sstr_free()

◆ sstr_new()

◆ sstr_of()

◆ sstr_printf()

◆ sstr_printf_append()

◆ sstr_ref()

◆ sstr_substr()

◆ sstr_version()

◆ sstr_vslprintf()

◆ sstr_vslprintf_append()