xref: /aosp_15_r20/external/fastrpc/inc/AEEstd.h (revision 418b791d679beb2078b579a3b6936cf330c41799)

/**
 * 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