This encapsulates a UTF-8 encoded OPC UA string. More...

#include <string.h>

Public Member Functions
static char *	ua_string_strndup (const char *s, size_t n)
	Creates a duplicate of the string `s`. More...

void	ua_string_init (struct ua_string *s)
	Initializes `s` with a null string, so it is safe to clear or perform further operations. More...

void	ua_string_clear (struct ua_string *s)
	Release allocated resources for `s`. More...

int	ua_string_allocate (struct ua_string *s, size_t size)
	Allocate a string with length `len` bytes. More...

int	ua_string_set (struct ua_string s, const char src)
	Initializes `s` with a copy of `src`. More...

int	ua_string_setn (struct ua_string s, const char src, size_t len)
	Initializes `s` with a copy of `src`. More...

void	ua_string_attach (struct ua_string s, char src)
	Initializes `s` with `src`. More...

void	ua_string_attachn (struct ua_string s, char src, size_t len)
	Initializes `s` with `src`. More...

void	ua_string_attach_const (struct ua_string s, const char src)
	Initializes `s` with string constant `src`. More...

void	ua_string_attachn_const (struct ua_string s, const char src, size_t len)
	Initializes `s` with string constant `src`. More...

int	ua_string_compare_lex (const struct ua_string a, const struct ua_string b)
	The compare function returns zero if both strings are equal. More...

int	ua_string_compare (const struct ua_string a, const struct ua_string b)
	The compare function returns zero if both strings are equal. More...

int	ua_string_compare_const (const struct ua_string a, const char b)
	Compares a UA string with a string constant. More...

int	ua_string_comparen_const (const struct ua_string a, const char b, size_t len)
	Compares a UA string with a string constant of known length. More...

int	ua_string_copy (struct ua_string dst, const struct ua_string src)
	Creates a copy of the string `src` including the terminating null byte. More...

int	ua_string_cat (struct ua_string dst, size_t size, const struct ua_string src)
	Appends a copy of `src` to the end of `dst`. More...

int	ua_string_catf (struct ua_string dst, size_t size, const char fmt,...)
	Appends a formated string to the end of `dst`. More...

int	ua_string_snprintf (struct ua_string s, size_t size, const char fmt,...)
	Replaces the given string `s` with a formated string. More...

size_t	ua_string_length (const struct ua_string *s)
	Returns the length of the string in bytes excluding the zero terminator. More...

char *	ua_string_data (struct ua_string *s)
	Returns the raw string data of `s`. More...

const char *	ua_string_const_data (const struct ua_string *s)
	Returns the raw string data of `s`. More...

bool	ua_string_is_null (const struct ua_string *s)
	Returns true if the given string is a NULL string. More...

bool	ua_string_is_empty (const struct ua_string *s)
	Returns true if the given string is a valid empty string. More...

Data Fields
uint32_t	len: 31
	Length of the string. More...

uint32_t	free: 1
	Bit to indicate if the data pointer must be freed. More...

union {
const char * cdata
	Const pointer to the data. More...

char * data
	Non-const pointer to the data. More...

}	d
	The string data. More...

Related Functions
#define	UA_STRING_INITIALIZER { 0, 0, { NULL } }
	Initializer for null strings.

#define	UA_STRING_FROM_C_STRING(s) { sizeof(s)-1, 0, { s } }
	Initializer for ua_strings from string constants.

Detailed Description

This encapsulates a UTF-8 encoded OPC UA string.

Note, on the wire OPC UA String are not zero terminated, in memory we always add a zero terminator to avoid problems with C functions that expect zero terminated strings.

Member Function Documentation

int ua_string_allocate	(	struct ua_string *	s,
		size_t	size
	)

Allocate a string with length len bytes.

This creates an empty string, but with an internal buffer of len bytes. Note that one byte is reserved for the null terminator. If you want to store a string with length n you need to allocate n+1 bytes.

Example:

struct ua_string tmp;
ua_string_allocate(tmp, 39);
ua_guid_snprintf(tmp.data, 39, &guid);

void ua_string_attach	(	struct ua_string *	s,
		char *	src
	)

Initializes s with src.

This function takes ownership of src which means the memory of src will be freed when this string gets cleared using ua_string_clear. If src is NULL, s will be initialized as null string.

void ua_string_attach_const	(	struct ua_string *	s,
		const char *	src
	)

Initializes s with string constant src.

This way s will refer to an external string src and will not free it when ua_string_clear() is called. This may be useful to initialize a UA string with string constants. If src is NULL, s will be initialized as null string.

Example:

struct ua_string tmp;

ua_string_attach_const(&tmp, "Hello World");

void ua_string_attachn	(	struct ua_string *	s,
		char *	src,
		size_t	len
	)

Initializes s with src.

This function functions behaves like ua_string_attach but takes an additional argument len to avoid a strlen() call. If src is NULL s is initialized as null string.

void ua_string_attachn_const	(	struct ua_string *	s,
		const char *	src,
		size_t	len
	)

Initializes s with string constant src.

This function functions behaves like ua_string_attach_ro but takes an additional argument len to avoid a strlen() call. If src is NULL s is initialized as null string.

int ua_string_cat	(	struct ua_string *	dst,
		size_t	size,
		const struct ua_string *	src
	)

Appends a copy of src to the end of dst.

Parameters

dst	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const()..
size	Maximum size the concatenated string can reach (including null byte). If size is too small `dst` will be truncated and UA_EBADTRUNCATED is returned.
src	The string to be concatenated to `dst`.

Returns: 0 on success, errorcode on failure.

int ua_string_catf	(	struct ua_string *	dst,
		size_t	size,
		const char *	fmt,
			...
	)

Appends a formated string to the end of dst.

Parameters

dst	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const().
size	Maximum size the concatenated string can reach (including null byte). If size is too small `dst` will be truncated and UA_EBADTRUNCATED is returned.
fmt	format string according to the printf-format.

Returns: 0 on success, errorcode on failure.

void ua_string_clear ( struct ua_string * s )

Release allocated resources for s.

It is safe to pass a null string or a string attached from a constant string. So clear every ua_string you don't need any longer!

Parameters

s	string to be cleared, will be a null string afterwards.

int ua_string_compare	(	const struct ua_string *	a,
		const struct ua_string *	b
	)

The compare function returns zero if both strings are equal.

If not equal an integer value less or greater then zero is returned, so that the return value can be used as a sorting criteria (e.g. qsort).

Strings are compared by their length field first, so shorter strings are considered smaller. Strings with the same length are compared using ua_memcmp.

This function is intended for maximum performance, however if strings are presented to a human ua_string_compare_lex should be considered.

int ua_string_compare_const	(	const struct ua_string *	a,
		const char *	b
	)

Compares a UA string with a string constant.

This function is provided for convenience and creates a ua_string from b and then calls ua_string_compare

Returns: Zero if equal.

int ua_string_compare_lex	(	const struct ua_string *	a,
		const struct ua_string *	b
	)

The compare function returns zero if both strings are equal.

If not equal an integer value less or greater then zero is returned, so that the return value can be used as a sorting criteria (e.g. qsort).

Strings are compared byte by byte, so when sorting the result is sorted lexicographical. The comparison is case sensitive and all captial letters are considered smaller than all lowercase letters, similar to the C99 strcmp() function.

For a more performant comparison see ua_string_compare.

int ua_string_comparen_const	(	const struct ua_string *	a,
		const char *	b,
		size_t	len
	)

Compares a UA string with a string constant of known length.

This function is provided for convenience.

It sorts the same way as ua_string_compare.

Parameters

a	ua_string as first string comparison operand
b	const char* string as second comparison operand
len	Length if b in bytes. This function is used if `b` is not zero terminated. Note that the purpose of `len` is only to define the length of b, it is not like the n argument of strncmp. So if `a` is longer than `b`, and `len` bytes of `a` are identical to `b`, this function will return "not equal", because the strings have different lengths. To compare substrings you must reduce the length of `a` and `b`.

Returns: Zero if equal.

const char * ua_string_const_data ( const struct ua_string * s )

Returns the raw string data of s.

This can be used to pass the string to other C functions which expects a normal C string.

int ua_string_copy	(	struct ua_string *	dst,
		const struct ua_string *	src
	)

Creates a copy of the string src including the terminating null byte.

Parameters

dst	destination string
src	source string

Returns: returns zero on success, or errorcode on failure.

char * ua_string_data ( struct ua_string * s )

Returns the raw string data of s.

This pointer can be used to access and modify the characters that compose the string.

void ua_string_init ( struct ua_string * s )

Initializes s with a null string, so it is safe to clear or perform further operations.

Parameters

s	an uninitialized ua_string.

bool ua_string_is_empty ( const struct ua_string * s )

Returns true if the given string is a valid empty string.

This means the string has length of zero, but the data pointer is valid and contains a zero terminator.

bool ua_string_is_null ( const struct ua_string * s )

Returns true if the given string is a NULL string.

In OPC UA len is set to -1 for NULL strings, however we only check the data pointer. If data is NULL the string is a NULL string and len is ignored.

size_t ua_string_length ( const struct ua_string * s )

Returns the length of the string in bytes excluding the zero terminator.

A value of 0 indicates an empty or null string, or an invalid argument.

int ua_string_set	(	struct ua_string *	s,
		const char *	src
	)

Initializes s with a copy of src.

src must be a zero terminated C string or NULL.

int ua_string_setn	(	struct ua_string *	s,
		const char *	src,
		size_t	len
	)

Initializes s with a copy of src.

Unlike ua_string_set this function takes an additional len argument. This avoids calling strlen() which is faster when the length is already known and it can be used to create substrings of src. s is initialized as null string if src is NULL.

int ua_string_snprintf	(	struct ua_string *	s,
		size_t	size,
		const char *	fmt,
			...
	)

Replaces the given string s with a formated string.

Parameters

s	An initialized ua_string. This can be a also a Null string, but it must not be a constant string created with ua_string_attach(n)_const().
size	Maximum size the output string can reach (including null byte). If size is too small `s` will be truncated and depending on the platform either UA_EBAD or UA_EBADTRUNCATED is returned.
fmt	format string according to the printf-format.

Returns: 0 on success, errorcode on failure.

static char * ua_string_strndup	(	const char *	s,
		size_t	n
	)

Creates a duplicate of the string s.

This function reads at most n-1 characters from s and appends a zero terminator. So it is safe to call this function from non-terminated string as long as n-1 characters are readable.

Parameters

s	source string
n	size of new string including the zero terminator.

Returns: new zero terminated string on success, NULL if memory allocation fails.

Field Documentation

const char* cdata

Const pointer to the data.

union { ... } d

The string data.

char* data

Non-const pointer to the data.

uint32_t free

Bit to indicate if the data pointer must be freed.

uint32_t len

Length of the string.

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

C:/work/embeddedstack/src/uabase/string.h
C:/work/embeddedstack/src/uabase/string.c

Public Member Functions

Data Fields

Related Functions

Detailed Description

Member Function Documentation

Field Documentation