diff options
Diffstat (limited to 'inc/AEEstd.h')
| -rw-r--r-- | inc/AEEstd.h | 2681 |
1 files changed, 2681 insertions, 0 deletions
diff --git a/inc/AEEstd.h b/inc/AEEstd.h new file mode 100644 index 0000000..2c832e6 --- /dev/null +++ b/inc/AEEstd.h @@ -0,0 +1,2681 @@ +/** + * Copyright (c) 2019, The Linux Foundation. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * * Neither the name of The Linux Foundation nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS + * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN + * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef AEESTD_H +#define AEESTD_H +/*==================================================================== + +DESCRIPTION: Standard library; general-purpose utility functions. + +====================================================================*/ +#include "AEEVaList.h" +#include "AEEStdDef.h" +#include "string.h" + +#define STD_CONSTRAIN( val, min, max ) (((val) < (min)) ? (min) : ((val) > (max)) ? (max) : (val)) +#define STD_BETWEEN( val, minGE, maxLT ) \ + ( (unsigned long)((unsigned long)(val) - (unsigned long)(minGE)) < \ + (unsigned long)((unsigned long)(maxLT) - (unsigned long)(minGE)) ) +#define STD_ARRAY_SIZE(a) ((int)((sizeof((a))/sizeof((a)[0])))) +#define STD_ARRAY_MEMBER(p,a) (((p) >= (a)) && ((p) < ((a) + STD_ARRAY_SIZE(a)))) + +#define STD_SIZEOF(x) ((int)sizeof(x)) +#define STD_OFFSETOF(type,member) (((char*)(&((type*)1)->member))-((char*)1)) + +#define STD_RECOVER_REC(type,member,p) ((void)((p)-&(((type*)1)->member)),\ + (type*)(void*)(((char*)(void*)(p))-STD_OFFSETOF(type,member))) +#define STD_MIN(a,b) ((a)<(b)?(a):(b)) +#define STD_MAX(a,b) ((a)>(b)?(a):(b)) +//lint -emacro(545,STD_ZEROAT) +#define STD_ZEROAT(p) std_memset((p), 0, sizeof(*p)) + +#define _STD_BITS_PER(bits) (8*sizeof((bits)[0])) + +#define STD_BIT_SET(bits, ix) ((bits)[(ix)/_STD_BITS_PER((bits))] |= 0x1<<((ix) & (_STD_BITS_PER((bits))-1))) +#define STD_BIT_CLEAR(bits, ix) ((bits)[(ix)/_STD_BITS_PER((bits))] &= ~(0x1<<((ix) & (_STD_BITS_PER((bits))-1)))) +#define STD_BIT_TEST(bits, ix) ((bits)[(ix)/_STD_BITS_PER((bits))] & (0x1<<((ix) & (_STD_BITS_PER((bits))-1)))) + +// +// Error codes +// +#define STD_NODIGITS 1 +#define STD_NEGATIVE 2 +#define STD_OVERFLOW 3 +#define STD_BADPARAM 4 +#define STD_UNDERFLOW 5 + +//Compute string length using strlen +#define std_strlen strlen + +#ifdef __cplusplus +extern "C" { +#endif /* #ifdef __cplusplus */ + +//Version function +extern int std_getversion(char *pcDst, int nDestSize); + +//String functions +extern int std_strcmp(const char *s1, const char *s2); +extern int std_strncmp(const char *s1, const char *s2, int n); +extern int std_stricmp(const char *s1, const char *s2); +extern int std_strnicmp(const char *s1, const char *s2, int n); +extern int std_strlcpy(char *pcDst, const char *pszSrc, int nDestSize); +extern int std_strlcat(char *pcDst, const char *pszSrc, int nDestSize); +extern char * std_strstr(const char *pszString, const char *pszSearch); + +//Character functions +extern char std_tolower(char c); +extern char std_toupper(char c); + +// Mem functions +extern void * std_memset(void *p, int c, int nLen); +extern void * std_memmove(void *pTo, const void *cpFrom, int nLen); +extern int std_memscpy(void *dst, int dst_size, const void *src, int src_size); +extern int std_memsmove(void *dst, int dst_size, const void *src, int src_size); +extern int std_memcmp(const void *a, const void *b, int length); +extern void * std_memchr(const void* s, int c, int n); +extern void * std_memstr(const char* cpHaystack, const char* cpszNeedle, int nHaystackLen); +extern void * std_memrchr(const void* s, int c, int n); +extern void * std_memrchrbegin(const void* p, int c, int nLen); +extern void * std_memchrend(const void* cpcSrch, int c, int nLen); +extern void * std_memchrsend(const void *cpSrch, const char* cpszChars, int nLen); + +//Other String functions +extern char * std_strchr(const char* s, int c); +extern char * std_strchrs(const char* sSrch, const char *sChars); +extern char * std_strrchr(const char* s, int c); +extern char * std_strchrend(const char *cpszSrch, char c); +extern char * std_strchrsend(const char* s, const char* cpszSrch); +extern char * std_strends(const char* cpsz, const char* cpszSuffix); +extern char * std_striends(const char* cpsz, const char* cpszSuffix); +extern char * std_strbegins(const char* cpsz, const char* cpszPrefix); +extern char * std_stribegins(const char* cpsz, const char* cpszPrefix); +extern int std_strcspn(const char* s, const char* cpszSrch); +extern int std_strspn(const char* s, const char* cpszSrch); + +//Wide char string functions +extern int std_wstrlen(const AECHAR *s); +extern int std_wstrlcpy(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize); +extern int std_wstrlcat(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize); +extern int std_wstrncmp(const AECHAR* s1, const AECHAR* s2, int nLen); +extern int std_wstrcmp(const AECHAR* s1, const AECHAR* s2); +extern AECHAR* std_wstrchr(const AECHAR* cpwszText, AECHAR ch); +extern AECHAR* std_wstrrchr(const AECHAR* cpwszText, AECHAR ch); + +//Path functions +extern int std_makepath(const char *cpszDir, + const char *cpszFile, + char *pszDest, int nDestSize); +extern char * std_splitpath(const char *cpszPath, const char *cpszDir); +extern char * std_cleanpath(char *pszPath); +extern char * std_basename(const char *pszPath); + +//Inet functions, number functions +extern unsigned int std_scanul(const char *pchBuf, int nRadix, + const char **ppchEnd, int *pnError); +extern uint64 std_scanull(const char *pchBuf, int nRadix, + const char **ppchEnd, int *pnError); +extern double std_scand(const char *pchBuf, const char **ppchEnd); + +// Rand functions +extern unsigned std_rand_next(unsigned uRand); +extern uint32 std_rand(uint32 uSeed, byte* pDest, int nSize); + + +// printf functions +extern int std_vstrlprintf(char *pszDest, int nDestSize, + const char *pszFmt, AEEVaList args); + +extern int std_strlprintf(char *pszDest, int nDestSize, + const char *pszFmt, ...); + +extern int std_vsnprintf(char *pszDest, int nDestSize, + const char *cpszFmt, AEEVaList args); + +extern int std_snprintf(char *pszDest, int nDestSize, + const char *pszFmt, ...); + +// endian swapping functions +extern int std_CopyLE(void *pvDest, int nDestSize, + const void *pvSrc, int nSrcSize, + const char *pszFields); + +extern int std_CopyBE(void *pvDest, int nDestSize, + const void *pvSrc, int nSrcSize, + const char *pszFields); + +// sorting utilities +extern void std_qsort(void* pElems, int nNumElems, int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +extern int std_bisect(const void* pElems, int nNumElems, int nElemWidth, + const void* pElem, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +extern void std_merge(void* vpDst, int nDst, + const void* vpA, int nA, + const void* vpB, int nB, + int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +extern int std_uniq(void* vpElems, int nNumElems, int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +#ifdef __cplusplus +} +#endif /* #ifdef __cplusplus */ + + +#define STD_SWAPS(us) \ + ((((us) & 0xff) << 8) + (((us) & 0xff00) >> 8)) + + +static __inline unsigned short std_swaps(unsigned short us) +{ + return STD_SWAPS(us); +} + +/* note, STD_SWAPL() requires that ul be an l-value, and destroyable. + this macro is not intended for use outside AEEstd.h */ +#define STD_SWAPL(ul) \ + (((ul) = (((ul) & 0x00ff00ff) << 8) | (((ul)>>8) & 0x00ff00ff)),(((ul) >> 16) | ((ul) << 16))) + +static __inline unsigned long std_swapl(unsigned long ul) +{ + return STD_SWAPL(ul); +} + +#ifdef AEE_BIGENDIAN +# define STD_HTONL(u) (u) +# define STD_HTONS(u) (u) +# define STD_HTOLEL(u) (STD_SWAPL(u)) +# define STD_HTOLES(u) (STD_SWAPS(u)) +#else +# define STD_HTONL(u) (STD_SWAPL(u)) +# define STD_HTONS(u) (STD_SWAPS(u)) +# define STD_HTOLEL(u) (u) +# define STD_HTOLES(u) (u) +#endif + +static __inline unsigned short std_letohs(unsigned short us) +{ + return STD_HTOLES(us); +} + +static __inline unsigned short std_htoles(unsigned short us) +{ + return STD_HTOLES(us); +} + +static __inline unsigned long std_letohl(unsigned long ul) +{ + return STD_HTOLEL(ul); +} + +static __inline unsigned long std_htolel(unsigned long ul) +{ + return STD_HTOLEL(ul); +} + +static __inline unsigned short std_ntohs(unsigned short us) +{ + return STD_HTONS(us); +} + +static __inline unsigned short std_htons(unsigned short us) +{ + return STD_HTONS(us); +} + +static __inline unsigned long std_ntohl(unsigned long ul) +{ + return STD_HTONL(ul); +} + +static __inline unsigned long std_htonl(unsigned long ul) +{ + return STD_HTONL(ul); +} + + +#undef STD_HTONL // private macro; not exported as a supported API +#undef STD_HTONS // private macro; not exported as a supported API +#undef STD_HTOLEL // private macro; not exported as a supported API +#undef STD_HTOLES // private macro; not exported as a supported API +#undef STD_SWAPS // private macro; not exported as a supported API +#undef STD_SWAPL // private macro; not exported as a supported API + + +/* +======================================================================= +MACROS DOCUMENTATION +======================================================================= + +STD_CONTSTRAIN() + +Description: + STD_CONTSTRAIN() constrains a number to be between two other numbers. + +Definition: + STD_CONSTRAIN( val, min, max ) \ + (((val) < (min)) ? (min) : ((val) > (max)) ? (max) : (val)) + +Parameters: + val: number to constrain + min: number to stay greater than or equal to + max: number to stay less than or equal to + +Evaluation Value: + the constrained number + +======================================================================= + +STD_BETWEEN() + +Description: + STD_BETWEEN() tests whether a number is between two other numbers. + +Definition: + STD_BETWEEN( val, minGE, maxLT ) \ + ((unsigned)((unsigned)(val) - (unsigned)(minGE)) < \ + (unsigned)((unsigned)(maxLT) - (unsigned)(minGE))) + +Parameters: + val: value to test + minGE: lower bound + maxLT: upper bound + +Evaluation Value: + 1 if val >= minGE and val < maxLT + +======================================================================= + +STD_ARRAY_SIZE() + +Description: + STD_ARRAY_SIZE() gives the number of elements in a statically allocated array. + +Definition: + STD_ARRAY_SIZE(a) (sizeof((a))/sizeof((a)[0])) + +Parameters: + a: array to test + +Evaluation Value: + number of elements in a + +======================================================================= + +STD_ARRAY_MEMBER() + +Description: + STD_ARRAY_MEMBER() tests whether an item is a member of a statically allocated array. + +Definition: + STD_ARRAY_MEMBER(p,a) (((p) >= (a)) && ((p) < ((a) + STD_ARRAY_SIZE(a)))) + +Parameters: + p: item to test + a: array to check + +Evaluation Value: + 1 if p is in a + +======================================================================= + +STD_OFFSETOF() + +Description: + STD_OFFSETOF() gives the offset of member of a struct. + +Definition: + STD_OFFSETOF(type,member) (((char *)(&((type *)0)->member))-((char *)0)) + +Parameters: + type: structured type + member: name of member in the struct + +Evaluation Value: + offset of member (in bytes) in type + +======================================================================= + +STD_RECOVER_REC() + +Description: + STD_RECOVER_REC() provides a safe cast from a pointer to a member + of a struct to a pointer to the containing struct + +Definition: + STD_RECOVER_REC(type,member,p) ((type*)(((char*)(p))-STD_OFFSETOF(type,member))) + +Parameters: + type: structured type + member: name of member in the struct + p: pointer to the member of the struct + +Evaluation Value: + a pointer of type type to the containing struct + +======================================================================= + +STD_MIN() + +Description: + STD_MIN() finds the smaller of two values. + +Definition: + STD_MIN(a,b) ((a)<(b)?(a):(b)) + +Parameters: + a, b: values to compare + +Evaluation Value: + smaller of a and b + +======================================================================= + +STD_MAX() + +Description: + STD_MAX() finds the larger of two values. + +Definition: + STD_MAX(a,b) ((a)>(b)?(a):(b)) + +Parameters: + a, b: values to compare + +Evaluation Value: + larger of a and b + +======================================================================= + +STD_ZEROAT() + +Description: + STD_ZEROAT() zero-initializes the contents of a typed chunk of memory. + +Definition: + STD_ZEROAT(p) std_memset((p), 0, sizeof(*p)) + +Parameters: + p: the chunk to initialize + +Evaluation Value: + p + +======================================================================= + +STD_BIT_SET() + +Description: + STD_BIT_SET(bits, ix) sets the bit in the memory stored in bits at + index ix + +Parameters: + bits: the memory address holding the bits + ix: the index of the bit to set; + +======================================================================= + +STD_BIT_CLEAR() + +Description: + STD_BIT_CLEAR(bits, ix) clears the bit in the memory stored in bits + at index ix + +Parameters: + bits: the memory address holding the bits + ix: the index of the bit to clear + +======================================================================= + +STD_BIT_TEST() + +Description: + STD_BIT_TEST(bits, ix) returns the bit in the memory stored in bits + at index ix + +Parameters: + bits: the memory address holding the bits + ix: the index of the bit to test + +Evaluation Value: + 0x1 if set 0x0 if not set + +===================================================================== +INTERFACES DOCUMENTATION +======================================================================= + +std Interface + +Description: + This library provides a set of general-purpose utility functions. + Functionality may overlap that of a subset of the C standard library, but + this library differs in a few respects: + + - Functions are fully reentrant and avoid use of static variables. + + - The library can be supported consistently across all environments. + Compiler-supplied libraries sometimes behave inconsistently and are + unavailable in some environments. + + - Omits "unsafe" functions. C standard library includes many functions + that are best avoided entirely: strcpy, strcat, strtok, etc. + + +======================================================================= + +std_getversion() + +Description: + + The std_getversion() copies the stdlib version to pcDst. This function + takes the size of the destination buffer as an argument and guarantees + to zero-terminate the result and not to overflow the nDestSize size. + + This function copies up to size-1 characters from the stdlib version + string to pcDest and NUL-terminates the pcDest string. + +Prototype: + int std_getversion(char *pcDst, int nDestSize) + + +Parameters: + pcDst : Destination string + nDestSize: Size of the destination buffer in bytes + +Return Value: + + Returns the length of the version string (in characters). + +======================================================================= + +std_strlen() + +Description: + The std_strlen() computes the length of the given string. + +Prototype: + int std_strlen(const char *cpszStr) + +Parameters: + cpszStr : String whose length will be computed + +Return Value: + Length of the string in characters that precede the terminating NULL character. + +======================================================================= + +std_strcmp() + +Description: + The std_strcmp() compares two NUL-terminated character strings. + Comparison is strictly by byte values with no character set + interpretation. + +Prototype: + + int std_strcmp(const char *s1, const char *s2); + +Parameters: + s1, s2: strings to compare + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +See Also: + std_wstrcmp + +======================================================================= + +std_strncmp() + +Description: + The std_strncmp() compares at most n bytes of two NUL-terminated character strings. + +Prototype: + + int std_strncmp(const char *s1, const char *s2, int n); + +Parameters: + s1, s2: strings to compare + n: maximum number of bytes to compare. if either s1 or s2 is + shorter than n, the function terminates there + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +See Also: + std_wstrncmp + +======================================================================= + +std_stricmp() + +Description: + The std_stricmp() compares two NUL-terminated character strings, case-folding any + ASCII characters. + +Prototype: + + int std_stricmp(const char *s1, const char *s2); + +Parameters: + s1, s2: strings to compare + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +======================================================================= + +std_strnicmp() + +Description: + The std_strnicmp() compares at most n bytes of 2 NUL-terminated character strings, + case-folding any ASCII characters. + +Prototype: + + int std_strnicmp(const char *s1, const char *s2, int n); + +Parameters: + s1, s2: strings to compare + n: maximum number of bytes to compare. if either s1 or s2 is + shorter than n, the function terminates there + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +======================================================================= + +std_strlcpy() + +Description: + + The std_strlcpy() copies pszSrc string to the pcDst. It is a safer + alternative to strcpy() or strncpy(). This function takes the size of the + destination buffer as an argument and guarantees to NUL-terminate the + result and not to overflow the nDestSize size. + + This function copies up to nDestSize-1 characters from the pszSrc string + to pcDest and NUL-terminates the pcDest string. + +Prototype: + int std_strlcpy(char *pcDst, const char *pszSrc, int nDestSize) + +Parameters: + pcDst : Destination string + pcSrc : Source string + nDestSize: Size of the destination buffer in bytes + +Return Value: + + Returns the length of the string (in characters) it tried to create, + which is same as length of pszSrc. + + Example: + + { + char buf[64]; + if (std_strlcpy(buf, file_name, STD_ARRAY_SIZE(buf) >= + STD_ARRAY_SIZE(buf)) { + //Truncated -- Handle overflow.... + } + } + +Comment: + + Unlike strlcpy, std_strlcpy accepts an integer size and does nothing when a + negative value is passed. When passing valid sizes for objects on our + supported platforms, this should not result in any observed difference. + However, calling strlcpy() with UINT_MAX will result in the entire source + string being copied, whereas std_strlcpy() will do nothing. Passing INT_MAX + to str_strlcpy() will achieve the same result (although both these cases are + bad practice since they defeat bounds checking). + + +======================================================================= + +std_strlcat() + +Description: + + The std_strlcat() function concatenates a string to a string already + residing in a buffer. It is a safer alternative to strcat() or strncat(). + This function takes the size of the destination buffer as an argument and + guarantees not to create an improperly terminated string and not to + overflow the nDestSize size. + + This function appends pszSrc to pcDst, copying at most nDestSize minus + the length of the string in pcDest minus 1 bytes, always NUL-terminating + the result. + + For compatibility with "strlcat()", std_strlcat() does *not* zero-terminate + the destination buffer in cases where the buffer lacks termination on entry + to the function. Do not rely on std_strlcat() to zero-terminate a buffer + that is not already zero-terminated; instead ensure that the buffer is + properly initialized using std_strlcpy() or some other means. + +Prototype: + + int std_strlcat(char *pcDst, const char *pszSrc, int nDestSize) + +Parameters: + + pcDst : Destination string + pcSrc : Source string + nDestSize: Size of the destination buffer in bytes + +Return Value: + + Returns the length of the string (in characters) it tried to create, + which is same as length of pszSrc plus the length of pszDest. + + Example: + + { + char buf[64]; + if (std_strlcat(buf, file_name, STD_ARRAY_SIZE(buf) >= + STD_ARRAY_SIZE(buf)) { + //Truncated -- Handle overflow.... + } + } + + +======================================================================= + +std_strstr() + +Description: + The std_strstr() finds the first occurrence of a substring in a string. + +Prototype: + + char * std_strstr(const char *pszString, const char *pszSearch); + +Parameters: + pszString: string to search + pszSearch: sub string to search for + +Return Value: + A pointer to the first character in the first occurrence of the substring if found, NULL otherwise + +======================================================================= + +std_tolower() + +Description: + The std_tolower() converts an uppercase letter to the corresponding + lowercase letter. + +Prototype: + char std_tolower(char c); + +Parameters: + c: A character. + +Return Value: + the corresponding lowercase letter if c is an ASCII character whose + value is representable as an uppercase letter, else the same character + c is returned. + +======================================================================= + +std_toupper() + +Description: + The std_toupper() converts an lowercase letter to the corresponding + uppercase letter. + +Prototype: + char std_toupper(char c); + +Parameters: + c: is a character. + +Return Value: + The corresponding uppercase letter if c is an ASCII character whose + value is representable as an lowercase letter; else the same character + c is returned. + +======================================================================= + +std_memset() + +Description: + The std_memset() sets each byte in a block of memory to a value. + +Prototype: + + void *std_memset(void *p, int c, int nLen); + +Parameters: + p: memory block to set + c: value to set each byte to + nLen: size of p in bytes + +Return Value: + p + +======================================================================= + +std_memmove() + +Description: + The std_memmove() copies a block of memory from one buffer to another. + +Prototype: + + void *std_memmove(void *pTo, const void *cpFrom, int nLen); + +Parameters: + pTo: destination buffer + cpFrom: source buffer + nLen: number of bytes to copy + +Return Value: + pTo + +======================================================================= + +std_memsmove() + +Description: + + Size bounded memory move. + + Moves bytes from the source buffer to the destination buffer. + + This function ensures that there will not be a copy beyond + the size of the destination buffer. + + This function should be used in preference to memscpy() if there + is the possiblity of source and destination buffers overlapping. + The result of the operation is defined to be as if the copy were from + the source to a temporary buffer that overlaps neither source nor + destination, followed by a copy from that temporary buffer to the + destination. + +Prototype: + + int std_memsmove(void *dst, int dst_size, const void *src, int src_size); + +Parameters: + @param[out] dst Destination buffer. + @param[in] dst_size Size of the destination buffer in bytes. + @param[in] src Source buffer. + @param[in] src_size Number of bytes to copy from source buffer. + +Return value: + The number of bytes copied to the destination buffer. It is the + caller's responsibility to check for trunction if it cares about it - + truncation has occurred if the return value is less than src_size. + A negative return value indicates an error + +======================================================================= + +std_memcmp() + +Description: + The std_memcmp() compares two memory buffers, byte-wise. + +Prototype: + + int std_memcmp(const void *a, const void *b, int length); + +Parameters: + a, b: buffers to compare + length: number of bytes to compare + +Return Value: + 0 if buffers are the same for nLength ~ + < 0 if a is less than b ~ + > 0 if a is greater than b + +======================================================================= + +std_memscpy - Size bounded memory copy. + +Description: + + Copies bytes from the source buffer to the destination buffer. + + This function ensures that there will not be a copy beyond + the size of the destination buffer. + + The result of calling this on overlapping source and destination + buffers is undefined. + +Prototype: + + int std_memscpy(void *dst, int dst_size, const void *src, int src_size); + +Parameters: + + @param[out] dst Destination buffer. + @param[in] dst_size Size of the destination buffer in bytes. + @param[in] src Source buffer. + @param[in] src_size Number of bytes to copy from source buffer. + +Return value: + + The number of bytes copied to the destination buffer. It is the + caller's responsibility to check for trunction if it cares about it - + truncation has occurred if the return value is less than src_size. + Returs a negative value on error. + +======================================================================= + +std_memchr() + +Description: + The std_memchr() finds the first occurrence of a character in a memory + buffer. + +Prototype: + + void *std_memchr(const void* s, int c, int n); + +Parameters: + s: buffer to search + c: value of byte to look for + n: size of s in bytes + +Return Value: + A pointer to the occurrence of c. NULL if not found. + +======================================================================= + +std_memstr() + +Description: + The std_memstr() finds the first occurrence of a substring in a memory + buffer. + +Prototype: + + void *std_memstr(const char* cpHaystack, const char* cpszNeedle, + int nHaystackLen); + +Parameters: + cpHaystack: buffer to search + cpszNeedle: NUL-terminated string to search for + nHaystackLen: size of cpHaystack in bytes + +Return Value: + a pointer to the first occurrence of cpszNeedle if found, + NULL otherwise + +Comments: + None + +Side Effects: + None + +See Also: + None + +======================================================================= + +std_memrchr() + +Description: + + The std_memrchr() finds the last occurrence of a character in a memory + buffer. + +Prototype: + + void *std_memrchr(const void* s, int c, int n); + +Parameters: + s: buffer to search + c: value of byte to look for + n: size of s in bytes + +Return Value: + a pointer to the last occurrence of c, NULL if not found + +======================================================================= + +std_memrchrbegin() + +Description: + The std_memrchrbegin() finds the last occurrence of a character in a + memory buffer. + +Prototype: + + void *std_memrchrbegin(const void* s, int c, int n); + +Parameters: + s: buffer to search + c: value of byte to look for + n: size of s in bytes + +Return Value: + a pointer to the last occurrence of c, or s if not found + +======================================================================= + +std_memchrend() + +Description: + The std_memchrend() finds the first occurrence of a character in a + memory buffer. + +Prototype: + + void *std_memchrend(const void* s, int c, int n); + +Parameters: + s: buffer to search + c: value of byte to look for + n: size of s in bytes + +Return Value: + a pointer to the occurrence of c, s + n if not found + +======================================================================= +std_memchrsend() + +Description: + The std_memchrsend() finds the first occurrence of any character in a + NUL-terminated list of characters in a memory buffer. + +Prototype: + + void *std_memchrend(const void* s, const char* cpszChars, int n); + +Parameters: + s: buffer to search + cpszChars: characters to look for + n: size of s in bytes + +Return Value: + a pointer to the first occurrence of one of cpszChars, s + n if not found + +======================================================================= + +std_strchr() + +Description: + The std_strchr() finds the first occurrence of a character in a + NUL-terminated string. + +Prototype: + + char *std_strchr(const char* s, int c); + +Parameters: + s: string to search + c: char to search for + +Return Value: + pointer to first occurrence, NULL if not found + +See Also: + std_wstrchr + +======================================================================= + +std_strchrs() + +Description: + The std_strchrs() searches s, a NUL-terminated string, for the first + occurrence of any characters in cpszSrch, a NUL-terminated list of + characters. + +Prototype: + + char *std_strchrs(const char* s, const char *cpszSrch); + +Parameters: + s: string to search + cpszSrch: a list of characters to search for + +Return Value: + first occurrence of any of cpszSrch, NULL if not found + +======================================================================= + +std_strrchr() + +Description: + The std_strrchr() finds the last occurrence of a character in a + NUL-terminated string. + +Prototype: + + char *std_strrchr(const char* s, int c); + +Parameters: + s: string to search + c: char to search for + +Return Value: + pointer to last occurrence, NULL if not found + +See Also: + std_wstrrchr + +======================================================================= + +std_strchrend() + +Description: + The std_strchrend() finds the first occurrence of a character in a + NUL-terminated string. + +Prototype: + + char *std_strchrend(const char* s, int c); + +Parameters: + s: string to search + c: char to search for + +Return Value: + pointer to first occurrence, s + std_strlen(s) if not found + +======================================================================= + +std_strchrsend() + +Description: + The std_strchrsend() searches s, a NUL-terminated string, for the first + occurrence of any characters in cpszSrch, a NUL-terminated list of + characters. + +Prototype: + + char *std_strchrsend(const char* s, const char* cpszSrch); + +Parameters: + s: string to search + cpszSrch: a list of characters to search for + +Return Value: + first occurrence of any of cpszSrch or s+strlen(s) if not found + +======================================================================= + +std_strends() + +Description: + The std_strends() tests whether a string ends in a particular suffix. + +Prototype: + + char *std_strends(const char* cpsz, const char* cpszSuffix); + +Parameters: + cpsz: string to test + cpszSuffix: suffix to test for + +Return Value: + the first character of cpsz+std_strlen(cpsz)-std_strlen(cpszSuffix) + if cpsz ends with cpszSuffix. NULL otherwise. + +======================================================================= + +std_striends() + +Description: + The std_striends() tests whether a string ends in a particular suffix, + case-folding ASCII characters. + +Prototype: + + char *std_striends(const char* cpsz, const char* cpszSuffix); + +Parameters: + cpsz: string to test + cpszSuffix: suffix to test for + +Return Value: + the first character of cpsz+std_strlen(cpsz)-std_strlen(cpszSuffix) + if cpsz ends with cpszSuffix. NULL otherwise. + +======================================================================= + +std_strbegins() + +Description: + The std_strbegins() tests whether a string begins with a particular + prefix string. + +Prototype: + + char *std_strbegins(const char* cpsz, const char* cpszPrefix); + +Parameters: + cpsz: string to test + cpszPrefix: prefix to test for + +Return Value: + cpsz + std_strlen(cpszPrefix) if cpsz does begin with cpszPrefix, + NULL otherwise + +======================================================================= + +std_stribegins() + +Description: + The std_stribegins() tests whether a string begins with a particular + prefix string, case-folding ASCII characters. + +Prototype: + + char *std_stribegins(const char* cpsz, const char* cpszPrefix); + +Parameters: + cpsz: string to test + cpszPrefix: prefix to test for + +Return Value: + cpsz + std_strlen(cpszPrefix) if cpsz does begin with cpszPrefix, + NULL otherwise + + +======================================================================= + +std_strcspn() + +Description: + The std_strcspn() function searches s, a NUL-terminated string, for + the first occurrence of any characters in cpszSrch, a NUL-terminated + list of characters. This function returns the length of the longest + initial substring of s which consists of characters not present in + cpszSrch. + +Prototype: + + int std_strcspn(const char* s, const char* cpszSrch); + +Parameters: + s: string to search + cpszSrch: a list of characters to search for + +Return Value: + The index into the string s of the first occurrence of any of the + characters in cpszSrch. If no match is found, then index of the + terminating NUL character is returned. + +See Also: + std_strspn, std_strchr, std_strchrs + +======================================================================= + +std_strspn() + +Description: + The std_strspn() functions searches s, a NUL-terminated string, for + the first occurrence of a character that matches none of the + characters in cpszSrch, a NUL-terminated list of characters. This + function returns the length of the longest initial substring of s + which consists of characters present in cpszSrch. + +Prototype: + + int std_strspn(const char* s, const char* cpszSrch); + +Parameters: + s: string to search + cpszSrch: a list of characters to search for + +Return Value: + The index into the string s of the first occurrence of any character + that matches none of the characters in cpszSrch. If all characters + in s are present in cpszSrch, the index of the terminating NUL + character is returned. + +See Also: + std_strcspn, std_strchr, std_strchrs + +======================================================================= + +std_wstrlcpy() + +Description: + + The std_wstrlcpy() function copies a string. It is equivalent to + str_strlcpy() except that it operates on wide (16-bit) character strings. + See std_strlcpy() for details. + + +Prototype: + + int std_wstrlcpy(AECHAR *pcDest, const AECHAR *pszSrc, int nDestSize); + +Parameters: + pcDst: destination string + pszSrc: source string + int nDestSize: size of pcDest __in AECHARs__ + +Return Value: + Returns the length of the string (in AECHARs) it tried to create, + which is same as length of pszSrc. + + Example: + + { + AECHAR buf[64]; + if (std_wstrlcpy(buf, file_name, STD_ARRAY_SIZE(buf)) >= + STD_ARRAY_SIZE(buf)) { + //Truncated -- Handle overflow.... + } + } + +See Also: + std_wstrlcat + +======================================================================= + +std_wstrlcat() + +Description: + + The std_wstrlcat() function concatenates two strings. It is equivalent to + std_strlcat() except that it operates on wide (16-bit) character strings. + See std_strlcat() for more information. + +Prototype: + int std_wstrlcat(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize) + +Parameters: + pcDst[out]: Destination string + pcSrc : Source string + nDestSize: Size of the destination buffer in AECHARs + +Return Value: + Returns the length of the string (in AECHARs) it tried to create, + which is same as length of pszSrc + the length of pszDest. + + Example: + + { + char buf[64]; + if (std_wstrlcat(buf, file_name, STD_ARRAY_SIZE(buf)) >= + STD_ARRAY_SIZE(buf)) { + //Truncated -- Handle overflow.... + } + } + +See Also: + std_wstrlcpy + +======================================================================= + +std_wstrncmp() + +Description: + + The std_wstrncmp() function compares up to a specified number of bytes + in two NUL-terminated strings. It is equivalent to std_strncmp() except + that it operates on wide (16-bit) character strings. + +Prototype: + int std_wstrncmp(const AECHAR* s1, const AECHAR* s2, int nLen); + +Parameters: + s1, s2: strings to compare + n: maximum number of AECHARs to compare. if either s1 or s2 is + shorter than n, the function terminates there. + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +See Also: + std_strncmp + +======================================================================= + +std_wstrcmp() + +Description: + The std_wstrcmp() compares two NUL-terminated strings. It is equivalent + to std_strncmp() except that it operates on wide (16-bit) character + strings. Comparison is strictly by byte values with no character set + interpretation. + +Prototype: + + int std_wstrcmp(const AECHAR* s1, const AECHAR* s2); + +Parameters: + s1, s2: strings to compare + +Return Value: + 0 if strings are the same ~ + < 0 if s1 is less than s2 ~ + > 0 if s1 is greater than s2 + +See Also: + std_strcmp + +======================================================================= + +std_wstrchr() + +Description: + This function is the wide string counterpart of std_strchr(). + The std_wstrchr() finds the first occurrence of a character in a + NUL-terminated wide (16-bit) character string. + +Prototype: + + AECHAR* std_wstrchr(const AECHAR* s, AECHAR ch); + +Parameters: + s: string to search + ch: char to search for + +Return Value: + pointer to first occurrence, NULL if not found + +See Also: + std_strchr + +======================================================================= + +std_wstrrchr() + +Description: + This function is the wide string counterpart of std_strrchr(). + The std_wstrrchr() finds the last occurrence of a character in a + NUL-terminated wide (16-bit) character string. + +Prototype: + + AECHAR* std_wstrrchr(const AECHAR* s, AECHAR ch); + +Parameters: + s: string to search + ch: char to search for + +Return Value: + pointer to last occurrence, NULL if not found + +See Also: + std_strrchr + +======================================================================= + +std_makepath() + +Description: + The std_makepath() constructs a path from a directory portion and a file + portion, using forward slashes, adding necessary slashes and deleting extra + slashes. This function guarantees NUL-termination of pszDest + +Prototype: + + int std_makepath(const char *cpszDir, const char *cpszFile, + char *pszDest, int nDestSize) + +Parameters: + cpszDir: directory part + cpszFile: file part + pszDest: output buffer + nDestSize: size of output buffer in bytes + +Return Value: + the required length to construct the path, not including + NUL-termination + +Comments: + The following list of examples shows the strings returned by + std_makepath() for different paths. + +Example: + + cpszDir cpszFile std_makepath() + "" "" "" + "" "/" "" + "/" "" "/" + "/" "/" "/" + "/" "f" "/f" + "/" "/f" "/f" + "d" "f" "d/f" + "d/" "f" "d/f" + "d" "/f" "d/f" + "d/" "/f" "d/f" + +See Also: + std_splitpath + +======================================================================= + +std_splitpath() + +Description: + The std_splitpath() finds the filename part of a path given an inclusive + directory, tests for cpszPath being in cpszDir. The forward slashes are + used as directory delimiters. + +Prototype: + + char *std_splitpath(const char *cpszPath, const char *cpszDir); + +Parameters: + cpszPath: path to test for inclusion + cpszDir: directory that cpszPath might be in + +Return Value: + the part of cpszPath that actually falls beneath cpszDir, NULL if + cpszPath is not under cpszDir + +Comments: + The std_splitpath() is similar to std_strbegins(), but it ignores trailing + slashes on cpszDir, and it returns a pointer to the first character of + the subpath. + + The return value of std_splitpath() will never begin with a '/'. + + The following list of examples shows the strings returned by + std_splitpath() for different paths. + +Example: + cpszPath cpszDir std_splitpath() + "" "" "" + "" "/" "" + "/" "" "" + "/" "/" "" + "/d" "d" null + "/d" "/" "d" + "/d/" "/d" "" + "/d/f" "/" "d/f" + "/d/f" "/d" "f" + "/d/f" "/d/" "f" + +See Also: + std_makepath + +======================================================================= + +std_cleanpath() + +Description: + The std_cleanpath() removes double slashes, ".", and ".." from + slash-delimited paths,. It operates in-place. + +Prototype: + + char *std_cleanpath(char *pszPath); + +Parameters: + pszPath[in/out]: path to "clean" + +Return Value: + pszPath + +Comments: + Passing an "fs:/" path to this function may produce undesirable + results. This function assumes '/' is the root. + +Examples: + pszPath std_cleanpath() + "", "", + "/", "/", + + // here"s, mostly alone + "./", "/", + "/.", "/", + "/./", "/", + + // "up"s, mostly alone + "..", "", + "/..", "/", + "../", "/", + "/../", "/", + + // fun with x + "x/.", "x", + "x/./", "x/", + "x/..", "", + "/x/..", "/", + "x/../", "/", + "/x/../", "/", + "/x/../..", "/", + "x/../..", "", + "x/../../", "/", + "x/./../", "/", + "x/././", "x/", + "x/.././", "/", + "x/../.", "", + "x/./..", "", + "../x", "/x", + "../../x", "/x", + "/../x", "/x", + "./../x", "/x", + + // double slashes + "//", "/", + "///", "/", + "////", "/", + "x//x", "x/x", + + +Side Effects: + None + +See Also: + None + + +======================================================================= + +std_basename() + +Description: + The std_basename() returns the filename part of a string, + assuming '/' delimited filenames. + +Prototype: + + char *std_basename(const char *cpszPath); + +Parameters: + cpszPath: path of interest + +Return Value: + pointer into cpszPath that denotes part of the string immediately + following the last '/' + +Examples: + cpszPath std_basename() + "" "" + "/" "" + "x" "x" + "/x" "x" + "y/x" "x" + "/y/x" "x" + + See Also: + None + +======================================================================= + +std_rand_next() + +Description: + The std_rand_next() generates pseudo-random bytes. + +Prototype: + + unsigned std_rand_next(unsigned uRand); + +Parameters: + uRand: a seed for the pseudo-random generator + +Return Value: + the next value in the generator from uRand + +Comments: + for best results, this function should be called with its last + generated output. + + This is an example of code to generate 256 bytes of pseudo-random data. + + This is not crypto quality and should not be used for key generation + and the like. + +Example: + { + unsigned rand_buf[256/sizeof(unsigned)]; + int i; + unsigned uLast = std_rand_next(uCurrentTime); + for (i = 0; i < STD_ARRAY_SIZE(rand_buf); i++) { + rand_buf[i] = (uLast = std_rand_next(uLast)); + } + } + +See Also: + std_rand() + +======================================================================= + +std_rand() + +Description: + The std_rand() functions generates pseudo-random bytes and places it + in an output buffer of specified size. + +Prototype: + + uint32 std_rand(uint32 uSeed, byte* pDest, int nSize); + +Parameters: + uSeed: A seed for the pseudo-random generator + pDest: The output buffer where the random bytes are placed. + nSize: The size in bytes of pDest. + +Return Value: + The new seed value that can be used in a subsequent call to + std_rand(). + +Comments: + + std_rand() is a linear congruent psuedo-random number generator that + is seeded using the input seed. This makes the ouput predictable if + you can determine (or influence) the seed value used. Furthermore, + the random sequence of bytes generated by two different calls to this + function will be identical if both the calls use the same seed value. + + This is not crypto quality and should not be used for key generation + and other cryptographic uses. + +See Also: + std_rand_next() + +======================================================================= + +std_CopyLE() + +Description: + + The std_CopyLE() function copies data while translating numeric values + between host byte ordering and "little endian" byte ordering. + + pvDest and pvSrc are NOT required to be 16 or 32-bit word aligned. + + Behavior is undefined when the destination and source arrays overlap, + except in the special case where pvDest and pvSrc are equal. In that case, + std_CopyLE() modifies the buffer in-place. + + When the target byte ordering (little endian) matches the host byte + ordering, in-place translations reduce to a no-op, and copies are + delegated directly to std_memmove(). + + +Prototype: + int std_CopyLE(void *pvDest, int nDestSize, + const void *pvSrc, int nSrcSize, + const char *pszFields); + +Parameters: + pvDest: Pointer to destination buffer. + nDestSize: Size of the destination buffer. + pvSrc: Pointer to buffer containing source data. + nSrcSize: Size of source data. + pszFields: Description of the fields that comprise the source data. + + Each field size is given by a positive decimal integer or one of + the following characters: "S", "L", "Q", or "*". The letters + denote fields that should be converted to the desired byte + ordering: + +===pre> + S : a 2 byte (16 bit) value. + L : a 4 byte (32 bit) value. + Q : a 8 byte (64 bit) value. +===/pre> + + An integer gives a number of bytes and "*" represents the + remainder of the pvSrc[] buffer. No reordering is performed on + data in these fields. + + Comparisons are case-sensitive. Behavior is undefined when + other characters are supplied in pszFields. + + For example: "L12S*" would be appropriate to copy a structure + containing a uint32 followed by a 12 byte character array, + followed by a uint16, followed by an arbitrary amount of + character data. + + If nSrcSize is greater than the structure size (total of all the + sizes in pszFields[]) then pvSrc[] is treated as an array of + structures, each of which is described by pszFields. + +Return Value: + + The number of bytes actually copied or translated in-place. This will be + the smaller of nDestSize and nSrcSize, or zero if one of them are negative. + + +======================================================================= + +std_CopyBE() + +Description: + + The std_CopyBE() function has the same semantics as std_CopyLE() except it + copies between host byte ordering and big-endian ("network") byte order. + + See std_CopyLE() for more details. + + +Prototype: + void *std_CopyBE(void *pvDest, const void *pvSrc, + int cbDest, int nItems, const char *pszFields); + +Parameters: + pvDest: Pointer to destination buffer. + nDestSize: Size of the destination buffer. + pvSrc: Pointer to buffer containing source data. + nSrcSize: Size of source data. + pszFields: Description of the fields that comprise the source data, + as defined in std_CopyLE. + +Return Value: + + The number of bytes actually copied or translated in-place. This will be + the smaller of nDestSize and nSrcSize, or zero if one of them are negative. + +======================================================================= + +std_swapl() + +Description: + The std_swapl() changes endianness of an unsigned long. + +Prototype: + + unsigned long std_swapl(unsigned long ul) + +Parameters: + ul: input unsigned long + +Return Value: + ul, reversed in byte-ordering + +======================================================================= + +std_swaps() + +Description: + The std_swaps() changes endianness of an unsigned short. + +Prototype: + + unsigned short std_swaps(unsigned short us) + +Parameters: + us: input unsigned short + +Return Value: + us, reversed in byte-ordering + +======================================================================= + +std_letohs() + +Description: + The std_letohs() changes a short from little-endian to host byte order. + +Prototype: + + unsigned short std_letohs(unsigned short us) + +Parameters: + us: short to convert + +Return Value: + us converted from little-endian to host byte order. If the + host is little endian, just returns us + +======================================================================= + +std_htoles() + +Description: + The std_htoles() converts a short from host byte-order to little-endian. + +Prototype: + + unsigned short std_htoles(unsigned short us) + +Parameters: + us: short to convert + +Return Value: + us converted from host byte order to little-endian. If the + host is little endian, just returns us + +======================================================================= + +std_letohl() + +Description: + The std_letohl() changes a long from little-endian to host byte order. + +Prototype: + + unsigned long std_letohl(unsigned long ul) + +Parameters: + ul: long to convert + +Return Value: + ul converted from little-endian to host byte order. If the + host is little endian, just returns ul + +======================================================================= + +std_htolel() + +Description: + The std_htolel() converts a long from host byte-order to little-endian. + +Prototype: + + unsigned long std_htolel(unsigned long ul) + +Parameters: + ul: long to convert + +Return Value: + ul converted from host byte order to little-endian. If the + host is little endian, just returns ul. + + +======================================================================= + +std_ntohs() + +Description: + The std_ntohs() changes a short from big-endian to host byte order. + +Prototype: + + unsigned short std_ntohs(unsigned short us) + +Parameters: + us: short to convert + +Return Value: + us converted from big-endian to host byte order. If the + host is big endian, just returns us. + +======================================================================= + +std_htons() + +Description: + The std_htons() converts a short from host byte-order to big-endian. + +Prototype: + + unsigned short std_htons(unsigned short us) + +Parameters: + us: short to convert + +Return Value: + us converted from host byte order to big-endian. If the + host is big endian, just returns us. + +======================================================================= + +std_ntohl() + +Description: + The std_ntohl() changes a long from big-endian to host byte order. + +Prototype: + + unsigned long std_ntohl(unsigned long ul) + +Parameters: + ul: long to convert + +Return Value: + ul converted from big-endian to host byte order. If the + host is big endian, just returns ul. + +======================================================================= + +std_htonl() + +Description: + The std_htonl() converts a long from host byte-order to big-endian. + +Prototype: + + unsigned long std_htonl(unsigned long ul) + +Parameters: + ul: long to convert + +Return Value: + ul converted from host byte order to big-endian. If the + host is big endian, just returns ul. + + +======================================================================= + +std_strlprintf() + +Description: + + The functions std_strlprintf() and std_vstrlprintf() write formatted + output to a string. These functions guarantee NUL-termination of + the output buffer when its size is greater than zero. + + A format string is copied to the output buffer, except for conversion + specifiers contained within the format string. Conversion specifiers + begin with a "%" and specify some action that consumes an argument from + the argument list. + + Conversion specifiers have the following form: +===pre> + %[FLAGS] [WIDTH] [.PRECISION] [TYPE] CONV +===/pre> + + CONV is the only required field. It is always a single character, + and determines the action to be taken. Supported values are: + +===pre> + CONV | Description + ======|======================================================= + c | Output a single character. + | + s | Output a NUL-terminated single-byte character string. + | + d, i | Ouptut a signed decimal integer. + | + u | Output an unsigned decimal integer. + | + o | Output an unsigned octal integer. + | + x | Output an unsigned hexadecimal integer, using + | lower case digits. + | + X | Output an unsigned hexadecimal integer, using + | upper case digits. + | + p | Output a pointer value as eight hexadecimal digits, + | using upper case digits. +===/pre> + + The next argument from the argument list supplies the value to be + formatted and output. + + FLAGS, WIDTH, and PRECISION can modify the formatting of the value. + + FLAGS consists of one or more of the following characters: + +===pre> + Flag | Meaning + =====|================================================================= + + | Prefix positive numbers with "+" (%d and %i only). + -----|----------------------------------------------------------------- + - | When padding to meet WIDTH, pad on the right. + -----|----------------------------------------------------------------- + 0 | Pad with '0' characters when padding on the left to meet WIDTH. + -----|----------------------------------------------------------------- + blank| Prefix positive numbers with " " (%d and %i only). + space| + -----|----------------------------------------------------------------- + # | With %x or %X: prefixes non-zero values with "0x"/"0X". + | With %o, ensure the value begins with "0" (increasing PRECISION + | if necessary). + | Ignored for all other CONV specifiers. + -----|----------------------------------------------------------------- +===/pre> + + WIDTH is an unsigned decimal integer or the character "*". + + WIDTH gives the minimum number of characters to be written. The + formatted value will be padded with spaces until the minimum size is + met; it never causes a value to be truncated The sign of the WIDTH + integer selects between left and right padding. Padding will be on + the left unless the "-" flag is specified. + + When "*" is used, an 'int' argument is consumed from the argument + list and used as the WIDTH. A negative argument specifies padding on + the right, and its absolute value gives the amount of padding. + + If the "0" flags is specified, any padding on the left will consist + of "0" characters. An exception to this rule is that the "0" flag is + ignored when precision is specified for a numeric value. + + PRECISION is a non-negative decimal integer or "*" preceded by ".". + + When PRECISION accompanies any of the numeric conversions, it + specifies the minimum number of digits to output. Values are padded + on the left with '0' to meet the specified size. PRECISION defaults + to 1 for numbers. + + When PRECISION accompanies other conversions, it specifies the + maximum number of characters from the value to output. The value + will be truncated to ensure that at most PRECISION characters are + output. + + TYPE provides information about the type of arguments. This is used + to determine the size of integer arguments. Values larger than 'int' + can be properly obtained from the argument list. Their behavior + should be considered undefined for CONV operations other than integer + formatting. + +===pre> + TYPE | Meaning + =======|===================== + hh | sizeof(char) + -------|--------------------- + h | sizeof(short) + -------|--------------------- + l | sizeof(long) + -------|--------------------- + L, ll | sizeof(long long) + -------|--------------------- + j | sizeof(int64) + -------|--------------------- + z | sizeof(size_t) + -------|--------------------- +===/pre> + + For 64-bit integers, "ll" may be the most widely-supported type + specifier in other printf implementation, but "j" has been introduced + in ISO C99. This implementation supports both. + + Note that arguments to variadic functions are promoted to 'int' when + smaller than 'int', so 'h' and 'hh' have no observable effect. + Static analysis tools that understand standard format string syntax + may use this information for other purposes. + +Prototype: + + int std_strlprintf(char *pszDest, int nDestSize, + const char *pszFmt, ...); +Parameters: + pszDest [out]: output buffer, where output will be placed + nDestSize: size of pszDest in bytes + pszFmt: format string + +Return Value: + + The size required to hold the entire untruncated output, NOT + including NUL-termination. + +Comments: + + Notable omissions from std_strlprintf() are lack of support for + floating point and lack of support for "%n". + +Side Effects: + None + +See Also: + None + +======================================================================= + +std_vstrlprintf() + +Description: + + The std_vstrlprintf() is documented with std_strlprintf(), it's the + vector form of std_strlprintf(). See std_strlprintf() for a + more complete description. + +Prototype: + int std_vstrlprintf(char *pszDest, int nDestSize, + const char *pszFmt, AEEVaList args); + +Parameters: + pszDest [out]: output buffer, where output will be placed + nDestSize: size of pszDest in bytes + pszFmt: format string + args: arguments + + +======================================================================= + +std_snprintf() + +Description: + + The functions std_snprintf() and std_vsnprintf() are similar to + std_strlprintf and std_vstrlprintf that write formatted output to a + string. Unlike std_strlprintf, std_snprintf also support the floating + point conversion specifiers. These functions guarantee NUL-termination + of the output buffer when its size is greater than zero. + + A format string is copied to the output buffer, except for conversion + specifiers contained within the format string. Conversion specifiers + begin with a "%" and specify some action that consumes an argument from + the argument list. + + Conversion specifiers have the following form: +===pre> + %[FLAGS] [WIDTH] [.PRECISION] [TYPE] CONV +===/pre> + + CONV is the only required field. It is always a single character, + and determines the action to be taken. For a detailed description of + conversion sepcifiers, please refer to the documentation of + std_strlprintf(). Here. we only provide description of these fields + as it applies to the additional CONV values supported by + std_snprintf(). + + In addition to the values for CONV supported by std_strlprintf, this + function supports the following values: + +===pre> + CONV | Description + ======|======================================================= + e, E | Outputs a double value representing a floating point + | number in the style [-]d.ddd e±dd, where there is one + | digit (which is nonzero if the argument is nonzero) + | before the decimal-point character and the number of + | digits after it is equal to the precision. If the + | precision is missing, it is taken as 6. If the precision + | is zero and the # flag is not specified, no decimal-point + | character appears. The value is rounded to the appropriate + | number of digits. The E conversion specifier produces a + | number with E instead of e introducing the exponent. The + | exponent always contains at least two digits, and only as + | many more digits as necessary to represent the exponent. + | If the value is zero, the exponent is zero. + | + f, F | Outputs a double value representing a floating point + | number in the style [-]ddd.ddd, where the number of + | digits after the decimal-point character is equal to the + | precision specification. If the precision is missing, it + | is taken as 6. If the precision is zero and the # flag is + | not specified, no decimal-point character appears. If a + | decimal-point character appears, at least one digit + | appears before it. The value is rounded to the appropriate + | number of digits. + | + g, G | Outputs a double value representing a floating point + | number in the style f or e (or in style F or E in the case + | of a G conversion specifier), with the precision specifying + | the number of significant digits. If the precision is zero, + | it is taken as 1. The style used depends on the value + | converted. Style e (or E) is used only if the exponent + | resulting from such a conversion is less than -4 or greater + | than or equal to the precision. Trailing zeros are removed + | from the fractional portion of the result unless the # flag + | is specified; a decimal-point character appears only if it + | is followed by a digit. + | + a, A | Outputs a double value representing a floating point + | number in the style [-]0xh.hhhh p±d, where there is one + | non-zero hexadecimal digit before the decimal-point + | character and the number of hexadecimal digits after it is + | equal to the precision. If the precision is missing then + | the precision is assumed to be sufficient for an exact + | representation of the value, except that trailing zeros + | may be omitted. If the precision is zero and the # flag is + | not specified, no decimal point character appears. The + | letters 'abcdef' are used for '%a' conversion and the + | letters ABCDEF for '%A' conversion. The '%A' conversion + | specifier produces a number with 'X' and 'P' instead of 'x' + | and 'p'. The exponent always contains at least one digit, + | and only as many more digits as necessary to represent the + | decimal exponent of 2. If the value is zero, the exponent + | is zero. + | +===/pre> + + For 'e', 'f', 'g' and 'a' convervsion specifiers, a double argument + representing an infinity is converted in to the style '[-]inf' and + a double argument representing a NaN is converted in to the stlye + 'nan'. The 'E', 'F', 'G' and 'A' conversion specifiers result in + 'INF' or 'NAN' instead of 'inf' or 'nan', respectively. + +Prototype: + + int std_snprintf(char *pszDest, int nDestSize, + const char *pszFmt, ...); +Parameters: + pszDest [out]: output buffer, where output will be placed + nDestSize: size of pszDest in bytes + pszFmt: format string + +Return Value: + + The size required to hold the entire untruncated output, NOT + including NUL-termination. + +Comments: + + Notable omissions from std_strlprintf() lack of support for "%n". + +Side Effects: + None + +See Also: + std_strlprintf() + +======================================================================= + +std_vsnprintf() + +Description: + + The std_vsnprintf() is documented with std_snprintf(), it's the + vector form of std_snprintf(). See std_snprintf() for a more complete + description. + +Prototype: + int std_vsnprintf(char *pszDest, int nDestSize, + const char *pszFmt, AEEVaList args); + +Parameters: + pszDest [out]: output buffer, where output will be placed + nDestSize: size of pszDest in bytes + pszFmt: format string + args: arguments + + +======================================================================= + +std_scanul() + +Description: + + The std_scanul() converts an ASCII representation of a number to an unsigned + long. It expects strings that match the following pattern: +===pre> + spaces [+|-] digits +===/pre> + + 'Spaces' is zero or more ASCII space or tab characters. + + 'Digits' is any number of digits valid in the radix. Letters 'A' through + 'Z' are treated as digits with values 10 through 35. 'Digits' may begin + with "0x" when a radix of 0 or 16 is specified. + + Upper and lower case letters can be used interchangeably. + + +Prototype: + + uint32 std_scanul( const char *pchBuf, int nRadix, const char **ppchEnd, + int *pnError) + +Parameters: + + pchBuf [in] : the start of the string to scan. + + nRadix [in] : the numeric radix (or base) of the number. Valid values are + 2 through 36 or zero, which implies auto-detection. + Auto-detection examines the digits field. If it begins with + "0x", radix 16 is selected. Otherwise, if it begins with + "0" radix 8 is selected. Otherwise, radix 10 is selected. + + ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first + character that did not match the expected pattern shown + above, except on STD_BADPARAM and STD_OVERFLOW when it is + set to the start of the string. + + pnError [out] : If pnError is not NULL, *pnError holds the error code, + which is one of the following: +~ + 0 : Numeric value is from 0 to MAX_UINT32. + + STD_NEGATIVE : The scanned value was negative and its absolute value was + from 1 to MAX_UINT32. The result is the negated value + (cast to a uint32). + + STD_NODIGITS : No digits were found. The result is zero. + + STD_OVERFLOW : The absolute value exceeded MAX_UINT32. The result + is set to MAX_UINT32 and *ppchEnd is set to pchBuf. + + STD_BADPARAM : An improper value for nRadix was received. The result + is set to zero, and *ppchEnd is set to pchBuf. +* + +Return Value: + + The converted numeric result. + +Comments: + + The std_scanul() is similar to ANSI C's strtoul() but differs in the following + respects: + + 1. It returns an error/success code. strtoul() results are ambiguous + unless the caller sets errno to zero before calling it. + + 2. std_scanul() is free of references to current locale and errno. Some + strtoul() implementations use locale; some don't. + + 3. It provides more complete reporting of range underflow. strtoul() + does not distinguish between "-1" and "0xFFFFFFFF", and underflow is + poorly defined. + + 4. std_scanul() reports a "no digits" error code to distinguish "0" from + whitespace, "+", etc.. + +See Also: + + std_scanull() + +======================================================================= + +std_scanull() + +Description: + + The std_scanull() converts an ASCII representation of a number to an + unsigned long long. It expects strings that match the following pattern: +===pre> + spaces [+|-] digits +===/pre> + + 'Spaces' is zero or more ASCII space or tab characters. + + 'Digits' is any number of digits valid in the radix. Letters 'A' through + 'Z' are treated as digits with values 10 through 35. 'Digits' may begin + with "0x" when a radix of 0 or 16 is specified. + + Upper and lower case letters can be used interchangeably. + + +Prototype: + + uint64 std_scanull(const char *pchBuf, int nRadix, const char **ppchEnd, + int *pnError) + +Parameters: + + pchBuf [in] : the start of the string to scan. + + nRadix [in] : the numeric radix (or base) of the number. Valid values are + 2 through 36 or zero, which implies auto-detection. + Auto-detection examines the digits field. If it begins with + "0x", radix 16 is selected. Otherwise, if it begins with + "0" radix 8 is selected. Otherwise, radix 10 is selected. + + ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first + character that did not match the expected pattern shown + above, except on STD_BADPARAM and STD_OVERFLOW when it is + set to the start of the string. + + pnError [out] : If pnError is not NULL, *pnError holds the error code, + which is one of the following: +~ + 0 : Numeric value is from 0 to MAX_UINT64. + + STD_NEGATIVE : The scanned value was negative and its absolute value was + from 1 to MAX_UINT64. The result is the negated value + (cast to a uint64). + + STD_NODIGITS : No digits were found. The result is zero. + + STD_OVERFLOW : The absolute value exceeded MAX_UINT64. The result + is set to MAX_UINT64 and *ppchEnd is set to pchBuf. + + STD_BADPARAM : An improper value for nRadix was received. The result + is set to zero, and *ppchEnd is set to pchBuf. +* + +Return Value: + + The converted numeric result. + +Comments: + + The std_scanull() is similar to ANSI C's strtoull() but differs in the following + respects: + + 1. It returns an error/success code. strtoull() results are ambiguous + unless the caller sets errno to zero before calling it. + + 2. std_scanull() is free of references to current locale and errno. Some + strtoull() implementations use locale; some don't. + + 3. It provides more complete reporting of range underflow. strtoul() + does not distinguish between "-1" and "0xFFFFFFFFFFFFFFFF", and underflow + is poorly defined. + + 4. std_scanull() reports a "no digits" error code to distinguish "0" from + whitespace, "+", etc.. + +See Also: + + std_scanul() + +======================================================================= + +std_qsort() + +Description: + + An implementation of the quicksort algorithm, a massively recursive, + in-place sorting algorithm for an array. + + The contents of the array are sorted in ascending order according to + the comparison function pointed to by pfnCompare. + + pfnCompare must return a value less than, equal to, or + greater than zero if the first argument is considered to be + less than, equal to, or greater than the second, respectively. + + std_qsort() is not a stable sort. + +Prototype: + void std_qsort(void* pElems, int nNumElems, int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + + +Parameters: + pElems: array of elements to be sorted in place. It's size + must be nNumElems * nElemWidth in bytes. + nNumElems: number of elements in pElems + nElemWidth: the width, in bytes of each element of pElems + pfnCompare: callback comparison function, should return 0, less than + zero or greater than zero if the left comparand is equal to, less + than, or greater than, the right comparand, respectively. + pCompareCx: the context passed as the first parameter by pfnCompare + +Return Value: + None + +Comments: + If nElemWidth is 2, 4, or 8, pElems is accessed internally as + integer values for the purposes of reading and writing elements. + Therefore, pElems must be aligned on a memory boundary compatible + with integer access of the array elements. I.e. if you pass 4 as + nElemWidth, *(int*)pElems must succeed. + +======================================================================= + +std_bisect() + +Description: + + Find an element in a sorted array of elements. Uses a binary + search. + +Prototype: + int std_bisect(const void* pElems, int nNumElems, int nElemWidth, + const void* pElemFind, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +Parameters: + pElems: array of elements to be searched. It's size + must be nNumElems * nElemWidth in bytes. + nNumElems: number of elements in pElems + nElemWidth: the width, in bytes of each element of pElems + pElemFind: the element value to find in the array + pfnCompare: callback comparison function, should return 0, less than + zero or greater than zero if the left comparand is equal to, less + than, or greater than, the right comparand, respectively. + pCompareCx: the context passed as the first parameter by pfnCompare + +Return Value: + index of the element such that pElems[index] <= elem < pElems[index + 1] + nNumElems if elem is greater than all the elements in the list + 0 if the elem is less than or equal to the all the elements in the list + +======================================================================= + +std_merge() + +Description: + + Merge two sorted arrays into another array. + +Prototype: + void std_merge(void* vpDst, int nDst, + const void* vpA, int nA, + const void* vpB, int nB, + int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +Parameters: + vpDst: destination array. It's size must be nDst * nElemWidth in bytes. + nDst: number of elements that vpDst can accomodate + vpA: array of elements to be merged, it's size must be nA * nElemWidth + in bytes. + nA: number of elements in vpA + vpB: array of elements to be merged, it's size must be nB * nElemWidth + in bytes. + nB: number of elements in vpB + nElemWidth: the width, in bytes of each element of pElems + pfnCompare: callback comparison function, should return 0, less than + zero or greater than zero if the left comparand is equal to, less + than, or greater than, the right comparand, respectively. + pCompareCx: the context passed as the first parameter by pfnCompare + +Return Value: + none + +======================================================================= + +std_uniq() + +Description: + Removes duplicate entries from a sorted array. + +Prototype: + int std_uniq(void* vpElems, int nNumElems, int nElemWidth, + int (*pfnCompare)(void*, const void*, const void*), + void* pCompareCx); + +Parameters: + pElems: array of elements to be searched. It's size + must be nNumElems * nElemWidth in bytes. + nNumElems: number of elements in pElems + nElemWidth: the width, in bytes of each element of pElems + pfnCompare: callback comparison function, should return 0, less than + zero or greater than zero if the left comparand is equal to, less + than, or greater than, the right comparand, respectively. + pCompareCx: the context passed as the first parameter by pfnCompare + +Return Value: + the number of uniq elements left in vpElems + +======================================================================= + +std_scand() + +Description: + + The std_scand() converts the initial portion of an input ASCII string + to it's corresponding floating point value. It expects the input + string to match the following pattern: +===pre> + <Spaces><Subject String><Rest Of The String> +===/pre> + + 'Spaces' - is zero or more ASCII space or tab characters. + 'Subject String' - is the part of the input string that represents a + valid floating point constant. + 'Rest Of The String' - is the remaining sequence of one or more + characters including the terminating null + character of the input string. + + A valid subject string can be one of the following: + -- <NAN>, ignoring case. This is interpreted as a quiet NAN. + -- [+|-]<INF|INFINITY>, ignoring case. This is interpreted as an + infinity. + -- [+|-]<Valid Floating Point Number> + + In general, a valid floating poing number can either be a decimal + number or an hexadecimal number, and has the following form: + <Integral Part>[.[<Fractional Part>]][<Exponent>] + where the intergral, fractional and the exponent part may consist of + sequence of valid decimal or hexadecimal digits. More specifically: + + For a decimal floating point number: + 'Integral Part' - <Decimal Digits> + 'Fractional Part' - <Decimal Digits> + 'Exponent' - <e|E><Decimal Digits> + For a hexadecimal floating point number: + 'Integral Part' - <Hexadecimal Digits> + 'Fractional Part' - <Hexadecimal Digits> + 'Exponent' - <p|P><Decimal Digits> + + where: + 'Decimal Digits' - is any number of digits in the range [0,10]. + 'Hexadecimal Digits' - is any number of digits in the range [0,10] + or the alphabets A through F. + 'e','E','p','P' - represent the exponent characters + +Prototype: + + double std_scand(const char *pchBuf, const char **ppchEnd); + +Parameters: + + pchBuf [in] : the start of the string to scan. + + ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first + character after the parsed number. + +Return Value: + + This function returns the converted numeric result. If the string + does not contain a valid floating point number then the function + returns zero. If the converted value is outside the range of + representable values (overflow), [-]INFINITY is + returned. In case of an underflow, the function returns zero. + +=======================================================================*/ + +#endif // AEESTD_H + + |