51Degrees Device Detection C/C++  4.5

A device detection library that is used natively or by 51Degrees products

Documentation

String

• Common

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.
char *	fiftyoneDegreesStoredBinaryValueToText (const fiftyoneDegreesStoredBinaryValue *value, fiftyoneDegreesPropertyValueType storedValueType, uint8_t decimalPlaces, char *buffer, size_t bufferLength, fiftyoneDegreesException *exception)
	Writes the binary value as text, as results and metadata give it, with a number written to at most decimalPlaces places after the point.
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)

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

◆ fiftyoneDegreesStoredBinaryValueToText()

char * fiftyoneDegreesStoredBinaryValueToText	(	const fiftyoneDegreesStoredBinaryValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		uint8_t	decimalPlaces,
		char *	buffer,
		size_t	bufferLength,
		fiftyoneDegreesException *	exception )

Writes the binary value as text, as results and metadata give it, with a number written to at most decimalPlaces places after the point.

The text is written into buffer when it fits in bufferLength bytes, and otherwise into memory allocated with fiftyoneDegreesMalloc, which the caller frees with fiftyoneDegreesFree when the pointer returned is not buffer. A string or an area that would not fit buffer is written straight into memory sized from its length or its bytes. A string is therefore written once. An area is normally written once too, as #FIFTYONE_DEGREES_TEXT_PER_GEOMETRY_BYTE characters for each byte normally hold its text. A reduced area written to more than 4 places can need more, as each point of 4 bytes can then take more than 20 characters, and is written a second time when it does. A number or an IP address has no size until it is written, so one whose text does not fit buffer is written twice, as an IPv6 address of 39 characters is with a buffer of less than 40 bytes. buffer can be NULL with bufferLength 0, and the text is then always allocated.

Parameters

value	the binary value to write
storedValueType	format of byte array representation
decimalPlaces	the most places to write after the decimal point
buffer	memory the text is written into when it fits
bufferLength	the bytes buffer holds
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns

the null terminated text, or NULL when the value cannot be written or memory cannot be allocated

◆ 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

Have a data or code question? Get in touch and explore subscription options.