Google Git
Sign in
android / platform / external / fastrpc / d9d953a35f7b0309f5670349ca1aef7840b599da / . / inc / AEEstd.h
blob: 2c832e6caba0fa2ba6520c1406e8567cbaa99085 [file] [log] [blame]
/**
* 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