as_string Struct Reference

Detailed Description

Container for NULL-terminates string values.

Initialization

An as_string should be initialized via one of the provided function.

• as_string_init()
• as_string_new()

To initialize a stack allocated as_string, use as_string_init():

as_string s;
as_string_init(&s, "abc", false);

The 3rd argument indicates whether the string value should be free()d when as_string is destroyed.

To create and initialize a heap allocated as_string, use as_string_new():

as_string * s = as_string_new("abc", false);

Destruction

When the as_string instance is no longer required, then you should release the resources associated with it via as_string_destroy():

as_string_destroy(s);

Usage

There are two functions for getting the boxed value contained by as_string:

as_string_get() returns the contained value. If an error occurred, then NULL is returned. Possible errors is the as_string instance is NULL.

char * sval = as_string_get(i);

as_string_getorelse() allows you to return a default value if an error occurs:

char * sval = as_string_getorelse(i, "oops!");

Conversions

as_string is derived from as_val, so it is generally safe to down cast:

as_val val = (as_val) s;

However, upcasting is more error prone. When doing so, you should use as_string_fromval(). If conversion fails, then the return value is NULL.

as_string * i = as_string_fromval(val);

Definition at line 103 of file as_string.h.

#include "as_string.h"

Inheritance diagram for as_string:

Collaboration diagram for as_string:

Data Fields
bool	free
size_t	len
char *	value
Data Fields inherited from as_val
uint32_t	count
bool	free
as_val_t	type

Related Symbols
(Note that these are not member symbols.)
AS_EXTERN const char *	as_basename (as_string *filename, const char *path)
static void	as_string_destroy (as_string *string)
static as_string *	as_string_fromval (const as_val *v)
static char *	as_string_get (const as_string *string)
static char *	as_string_getorelse (const as_string *string, char *fallback)
AS_EXTERN as_string *	as_string_init (as_string *string, char *value, bool free)
AS_EXTERN as_string *	as_string_init_wlen (as_string *string, char *value, size_t len, bool free)
AS_EXTERN size_t	as_string_len (as_string *string)
AS_EXTERN as_string *	as_string_new (char *value, bool free)
AS_EXTERN as_string *	as_string_new_wlen (char *value, size_t len, bool free)
static char *	as_string_tostring (const as_string *string)
static as_val *	as_string_toval (const as_string *s)
AS_EXTERN bool	as_strncpy (char *trg, const char *src, int size)

Friends And Related Symbol Documentation

as_basename()

AS_EXTERN const char * as_basename ( as_string * filename, const char * path )

related

Return filename component of full path.

If path is empty, the current directory is returned. If path contains trailing directory slashes, create new string to hold filename without slashes. The input path is guaranteed not to be modified. as_string_destroy() must be called when finished with filename.

as_string_destroy()

static void as_string_destroy ( as_string * string )

related

Destroy the as_string and associated resources.

Definition at line 209 of file as_string.h.

References as_val_destroy.

as_string_fromval()

static as_string * as_string_fromval ( const as_val * v )

related

Convert from an as_val.

Definition at line 291 of file as_string.h.

References AS_STRING, and as_util_fromval.

as_string_get()

static char * as_string_get ( const as_string * string )

related

Get the string value.

Definition at line 244 of file as_string.h.

References as_string_getorelse().

as_string_getorelse()

static char * as_string_getorelse ( const as_string * string, char * fallback )

related

Get the string value. If string is NULL, then return the fallback value.

Definition at line 234 of file as_string.h.

as_string_init()

AS_EXTERN as_string * as_string_init ( as_string * string, char * value, bool free )

related

Initialize a stack allocated as_string.

If free is true, then the string value will be freed when the as_string is destroyed.

Parameters

string	The stack allocated as_string to initialize
value	The NULL terminated string of character.
free	If true, then the value will be freed when as_string is destroyed.

Returns

On success, the initialized string. Otherwise NULL.

as_string_init_wlen()

AS_EXTERN as_string * as_string_init_wlen ( as_string * string, char * value, size_t len, bool free )

related

Initialize a stack allocated as_string and its length.

If free is true, then the string value will be freed when the as_string is destroyed.

Parameters

string	The stack allocated as_string to initialize
value	The NULL terminated string of character.
len	The length of the string.
free	If true, then the value will be freed when as_string is destroyed.

Returns

On success, the initialized string. Otherwise NULL.

as_string_len()

AS_EXTERN size_t as_string_len ( as_string * string )

related

The length of the string

Parameters

string

The string to get the length of.

Returns

the length of the string in bytes.

as_string_new()

AS_EXTERN as_string * as_string_new ( char * value, bool free )

related

Create and initialize a new heap allocated as_string.

If free is true, then the string value will be freed when the as_string is destroyed.

Parameters

value	The NULL terminated string of character.
free	If true, then the value will be freed when as_string is destroyed.

Returns

On success, the new string. Otherwise NULL.

as_string_new_wlen()

AS_EXTERN as_string * as_string_new_wlen ( char * value, size_t len, bool free )

related

Create and initialize a new heap allocated as_string and its length.

If free is true, then the string value will be freed when the as_string is destroyed.

Parameters

value	The NULL terminated string of character.
len	The length of the string.
free	If true, then the value will be freed when as_string is destroyed.

Returns

On success, the new string. Otherwise NULL.

as_string_tostring()

static char * as_string_tostring ( const as_string * string )

related

Get the string value.

Deprecated

Use as_string_get() instead

Definition at line 255 of file as_string.h.

References as_string_getorelse().

as_string_toval()

static as_val * as_string_toval ( const as_string * s )

related

Convert to an as_val.

Definition at line 281 of file as_string.h.

as_strncpy()

AS_EXTERN bool as_strncpy ( char * trg, const char * src, int size )

related

Copy null terminated src to trg up to a maximum size. If maximum size reached, null terminate last character and and return true that truncation occurred.

as_strncpy does not pad unused bytes with zeroes like the standard strncpy.

char target[64];
as_strncpy(target, "source string", sizeof(target));

Field Documentation

free

bool as_string::free

If true, then as_string.value can be freed.

Definition at line 115 of file as_string.h.

len

size_t as_string::len

The length of the string.

Definition at line 125 of file as_string.h.

value

char* as_string::value

The string value.

Definition at line 120 of file as_string.h.

---

The documentation for this struct was generated from the following file:

• as_string.h