\r\n

51Degrees Device Detection C/C++  4.2Newer Version 4.4

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

List

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. More...
void  fiftyoneDegreesListAdd (fiftyoneDegreesList *list, fiftyoneDegreesCollectionItem *item)
Adds a collection item to a list. More...
fiftyoneDegreesString *  fiftyoneDegreesListGetAsString (fiftyoneDegreesList *list, int index)
Gets the item at the index provided as a string. More...
void  fiftyoneDegreesListFree (fiftyoneDegreesList *list)
Frees the memory allocated to the list structure and release all items stored in it. More...
void  fiftyoneDegreesListReset (fiftyoneDegreesList *list)
Resets a newly allocated list to a clean empty state. More...
void  fiftyoneDegreesListRelease (fiftyoneDegreesList *list)
Releases all the items stored in the list. More...

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
On This Page

Generated by doxygen 1.8.15