51Degrees Device Detection C/C++  4.5

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

Search

Documentation

List

• Common

Detailed Description

A more manageable way to store arrays.

Introduction

Lists are a way of storing an array of elements in an easy to manage way. This means that the capacity, and the number of elements are both known quantities to any method handling the list, in contrast to a pure array where neither are known. Lists hold collection items, so when they are finished with, they must be freed correctly using the fiftyoneDegreesListFree method. Cleanup is also handled so as to be simpler to use than an array. By freeing the list, all elements are released from their collection and the memory for the list is freed.

Creation

Lists are created by allocating memory to the list structure, then calling the init method fiftyoneDegreesListInit to allocate memory for list items and initialise the count and capacity.

Add

Collection items are added to a list using the fiftyoneDegreesListAdd method. This then holds the reference to the collection item until the list is freed.

Get

Items can be fetched from the list by accessing the collection item directly:

list->items[index]

then casting the pointer it contains to the correct type. Or for strings the fiftyoneDegreesListGetAsString method can be used to access and cast in one call.

Free

Lists must be freed using the fiftyoneDegreesListFree method. This releases all collection items stored within, and frees the memory for the internal array which stores their pointers.

Reuse

Lists can be reused by releasing all the collection items with the fiftyoneDegreesListRelease method, clearing the list ready for a new list of items to be added.

Usage Example

fiftyoneDegreesList list;

fiftyoneDegreesCollectionItem *item;

// Initialise the list with the capacity for 1 entry

fiftyoneDegreesListInit(&list, 1);

// Add an item from a collection to the list

fiftyoneDegreesListAdd(&list, item);

// Get the first item in the list as a string

fiftyoneDegreesString *string = fiftyoneDegreesListGetAsString(&list, 0);

// Do Something with the string

// ...

// Free the list, releasing the items it contains back to their respective

// collections

fiftyoneDegreesListFree(&list);

Collaboration diagram for List:

Structs
struct	fiftyoneDegreesList
	List structure which contains a list of collection items. More...

Functions
fiftyoneDegreesList *	fiftyoneDegreesListInit (fiftyoneDegreesList *list, uint32_t capacity)
	Initialise the list by allocating space for the items in the list structure.
void	fiftyoneDegreesListAdd (fiftyoneDegreesList *list, fiftyoneDegreesCollectionItem *item)
	Adds a collection item to a list.
fiftyoneDegreesString *	fiftyoneDegreesListGetAsString (fiftyoneDegreesList *list, int index)
	Gets the item at the index provided as a string.
void	fiftyoneDegreesListFree (fiftyoneDegreesList *list)
	Frees the memory allocated to the list structure and release all items stored in it.
void	fiftyoneDegreesListReset (fiftyoneDegreesList *list)
	Resets a newly allocated list to a clean empty state.
void	fiftyoneDegreesListRelease (fiftyoneDegreesList *list)
	Releases all the items stored in the list.

Function Documentation

◆ fiftyoneDegreesListAdd()

void fiftyoneDegreesListAdd	(	fiftyoneDegreesList *	list,
		fiftyoneDegreesCollectionItem *	item )

Adds a collection item to a list.

The reference to the item will be released when the list is released or freed.

Parameters

list	to add the item to
item	to add to the list

◆ fiftyoneDegreesListFree()

void fiftyoneDegreesListFree

(

fiftyoneDegreesList *

list

)

Frees the memory allocated to the list structure and release all items stored in it.

Parameters

list

to free

◆ fiftyoneDegreesListGetAsString()

fiftyoneDegreesString * fiftyoneDegreesListGetAsString	(	fiftyoneDegreesList *	list,
		int	index )

Gets the item at the index provided as a string.

Parameters

list	to get the item from
index	of the item in the list

Returns

the requested list item as a string

◆ fiftyoneDegreesListInit()

fiftyoneDegreesList * fiftyoneDegreesListInit	(	fiftyoneDegreesList *	list,
		uint32_t	capacity )

Initialise the list by allocating space for the items in the list structure.

Parameters

list	pointer to list structure to initialise
capacity	number of items expected in the list

Returns

the initialised list or NULL if memory could not be allocated

◆ fiftyoneDegreesListRelease()

void fiftyoneDegreesListRelease

(

fiftyoneDegreesList *

list

)

Releases all the items stored in the list.

Parameters

list	to release

◆ fiftyoneDegreesListReset()

void fiftyoneDegreesListReset

(

fiftyoneDegreesList *

list

)

Resets a newly allocated list to a clean empty state.

Parameters

list

to reset

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