Utilities

This section lists utility classes and functions, which help to implement Circle applications.

CString

#include <circle/string.h>
class CString

This class encapsulates a character string and allows different manipulations on it. The methods of this class are not reentrant.

CString::CString(void)

Creates an empty string object ("");

CString::CString(const char *pString)

Creates a string object. Sets the string initially to pString.

CString::CString(const CString &rString)

Copy constructor. Creates a new string object. Sets the string initially to the value of rString. rString remains unchanged.

CString::CString(CString &&rrString)

Move constructor. Creates a new string object. Sets the string initially to the value of rrString. rrString is set to an empty string.

CString::operator const char*(void) const

Returns a pointer to the string buffer, which is terminated with a zero-character.

const char *CString::operator=(const char *pString)

Assigns a new string. Returns a pointer to the string buffer, which is terminated with a zero-character.

CString &CString::operator=(const CString &rString)

Assigns a new string. Returns a reference to the string object.

CString &CString::operator=(CString &&rrString)

Move assignment. Assigns a new string. rrString is set to an empty string. Returns a reference to the string object.

size_t CString::GetLength(void) const

Returns the length of the string in number of characters (zero for empty string).

void CString::Append(const char *pString)

Appends pString to the string.

int CString::Compare(const char *pString) const

Compares pString with the string. Returns:

  • zero, if the strings are identical

  • a negative value, if the string is smaller than pString

  • a positive value, if the string is greater than pString

int CString::Find(char chChar) const

Searches for chChar in the string. Returns the zero-based index of the character or -1, if it is not found.

int CString::Replace(const char *pOld, const char *pNew)

Replaces all occurrences of pOld with pNew in the string. Returns the number of occurrences.

void CString::Format(const char *pFormat, ...)

Formats a string as known from sprintf(). Does support only a subset of the known format specifiers:

%[#][[-][0]len][.prec][l|ll]{c|d|f|i|o|p|s|u|x|X}

Field

Description

#

insert prefix 0, 0x or 0X for %o, %x or %X

-

left justify output

0

insert leading zeros

len

decimal number specifying the length of the field

.prec

decimal number specifying the precision for %f

l

type is long

ll

type is long long (with STDLIB_SUPPORT >= 1 only)

c

insert char

d

insert decimal int, long or long long (maybe with sign)

f

insert double

i

same as %d

o

insert octal unsigned, unsigned long or unsigned long long

p

same as %x

s

insert string (type is const char *)

u

insert decimal unsigned, unsigned long or unsigned long long

x

insert hex unsigned, unsigned long or unsigned long long (lower case)

X

insert hex unsigned, unsigned long or unsigned long long (upper case)
void CString::FormatV(const char *pFormat, va_list Args)

Same as Format(), but Args are given as va_list.

CPtrArray

#include <circle/ptrarray.h>
class CPtrArray

This class implements a dynamic array of pointers. The methods of this class are not reentrant.

CPtrArray::CPtrArray(unsigned nInitialSize = 100, unsigned nSizeIncrement = 100)

Creates a CPtrArray object with initially space for nInitialSize elements. The memory allocation will be increased by nSizeIncrement elements, when the array is full.

unsigned CPtrArray::GetCount(void) const

Returns the current number of used elements in the array.

void *CPtrArray::operator[](unsigned nIndex) const

Returns the pointer for the array element at nIndex (based on zero). nIndex must be smaller than the value returned from GetCount().

void *&CPtrArray::operator[](unsigned nIndex)

Returns a reference to the pointer for the array element at nIndex (based on zero). nIndex must be smaller than the value returned from GetCount().

unsigned CPtrArray::Append(void *pPtr)

Appends pPtr to end of the array.

void CPtrArray::RemoveLast(void)

Removes the last element from the array.

CPtrList

#include <circle/ptrlist.h>
class CPtrList

This class implements a linked list of pointers. The methods of this class are not reentrant.

type TPtrListElement

Opaque type definition.

TPtrListElement *CPtrList::GetFirst(void)

Returns the first element, or 0 if list is empty.

TPtrListElement *CPtrList::GetNext(TPtrListElement *pElement)

Returns the next element following pElement, or 0 if nothing follows.

void *CPtrList::GetPtr(TPtrListElement *pElement)

Returns the pointer for pElement.

void CPtrList::InsertBefore(TPtrListElement *pAfter, void *pPtr)

Inserts pPtr before the element pAfter, which must not be 0.

void CPtrList::InsertAfter(TPtrListElement *pBefore, void *pPtr)

Inserts pPtr after the element pBefore. Use pBefore == 0 to set the first element in the list (list must be empty).

void CPtrList::Remove(TPtrListElement *pElement)

Removes the element pElement from the list.

TPtrListElement *CPtrList::Find(void *pPtr)

Searches the element, whose pointer is equal to pPtr and returns it, or 0 if pPtr was not found.

CPtrListFIQ

#include <circle/ptrlistfiq.h>
class CPtrListFIQ

Same as CPtrList, but can be used from FIQ_LEVEL.

CPtrListFIQ::CPtrListFIQ(unsigned nMaxElements)

Creates a pointer list with up to nMaxElements elements.

CNumberPool

#include <circle/numberpool.h>
class CNumberPool

This class implements an allocation pool for numbers. The methods of this class are not reentrant.

static const unsigned Limit = 63

Allowed maximum of an allocated number.

static const unsigned Invalid = Limit + 1

Returned by AllocateNumber() on failure.

CNumberPool::CNumberPool(unsigned nMin, unsigned nMax = Limit)

Creates a number pool. nMin is the minimal returned number by AllocateNumber(). nMax is the maximal returned number.

unsigned CNumberPool::AllocateNumber(boolean bMustSucceed, const char *pFrom = "numpool")

Allocates a number from the number pool and returns it. If there are no more numbers available, this method returns CNumberPool::Invalid, if bMustSucceed is FALSE, or the system halts with a panic message otherwise. This message has the prefix pFrom.

void CNumberPool::FreeNumber(unsigned nNumber)

Returns nNumber, which has been allocated earlier, to the number pool for reuse.

Atomic memory access

#include <circle/atomic.h>

This header file defines some functions, which implement an atomic access to an aligned int variable in memory. These functions can be useful for synchronization purposes, especially for multi-core applications, where using a spin lock would be too time consuming. All accesses to such a variable must use one of the following functions, to ensure them being atomic.

int AtomicGet(volatile const int *pVar)

Returns the value of the int variable at pVar.

int AtomicSet(volatile int *pVar, int nValue)

Sets the int variable at pVar to nValue and returns nValue.

int AtomicExchange(volatile int *pVar, int nValue)

Sets the int variable at pVar to nValue and returns the previous value.

int AtomicCompareExchange(volatile int *pVar, int nCompare, int nValue)

Sets the int variable at pVar to nValue, if the previous value of the variable was nCompare, and returns the previous value of the variable.

int AtomicAdd(volatile int *pVar, int nValue)

Adds nValue to the int variable at pVar. Returns the result of the operation.

int AtomicSub(volatile int *pVar, int nValue)

Subtracts nValue from the int variable at pVar. Returns the result of the operation.

int AtomicIncrement(volatile int *pVar)

Increments the int variable at pVar by 1. Returns the result of the operation.

int AtomicDecrement(volatile int *pVar)

Decrements the int variable at pVar by 1. Returns the result of the operation.

C standard library functions

#include <circle/util.h>

This header file defines some functions, known from the C standard library.

Memory functions

void *memset(void *pBuffer, int nValue, size_t nLength)
void *memcpy(void *pDest, const void *pSrc, size_t nLength)
void *memmove(void *pDest, const void *pSrc, size_t nLength)
int memcmp(const void *pBuffer1, const void *pBuffer2, size_t nLength)

String functions

size_t strlen(const char *pString)
int strcmp(const char *pString1, const char *pString2)
int strcasecmp(const char *pString1, const char *pString2)
int strncmp(const char *pString1, const char *pString2, size_t nMaxLen)
int strncasecmp(const char *pString1, const char *pString2, size_t nMaxLen)
char *strcpy(char *pDest, const char *pSrc)
char *strncpy(char *pDest, const char *pSrc, size_t nMaxLen)
char *strcat(char *pDest, const char *pSrc)
char *strchr(const char *pString, int chChar)
char *strstr(const char *pString, const char *pNeedle)
char *strtok_r(char *pString, const char *pDelim, char **ppSavePtr)

Number conversion

unsigned long strtoul(const char *pString, char **ppEndPtr, int nBase)
unsigned long long strtoull(const char *pString, char **ppEndPtr, int nBase)
int atoi(const char *pString)

Other functions

#include <circle/util.h>
u16 bswap16(u16 usValue)
u32 bswap32(u32 ulValue)

Swaps the byte order of a 16- or 32-bit value.

int parity32(unsigned nValue)

Returns the number of 1-bits in nValue modulo 1.

Macros

#include <circle/macros.h>
PACKED

Packs a struct definition. The members will be stored tightly, not aligned as usual.

ALIGN(n)

Aligns a variable or member to a boundary of n in memory.

NORETURN

Append this to the prototype of a function, which never returns.

BIT(n)

Returns the bit mask (1U << (n)).

likely(exp)
unlikely(exp)

In time critical code this gives the compiler a hint, which result of the boolean expression exp is normally expected. This can result in faster code.