dynstring.h File Reference

#include "../headers/attributes.h"
#include <stdarg.h>
#include <stddef.h>
#include <sys/types.h>

Go to the source code of this file.

Typedefs
typedef struct dynamic_string	DynString

Functions
Constructor DynString *	dynstr_init (void)
Constructor DynString *	dynstr_init_cap (size_t cap)
Constructor DynString *	dynstr_init_as (const char *)
void	dynstr_destroy (DynString *)
ssize_t	dynstr_append (DynString *, const char *app)
ssize_t	dynstr_appendn (DynString *, const char *app, size_t len)
PrintfLike ssize_t	dynstr_appendf (DynString *, const char *fmt,...)
ssize_t	dynstr_vappendf (DynString *, const char *fmt, va_list vargs)
ssize_t	dynstr_prepend (DynString *, const char *)
ssize_t	dynstr_prependn (DynString *, const char *s, size_t len)
PrintfLike ssize_t	dynstr_prependf (DynString *, const char *fmt,...)
ssize_t	dynstr_vprependf (DynString *, const char *fmt, va_list vargs)
int	dynstr_slice (DynString *, size_t start_idx, ssize_t end_idx)
int	dynstr_slice_e (DynString *, ssize_t end_idx)
int	dynstr_slice_s (DynString *, size_t start_idx)
int	dynstr_reset (DynString *)
int	dynstr_set (DynString *, const char *string)
int	dynstr_set_at (DynString *dynstr, size_t idx, char c)
UseResult char *	dynstr_data_copy (const DynString *)
const char *	dynstr_data (const DynString *)
size_t	dynstr_len (const DynString *)

Typedef Documentation

DynString

typedef struct dynamic_string DynString

Function Documentation

dynstr_append()

ssize_t dynstr_append	(	DynString *	,
		const char *	app )

Appends a string to the end of the DynString.

app may not be NULL

Returns

RV_ERROR on allocation error, else the number of appended chars

dynstr_appendf()

PrintfLike ssize_t dynstr_appendf	(	DynString *	,
		const char *	fmt,
			... )

Appends a formatted string to the end of a DynString

Returns

RV_ERROR on allocation error, else the number of appended chars

dynstr_appendn()

ssize_t dynstr_appendn	(	DynString *	,
		const char *	app,
		size_t	len )

Appends at most len characters to the end of the DynString

app may not be NULL

Parameters

app	appended string
len	maximum number of chars appended

Returns

RV_ERROR on allocation error, else the number of appended chars (should be len)

dynstr_data()

const char * dynstr_data

(

const DynString *

)

Returns a const view of the string.

Returns

a pointer of the DynStrings data

dynstr_data_copy()

UseResult char * dynstr_data_copy

(

const DynString *

)

Allocates a new string with the DynString contents

Returns

pointer to heap-allocated data

dynstr_destroy()

void dynstr_destroy

(

DynString *

)

Frees all memory owned by the DynString

dynstr_init()

Constructor DynString * dynstr_init

(

void

)

Heap allocates a new DynString with a capacity of DEFAULT_DYNSTRING_CAP

Returns

a new DynString or NULL if allocation fails

dynstr_init_as()

Constructor DynString * dynstr_init_as

(

const char *

)

Heap allocates a new DynString with the data set to the supplied string. Capacity is set to the strings length including the terminating zero (\0)

Returns

a new DynString or NULL if allocation fails

dynstr_init_cap()

Constructor DynString * dynstr_init_cap

(

size_t

cap

)

Heap allocates a new DynString with a capacity of cap

Parameters

cap	capacity of the DynString

Returns

a new DynString or NULL if allocation fails

dynstr_len()

size_t dynstr_len

(

const DynString *

)

Fetches the length of the string in constant time

Returns

length of the string

dynstr_prepend()

ssize_t dynstr_prepend	(	DynString *	,
		const char *	)

Adds a string to the start of the DynString

Returns

RV_ERROR on allocation error, else the number of pre-pended chars

dynstr_prependf()

PrintfLike ssize_t dynstr_prependf	(	DynString *	,
		const char *	fmt,
			... )

Prepends a formatted string to the start of a DynString

Returns

RV_ERROR on allocation error, else the number of appended chars

dynstr_prependn()

ssize_t dynstr_prependn	(	DynString *	,
		const char *	s,
		size_t	len )

Prepends at most len characters to the start of the dynstr

s may not be NULL

Parameters

s	prepended string
len	maximum number of chars prepended

Returns

RV_ERROR on allocation error, else the number of added chars (should be len)

dynstr_reset()

int dynstr_reset

(

DynString *

)

Resets the dynstr to an empty string

Returns

RV_ERROR on realloc fail, else RV_SUCCESS

dynstr_set()

int dynstr_set	(	DynString *	,
		const char *	string )

Sets the dynstr's contents to a new string.

Parameters

string

this string is copied

Returns

RV_ERROR if allocation fails, else RV_SUCCESS

dynstr_set_at()

int dynstr_set_at	(	DynString *	dynstr,
		size_t	idx,
		char	c )

Sets char at idx to c (with bounds checking).

As if

string[ idx ] = c

Returns

RV_EXCEPTION if idx is OOB

dynstr_slice()

int dynstr_slice	(	DynString *	,
		size_t	start_idx,
		ssize_t	end_idx )

Sets the string to be a slice of itself, from start_idx to end_idx. If end_idx < 0, the end index is set as the offset from the \0 character in the string

Examples:

DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 0, -1 ); // => "Hello, world!"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 2, -1 ); // => "llo, world!"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 0, -3 ); // => "Hello, worl"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 0, 4 );  // => "Hell"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 2, -3 ); // => "llo, worl"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 2, 4 );  // => "ll"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 1, 2 );  // => "e"
 
DynString dynstr = dynstr_init_as( "Hello, world!" );
dynstr_slice( dynstr, 2, 1 );  // => returns RV_EXCEPTION
                               //    (contents of dynstr are unchanged)

Parameters

start_idx	index of the first preserved character
end_idx	index of the last preserved character

Returns

RV_SUCCESS on success, RV_EXCEPTION if index is OOB

dynstr_slice_e()

int dynstr_slice_e	(	DynString *	,
		ssize_t	end_idx )

See also

dynstr_slice()

dynstr_slice_s()

int dynstr_slice_s	(	DynString *	,
		size_t	start_idx )

See also

dynstr_slice()

dynstr_vappendf()

ssize_t dynstr_vappendf	(	DynString *	,
		const char *	fmt,
		va_list	vargs )

Appends a formatted string to the end of a DynString

Returns

RV_ERROR on allocation error, else the number of appended chars

dynstr_vprependf()

ssize_t dynstr_vprependf	(	DynString *	,
		const char *	fmt,
		va_list	vargs )

Prepends a formatted string to the start of a DynString

Returns

RV_ERROR on allocation error, else the number of appended chars