Detailed Description

Byte array structures containing raw data bytes.

String structures containing the string and length.

Introduction

The String structure allows a string and its length to be stored in one structure. This avoids unnecessary calls to strlen. Both the string and its length are allocated in a single operation, so the size of the actual structure (when including the string terminator) is sizeof(fiftyoneDegreesString) + length. This means that the string itself starts at "value" and continues into the rest of the allocated memory.

Get

Getting a const char * from a fiftyoneDegreesString structure can be done by casting a reference to the "value" field:

(const char*)&string->value

However, this can be simplified by using the FIFTYONE_DEGREES_STRING macro which also performs a NULL check on the structure to avoid a segmentation fault.

Compare

This file contains two case insensitive string comparison methods as standards like stricmp vary across compilers.

fiftyoneDegreesStringCompare : compares two strings case insensitively

fiftyoneDegreesStringCompareLength : compares two strings case insensitively up to the length required. Any characters after this point are ignored

Collaboration diagram for String:

Structs
struct	fiftyoneDegreesVarLengthByteArray
union	fiftyoneDegreesStoredBinaryValue
	"Packed" value that can be present inside "strings" of dataset. More...
struct	fiftyoneDegreesString
struct	fiftyoneDegreesStringBuilder
	String buffer for building strings with memory checks. More...

Macros
#define	FIFTYONE_DEGREES_STRING(s)
	Macro used to check for NULL before returning the string as a const char *.

Typedefs
typedef union fiftyone_degrees_stored_binary_value_t	fiftyoneDegreesStoredBinaryValue
typedef struct fiftyone_degrees_var_length_byte_array_t	fiftyoneDegreesVarLengthByteArray

Functions
void *	fiftyoneDegreesStoredBinaryValueRead (const fiftyoneDegreesCollectionFile file, const fiftyoneDegreesCollectionKey key, fiftyoneDegreesData data, fiftyoneDegreesException exception)
	Reads a binary value from the source file at the offset within the string structure.
const fiftyoneDegreesStoredBinaryValue *	fiftyoneDegreesStoredBinaryValueGet (const fiftyoneDegreesCollection strings, uint32_t offset, fiftyoneDegreesPropertyValueType storedValueType, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException *exception)
	Gets the binary value at the required offset from the collection provided.
int	fiftyoneDegreesStoredBinaryValueCompareWithString (const fiftyoneDegreesStoredBinaryValue value, fiftyoneDegreesPropertyValueType storedValueType, const char target, fiftyoneDegreesStringBuilder tempBuilder, fiftyoneDegreesException exception)
	Function to compare the current binary value to the target string value using the text format.
int	fiftyoneDegreesStoredBinaryValueToIntOrDefault (const fiftyoneDegreesStoredBinaryValue *value, fiftyoneDegreesPropertyValueType storedValueType, int defaultValue)
	Function to convert the binary value to int when possible.
double	fiftyoneDegreesStoredBinaryValueToDoubleOrDefault (const fiftyoneDegreesStoredBinaryValue *value, fiftyoneDegreesPropertyValueType storedValueType, double defaultValue)
	Function to convert the binary value to double when possible.
bool	fiftyoneDegreesStoredBinaryValueToBoolOrDefault (const fiftyoneDegreesStoredBinaryValue *value, fiftyoneDegreesPropertyValueType storedValueType, bool defaultValue)
	Function to convert the binary value to bool when possible.
uint32_t	fiftyoneDegreesStringGetFinalSize (const void initial, fiftyoneDegreesException exception)
	Gets size of String with trailing characters.
void *	fiftyoneDegreesStringRead (const fiftyoneDegreesCollectionFile file, const fiftyoneDegreesCollectionKey key, fiftyoneDegreesData data, fiftyoneDegreesException exception)
	Reads a string from the source file at the offset within the string structure.
const fiftyoneDegreesString *	fiftyoneDegreesStringGet (const fiftyoneDegreesCollection strings, uint32_t offset, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException *exception)
	Gets the string at the required offset from the collection provided.
int	fiftyoneDegreesStringCompareLength (char const a, char const b, size_t length)
	Case insensitively compare two strings up to the length requested.
int	fiftyoneDegreesStringCompare (const char a, const char b)
	Case insensitively compare two strings.
const char *	fiftyoneDegreesStringSubString (const char a, const char b)
	Case insensitively searching a first occurrence of a substring.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderInit (fiftyoneDegreesStringBuilder *builder)
	Initializes the buffer.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderAddChar (fiftyoneDegreesStringBuilder *builder, char const value)
	Adds the character to the buffer.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderAddInteger (fiftyoneDegreesStringBuilder *builder, int64_t const value)
	Adds the integer to the buffer.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderAddDouble (fiftyoneDegreesStringBuilder *builder, double value, uint8_t decimalPlaces)
	Adds the double to the buffer.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderAddChars (fiftyoneDegreesStringBuilder builder, const char value, size_t length)
	Adds the string to the buffer.
void	fiftyoneDegreesStringBuilderAddIpAddress (fiftyoneDegreesStringBuilder builder, const fiftyoneDegreesVarLengthByteArray ipAddress, fiftyoneDegreesIpType type, fiftyoneDegreesException *exception)
	Adds an the IP (as string) from byte "string".
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderAddStringValue (fiftyoneDegreesStringBuilder builder, const fiftyoneDegreesStoredBinaryValue value, fiftyoneDegreesPropertyValueType valueType, uint8_t decimalPlaces, fiftyoneDegreesException *exception)
	Adds a potentially packed value as a proper string to the buffer.
fiftyoneDegreesStringBuilder *	fiftyoneDegreesStringBuilderComplete (fiftyoneDegreesStringBuilder *builder)
	Adds a null terminating character to the buffer.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_STRING

#define FIFTYONE_DEGREES_STRING

(

s

)

Value:

(const char*)(s == NULL ? NULL : &((fiftyoneDegreesString*)s)->value)

fiftyoneDegreesString

Definition string.h:97

Macro used to check for NULL before returning the string as a const char *.

Parameters

s	pointer to the fiftyoneDegreesString

Returns: const char * string or NULL

Examples: Hash/StronglyTyped.c.

Function Documentation

◆ fiftyoneDegreesStoredBinaryValueCompareWithString()

int fiftyoneDegreesStoredBinaryValueCompareWithString	(	const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		const char *	target,
		fiftyoneDegreesStringBuilder *	tempBuilder,
		fiftyoneDegreesException *	exception )

Function to compare the current binary value to the target string value using the text format.

Parameters

value	the current binary value item
storedValueType	format of byte array representation
target	the target search value.
tempBuilder	temporary builder to stringify value into.

Returns: 0 if they are equal, otherwise negative for smaller and positive for bigger

◆ fiftyoneDegreesStoredBinaryValueGet()

const fiftyoneDegreesStoredBinaryValue * fiftyoneDegreesStoredBinaryValueGet	(	const fiftyoneDegreesCollection *	strings,
		uint32_t	offset,
		fiftyoneDegreesPropertyValueType	storedValueType,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Gets the binary value at the required offset from the collection provided.

Parameters

strings	collection to get the string from
offset	of the binary value in the collection
storedValueType	format of byte array representation
item	to store the string in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to binary value or NULL if the offset is not valid

◆ fiftyoneDegreesStoredBinaryValueRead()

void * fiftyoneDegreesStoredBinaryValueRead	(	const fiftyoneDegreesCollectionFile *	file,
		const fiftyoneDegreesCollectionKey *	key,
		fiftyoneDegreesData *	data,
		fiftyoneDegreesException *	exception )

Reads a binary value from the source file at the offset within the string structure.

Parameters

file	collection to read from
key	of the binary value in the collection
data	to store the new string in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to the string collection item or NULL if can't be found

Note: expects data to contain fiftyoneDegreesPropertyValueType matching the stored value type of the property this value belongs to.

◆ fiftyoneDegreesStoredBinaryValueToBoolOrDefault()

bool fiftyoneDegreesStoredBinaryValueToBoolOrDefault	(	const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		bool	defaultValue )

Function to convert the binary value to bool when possible.

Parameters

value	the current binary value item
storedValueType	format of byte array representation
defaultValue	fallback result.

Returns: converted value (when possible) or default one (when type is not convertible).

◆ fiftyoneDegreesStoredBinaryValueToDoubleOrDefault()

double fiftyoneDegreesStoredBinaryValueToDoubleOrDefault	(	const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		double	defaultValue )

Function to convert the binary value to double when possible.

Parameters

value	the current binary value item
storedValueType	format of byte array representation
defaultValue	fallback result.

Returns: converted value (when possible) or default one (when type is not convertible).

◆ fiftyoneDegreesStoredBinaryValueToIntOrDefault()

int fiftyoneDegreesStoredBinaryValueToIntOrDefault	(	const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		int	defaultValue )

Function to convert the binary value to int when possible.

Parameters

value	the current binary value item
storedValueType	format of byte array representation
defaultValue	fallback result.

Returns: converted value (when possible) or default one (when type is not convertible).

◆ fiftyoneDegreesStringBuilderAddChar()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderAddChar	(	fiftyoneDegreesStringBuilder *	builder,
		char const	value )

Adds the character to the buffer.

Parameters

builder	to add the character to
value	character to add

Returns: pointer to the builder passed

◆ fiftyoneDegreesStringBuilderAddChars()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderAddChars	(	fiftyoneDegreesStringBuilder *	builder,
		const char *	value,
		size_t	length )

Adds the string to the buffer.

Parameters

builder	to add the character to
value	of chars to add
length	of chars to add

Returns: pointer to the buffer passed

◆ fiftyoneDegreesStringBuilderAddDouble()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderAddDouble	(	fiftyoneDegreesStringBuilder *	builder,
		double	value,
		uint8_t	decimalPlaces )

Adds the double to the buffer.

Parameters

builder	to add the character to
value	floating-point number to add
decimalPlaces	precision (places after decimal dot)

Returns: pointer to the buffer passed

◆ fiftyoneDegreesStringBuilderAddInteger()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderAddInteger	(	fiftyoneDegreesStringBuilder *	builder,
		int64_t const	value )

Adds the integer to the buffer.

Parameters

builder	to add the character to
value	integer to add

Returns: pointer to the buffer passed

◆ fiftyoneDegreesStringBuilderAddIpAddress()

void fiftyoneDegreesStringBuilderAddIpAddress	(	fiftyoneDegreesStringBuilder *	builder,
		const fiftyoneDegreesVarLengthByteArray *	ipAddress,
		fiftyoneDegreesIpType	type,
		fiftyoneDegreesException *	exception )

Adds an the IP (as string) from byte "string".

Parameters

builder	to add the IP to
ipAddress	binary (packed) "string" with IP to add
type	type of IP inside
exception	pointer to exception struct

◆ fiftyoneDegreesStringBuilderAddStringValue()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderAddStringValue	(	fiftyoneDegreesStringBuilder *	builder,
		const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	valueType,
		uint8_t	decimalPlaces,
		fiftyoneDegreesException *	exception )

Adds a potentially packed value as a proper string to the buffer.

Parameters

builder	to add the character to
value	from data file to add
decimalPlaces	precision for numbers (places after decimal dot)
exception	pointer to exception struct

Returns: pointer to the buffer passed

◆ fiftyoneDegreesStringBuilderComplete()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderComplete

(

fiftyoneDegreesStringBuilder *

builder

)

Adds a null terminating character to the buffer.

Parameters

builder to terminate

Returns: pointer to the buffer passed

◆ fiftyoneDegreesStringBuilderInit()

fiftyoneDegreesStringBuilder * fiftyoneDegreesStringBuilderInit

(

fiftyoneDegreesStringBuilder *

builder

)

Initializes the buffer.

Parameters

builder to initialize

Returns: pointer to the builder passed

◆ fiftyoneDegreesStringCompare()

int fiftyoneDegreesStringCompare	(	const char *	a,
		const char *	b )

Case insensitively compare two strings.

Parameters

a	string to compare
b	other string to compare

Returns: 0 if same

◆ fiftyoneDegreesStringCompareLength()

int fiftyoneDegreesStringCompareLength	(	char const *	a,
		char const *	b,
		size_t	length )

Case insensitively compare two strings up to the length requested.

Parameters

a	string to compare
b	other string to compare
length	of the strings to compare

Returns: 0 if same

◆ fiftyoneDegreesStringGet()

const fiftyoneDegreesString * fiftyoneDegreesStringGet	(	const fiftyoneDegreesCollection *	strings,
		uint32_t	offset,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Gets the string at the required offset from the collection provided.

Parameters

strings	collection to get the string from
offset	of the string in the collection
item	to store the string in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to string of NULL if the offset is not valid

◆ fiftyoneDegreesStringGetFinalSize()

uint32_t fiftyoneDegreesStringGetFinalSize	(	const void *	initial,
		fiftyoneDegreesException *	exception )

Gets size of String with trailing characters.

Parameters

initial pointer to string "head"

Returns: full (with tail) struct size

◆ fiftyoneDegreesStringRead()

void * fiftyoneDegreesStringRead	(	const fiftyoneDegreesCollectionFile *	file,
		const fiftyoneDegreesCollectionKey *	key,
		fiftyoneDegreesData *	data,
		fiftyoneDegreesException *	exception )

Reads a string from the source file at the offset within the string structure.

Parameters

file	collection to read from
key	of the string in the collection
data	to store the new string in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to the string collection item or NULL if can't be found

◆ fiftyoneDegreesStringSubString()

const char * fiftyoneDegreesStringSubString	(	const char *	a,
		const char *	b )

Case insensitively searching a first occurrence of a substring.

Parameters

a	string to search
b	substring to be searched for

Returns: pointer to the first occurrence or NULL if not found

String Common

Detailed Description

Introduction

Get

Compare

Collaboration diagram for String:

Structs

Macros

Typedefs

Functions

Macro Definition Documentation

◆ FIFTYONE_DEGREES_STRING

Function Documentation

◆ fiftyoneDegreesStoredBinaryValueCompareWithString()

◆ fiftyoneDegreesStoredBinaryValueGet()

◆ fiftyoneDegreesStoredBinaryValueRead()

◆ fiftyoneDegreesStoredBinaryValueToBoolOrDefault()

◆ fiftyoneDegreesStoredBinaryValueToDoubleOrDefault()

◆ fiftyoneDegreesStoredBinaryValueToIntOrDefault()

◆ fiftyoneDegreesStringBuilderAddChar()

◆ fiftyoneDegreesStringBuilderAddChars()

◆ fiftyoneDegreesStringBuilderAddDouble()

◆ fiftyoneDegreesStringBuilderAddInteger()

◆ fiftyoneDegreesStringBuilderAddIpAddress()

◆ fiftyoneDegreesStringBuilderAddStringValue()

◆ fiftyoneDegreesStringBuilderComplete()

◆ fiftyoneDegreesStringBuilderInit()

◆ fiftyoneDegreesStringCompare()

◆ fiftyoneDegreesStringCompareLength()

◆ fiftyoneDegreesStringGet()

◆ fiftyoneDegreesStringGetFinalSize()

◆ fiftyoneDegreesStringRead()

◆ fiftyoneDegreesStringSubString()

String
Common