Detailed Description

Value of a data set relating to a property.

Introduction

A Value is stored in a values collection and contains the meta data for a specific value of a property in a data set.

Get

A value can be fetched from a values collection in one of two ways:

By Index : the fiftyoneDegreesValueGet method return the value at a specified index. This provides a way to access a value at a known index, or iterate over all values.

By Name : if the index of a value is not known, then the value can be fetched using the fiftyoneDegreesValueGetByName method to find the value in a values collection. This requires that the property the value relates to is also known, as values are only unique within the values which relate to a single property. For example "True" could be a value of many properties.

Collaboration diagram for Values:

Structs
struct	fiftyoneDegreesValue
	Value structure containing meta data relating to the value. More...

Macros
#define	FIFTYONE_DEGREES_VALUE_IS_MASKED(v)
	Macro to check if a Value's urlOffsetOrWeight field carries a masked weight.

Functions
const fiftyoneDegreesStoredBinaryValue *	fiftyoneDegreesValueGetContent (const fiftyoneDegreesCollection strings, const fiftyoneDegreesValue value, fiftyoneDegreesPropertyValueType storedValueType, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Returns the contents of the value using the item provided.
const fiftyoneDegreesString *	fiftyoneDegreesValueGetName (const fiftyoneDegreesCollection strings, const fiftyoneDegreesValue value, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Returns the string name of the value using the item provided.
const fiftyoneDegreesString *	fiftyoneDegreesValueGetDescription (const fiftyoneDegreesCollection strings, const fiftyoneDegreesValue value, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Returns the string description of the value using the item provided.
const fiftyoneDegreesString *	fiftyoneDegreesValueGetUrl (const fiftyoneDegreesCollection strings, const fiftyoneDegreesValue value, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Returns the string URL of the value using the item provided.
const fiftyoneDegreesValue *	fiftyoneDegreesValueGet (const fiftyoneDegreesCollection values, uint32_t valueIndex, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException *exception)
	Gets the value for the requested index from the collection provided.
const fiftyoneDegreesValue *	fiftyoneDegreesValueGetByNameAndType (const fiftyoneDegreesCollection values, const fiftyoneDegreesCollection strings, const fiftyoneDegreesProperty property, fiftyoneDegreesPropertyValueType storedValueType, const char valueName, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Get the value for the requested name from the collection provided.
const fiftyoneDegreesValue *	fiftyoneDegreesValueGetByName (const fiftyoneDegreesCollection values, const fiftyoneDegreesCollection strings, const fiftyoneDegreesProperty property, const char valueName, fiftyoneDegreesCollectionItem item, fiftyoneDegreesException exception)
	Get the value for the requested name from the collection provided.
long	fiftyoneDegreesValueGetIndexByNameAndType (const fiftyoneDegreesCollection values, const fiftyoneDegreesCollection strings, const fiftyoneDegreesProperty property, fiftyoneDegreesPropertyValueType storedValueType, const char valueName, fiftyoneDegreesException *exception)
	Get index of the value for the requested name from the collection provided.
long	fiftyoneDegreesValueGetIndexByName (fiftyoneDegreesCollection values, fiftyoneDegreesCollection strings, fiftyoneDegreesProperty property, const char valueName, fiftyoneDegreesException *exception)
	Get index of the value for the requested name from the collection provided.
bool	fiftyoneDegreesValueIsWeighted (const fiftyoneDegreesValue *value)
	Returns true if the value carries a masked weight.
uint16_t	fiftyoneDegreesValueGetWeight (const fiftyoneDegreesValue *value)
	Gets the weight from a Value record as a uint16_t (0–65535), or 0 if the value is not weighted.

Macro Definition Documentation

◆ FIFTYONE_DEGREES_VALUE_IS_MASKED

#define FIFTYONE_DEGREES_VALUE_IS_MASKED

(

v

)

Value:

((((uint32_t)((v)->urlOffsetOrWeight)) & 0xFFFF0000u) == 0xFF000000u)

Macro to check if a Value's urlOffsetOrWeight field carries a masked weight.

A value is weighted when (urlOffsetOrWeight & 0xFFFF0000) == 0xFF000000. This is distinct from -1 (0xFFFFFFFF, "no URL" sentinel) and from valid non-negative URL offsets.

Function Documentation

◆ fiftyoneDegreesValueGet()

const fiftyoneDegreesValue * fiftyoneDegreesValueGet	(	const fiftyoneDegreesCollection *	values,
		uint32_t	valueIndex,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Gets the value for the requested index from the collection provided.

Parameters

values	collection to get the value from
valueIndex	index of the value to get
item	to store the value in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: pointer to the value or NULL

◆ fiftyoneDegreesValueGetByName()

const fiftyoneDegreesValue * fiftyoneDegreesValueGetByName	(	const fiftyoneDegreesCollection *	values,
		const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesProperty *	property,
		const char *	valueName,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Get the value for the requested name from the collection provided.

Parameters

values	collection to get the value from
strings	collection containing the value names
property	that the value relates to
valueName	name of the value to get
item	to store the value in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns: pointer to the value or NULL if it does not exist

◆ fiftyoneDegreesValueGetByNameAndType()

const fiftyoneDegreesValue * fiftyoneDegreesValueGetByNameAndType	(	const fiftyoneDegreesCollection *	values,
		const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesProperty *	property,
		fiftyoneDegreesPropertyValueType	storedValueType,
		const char *	valueName,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Get the value for the requested name from the collection provided.

Parameters

values	collection to get the value from
strings	collection containing the value names
property	that the value relates to
storedValueType	format of byte array representation.
valueName	name of the value to get
item	to store the value in
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns: pointer to the value or NULL if it does not exist

◆ fiftyoneDegreesValueGetContent()

const fiftyoneDegreesStoredBinaryValue * fiftyoneDegreesValueGetContent	(	const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesValue *	value,
		fiftyoneDegreesPropertyValueType	storedValueType,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Returns the contents of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters

strings	collection of strings retrieved by offsets.
value	structure for the name required.
storedValueType	format of byte array representation.
item	used to store the resulting string in.
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to a contents in the collection item data structure.

◆ fiftyoneDegreesValueGetDescription()

const fiftyoneDegreesString * fiftyoneDegreesValueGetDescription	(	const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesValue *	value,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Returns the string description of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters

strings	collection of strings retrieved by offsets.
value	structure for the description required.
item	used to store the resulting string in.
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to a string in the collection item data structure, or to an empty string if the value has no description.

◆ fiftyoneDegreesValueGetIndexByName()

long fiftyoneDegreesValueGetIndexByName	(	fiftyoneDegreesCollection *	values,
		fiftyoneDegreesCollection *	strings,
		fiftyoneDegreesProperty *	property,
		const char *	valueName,
		fiftyoneDegreesException *	exception )

Get index of the value for the requested name from the collection provided.

Parameters

values	collection to get the value from
strings	collection containing the value names
property	that the value relates to
valueName	name of the value to get
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns: the 0 based index of the item if found, otherwise -1

◆ fiftyoneDegreesValueGetIndexByNameAndType()

long fiftyoneDegreesValueGetIndexByNameAndType	(	const fiftyoneDegreesCollection *	values,
		const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesProperty *	property,
		fiftyoneDegreesPropertyValueType	storedValueType,
		const char *	valueName,
		fiftyoneDegreesException *	exception )

Get index of the value for the requested name from the collection provided.

Parameters

values	collection to get the value from
strings	collection containing the value names
property	that the value relates to
storedValueType	format of byte array representation
valueName	name of the value to get
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h

Returns: the 0 based index of the item if found, otherwise -1

◆ fiftyoneDegreesValueGetName()

const fiftyoneDegreesString * fiftyoneDegreesValueGetName	(	const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesValue *	value,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Returns the string name of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters

strings	collection of strings retrieved by offsets.
value	structure for the name required.
item	used to store the resulting string in.
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to a string in the collection item data structure.

◆ fiftyoneDegreesValueGetUrl()

const fiftyoneDegreesString * fiftyoneDegreesValueGetUrl	(	const fiftyoneDegreesCollection *	strings,
		const fiftyoneDegreesValue *	value,
		fiftyoneDegreesCollectionItem *	item,
		fiftyoneDegreesException *	exception )

Returns the string URL of the value using the item provided.

The collection item must be released when the caller is finished with the string.

Parameters

strings	collection of strings retrieved by offsets.
value	structure for the URL required.
item	used to store the resulting string in.
exception	pointer to an exception data structure to be used if an exception occurs. See exceptions.h.

Returns: a pointer to a string in the collection item data structure, to an empty string if the value has no URL, or NULL if the field is negative as it is when it holds a weight.

◆ fiftyoneDegreesValueGetWeight()

uint16_t fiftyoneDegreesValueGetWeight

(

const fiftyoneDegreesValue *

value

)

Gets the weight from a Value record as a uint16_t (0–65535), or 0 if the value is not weighted.

The weight is stored in the lower 2 bytes of urlOffsetOrWeight when the upper 2 bytes match the 0xFF00 mask. To convert to a proportion: (double)weight / UINT16_MAX

Parameters

value the value to get the weight from

Returns: the weight (0–65535 range), or 0 if not weighted

◆ fiftyoneDegreesValueIsWeighted()

bool fiftyoneDegreesValueIsWeighted

(

const fiftyoneDegreesValue *

value

)

Returns true if the value carries a masked weight.

A value is weighted when (urlOffsetOrWeight & 0xFFFF0000) == 0xFF000000. This is distinct from -1 (0xFFFFFFFF, "no URL" sentinel) and from valid non-negative URL offsets.

Parameters

value the value to check

Returns: true if the value carries a masked weight, false otherwise

Values Common

Detailed Description

Introduction

Get

Collaboration diagram for Values:

Structs

Macros

Functions

Macro Definition Documentation

◆ FIFTYONE_DEGREES_VALUE_IS_MASKED

Function Documentation

◆ fiftyoneDegreesValueGet()

◆ fiftyoneDegreesValueGetByName()

◆ fiftyoneDegreesValueGetByNameAndType()

◆ fiftyoneDegreesValueGetContent()

◆ fiftyoneDegreesValueGetDescription()

◆ fiftyoneDegreesValueGetIndexByName()

◆ fiftyoneDegreesValueGetIndexByNameAndType()

◆ fiftyoneDegreesValueGetName()

◆ fiftyoneDegreesValueGetUrl()

◆ fiftyoneDegreesValueGetWeight()

◆ fiftyoneDegreesValueIsWeighted()

Values
Common