• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /**
2  * Copyright (c) 2019, The Linux Foundation. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *    * Redistributions of source code must retain the above copyright
8  *      notice, this list of conditions and the following disclaimer.
9  *    * Redistributions in binary form must reproduce the above
10  *      copyright notice, this list of conditions and the following
11  *      disclaimer in the documentation and/or other materials provided
12  *      with the distribution.
13  *    * Neither the name of The Linux Foundation nor the names of its
14  *      contributors may be used to endorse or promote products derived
15  *      from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
18  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
20  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
21  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
24  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
26  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
27  * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29 
30 #ifndef AEESTD_H
31 #define AEESTD_H
32 /*====================================================================
33 
34 DESCRIPTION:  Standard library; general-purpose utility functions.
35 
36 ====================================================================*/
37 #include "AEEVaList.h"
38 #include "AEEStdDef.h"
39 #include "string.h"
40 
41 #define STD_CONSTRAIN( val, min, max ) (((val) < (min)) ? (min) : ((val) > (max)) ? (max) : (val))
42 #define STD_BETWEEN( val, minGE, maxLT ) \
43                    ( (unsigned long)((unsigned long)(val) - (unsigned long)(minGE)) < \
44                    (unsigned long)((unsigned long)(maxLT) - (unsigned long)(minGE)) )
45 #define STD_ARRAY_SIZE(a)             ((int)((sizeof((a))/sizeof((a)[0]))))
46 #define STD_ARRAY_MEMBER(p,a) (((p) >= (a)) && ((p) < ((a) + STD_ARRAY_SIZE(a))))
47 
48 #define STD_SIZEOF(x)                 ((int)sizeof(x))
49 #define STD_OFFSETOF(type,member)     (((char*)(&((type*)1)->member))-((char*)1))
50 
51 #define STD_RECOVER_REC(type,member,p) ((void)((p)-&(((type*)1)->member)),\
52                                         (type*)(void*)(((char*)(void*)(p))-STD_OFFSETOF(type,member)))
53 #define STD_MIN(a,b)   ((a)<(b)?(a):(b))
54 #define STD_MAX(a,b)   ((a)>(b)?(a):(b))
55 //lint -emacro(545,STD_ZEROAT)
56 #define STD_ZEROAT(p)  std_memset((p), 0, sizeof(*p))
57 
58 #define _STD_BITS_PER(bits)     (8*sizeof((bits)[0]))
59 
60 #define STD_BIT_SET(bits, ix)     ((bits)[(ix)/_STD_BITS_PER((bits))] |= 0x1<<((ix) & (_STD_BITS_PER((bits))-1)))
61 #define STD_BIT_CLEAR(bits, ix)   ((bits)[(ix)/_STD_BITS_PER((bits))] &= ~(0x1<<((ix) & (_STD_BITS_PER((bits))-1))))
62 #define STD_BIT_TEST(bits, ix)    ((bits)[(ix)/_STD_BITS_PER((bits))] & (0x1<<((ix) & (_STD_BITS_PER((bits))-1))))
63 
64 //
65 // Error codes
66 //
67 #define STD_NODIGITS   1
68 #define STD_NEGATIVE   2
69 #define STD_OVERFLOW   3
70 #define STD_BADPARAM   4
71 #define STD_UNDERFLOW  5
72 
73 //Compute string length using strlen
74 #define std_strlen strlen
75 
76 #ifdef __cplusplus
77 extern "C" {
78 #endif /* #ifdef __cplusplus */
79 
80 //Version function
81 extern int           std_getversion(char *pcDst, int nDestSize);
82 
83 //String functions
84 extern int           std_strcmp(const char *s1, const char *s2);
85 extern int           std_strncmp(const char *s1, const char *s2, int n);
86 extern int           std_stricmp(const char *s1, const char *s2);
87 extern int           std_strnicmp(const char *s1, const char *s2, int n);
88 extern int           std_strlcpy(char *pcDst, const char *pszSrc, int nDestSize);
89 extern int           std_strlcat(char *pcDst, const char *pszSrc, int nDestSize);
90 extern char *        std_strstr(const char *pszString, const char *pszSearch);
91 
92 //Character functions
93 extern char          std_tolower(char c);
94 extern char          std_toupper(char c);
95 
96 // Mem functions
97 extern void *        std_memset(void *p, int c, int nLen);
98 extern void *        std_memmove(void *pTo, const void *cpFrom, int nLen);
99 extern int           std_memscpy(void *dst, int dst_size, const void *src, int src_size);
100 extern int           std_memsmove(void *dst, int dst_size, const void *src, int src_size);
101 extern int           std_memcmp(const void *a, const void *b, int length);
102 extern void *        std_memchr(const void* s, int c, int n);
103 extern void *        std_memstr(const char* cpHaystack, const char* cpszNeedle, int nHaystackLen);
104 extern void *        std_memrchr(const void* s, int c, int n);
105 extern void *        std_memrchrbegin(const void* p, int c, int nLen);
106 extern void *        std_memchrend(const void* cpcSrch, int c, int nLen);
107 extern void *        std_memchrsend(const void *cpSrch, const char* cpszChars, int nLen);
108 
109 //Other String functions
110 extern char *        std_strchr(const char* s, int c);
111 extern char *        std_strchrs(const char* sSrch, const char *sChars);
112 extern char *        std_strrchr(const char* s, int c);
113 extern char *        std_strchrend(const char *cpszSrch, char c);
114 extern char *        std_strchrsend(const char* s, const char* cpszSrch);
115 extern char *        std_strends(const char* cpsz, const char* cpszSuffix);
116 extern char *        std_striends(const char* cpsz, const char* cpszSuffix);
117 extern char *        std_strbegins(const char* cpsz, const char* cpszPrefix);
118 extern char *        std_stribegins(const char* cpsz, const char* cpszPrefix);
119 extern int           std_strcspn(const char* s, const char* cpszSrch);
120 extern int           std_strspn(const char* s, const char* cpszSrch);
121 
122 //Wide char string functions
123 extern int           std_wstrlen(const AECHAR *s);
124 extern int           std_wstrlcpy(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize);
125 extern int           std_wstrlcat(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize);
126 extern int           std_wstrncmp(const AECHAR* s1, const AECHAR* s2, int nLen);
127 extern int           std_wstrcmp(const AECHAR* s1, const AECHAR* s2);
128 extern AECHAR*       std_wstrchr(const AECHAR* cpwszText, AECHAR ch);
129 extern AECHAR*       std_wstrrchr(const AECHAR* cpwszText, AECHAR ch);
130 
131 //Path functions
132 extern int           std_makepath(const char *cpszDir,
133                                   const char *cpszFile,
134                                   char *pszDest, int nDestSize);
135 extern char *        std_splitpath(const char *cpszPath, const char *cpszDir);
136 extern char *        std_cleanpath(char *pszPath);
137 extern char *        std_basename(const char *pszPath);
138 
139 //Inet functions, number functions
140 extern unsigned int        std_scanul(const char *pchBuf, int nRadix,
141                                 const char **ppchEnd, int *pnError);
142 extern uint64        std_scanull(const char *pchBuf, int nRadix,
143                                  const char **ppchEnd, int *pnError);
144 extern double        std_scand(const char *pchBuf, const char **ppchEnd);
145 
146 // Rand functions
147 extern unsigned      std_rand_next(unsigned uRand);
148 extern uint32        std_rand(uint32 uSeed, byte* pDest, int nSize);
149 
150 
151 // printf functions
152 extern int           std_vstrlprintf(char *pszDest, int nDestSize,
153                                      const char *pszFmt, AEEVaList args);
154 
155 extern int           std_strlprintf(char *pszDest, int nDestSize,
156                                     const char *pszFmt, ...);
157 
158 extern int           std_vsnprintf(char *pszDest, int nDestSize,
159                                    const char *cpszFmt, AEEVaList args);
160 
161 extern int           std_snprintf(char *pszDest, int nDestSize,
162                                   const char *pszFmt, ...);
163 
164 // endian swapping functions
165 extern int           std_CopyLE(void *pvDest,       int nDestSize,
166                                 const void *pvSrc,  int nSrcSize,
167                                 const char *pszFields);
168 
169 extern int           std_CopyBE(void *pvDest,      int nDestSize,
170                                 const void *pvSrc, int nSrcSize,
171                                 const char *pszFields);
172 
173 // sorting utilities
174 extern void  std_qsort(void* pElems, int nNumElems, int nElemWidth,
175                        int (*pfnCompare)(void*, const void*, const void*),
176                        void* pCompareCx);
177 
178 extern int   std_bisect(const void* pElems, int nNumElems, int nElemWidth,
179                         const void* pElem,
180                         int (*pfnCompare)(void*, const void*, const void*),
181                         void* pCompareCx);
182 
183 extern void  std_merge(void* vpDst, int nDst,
184                        const void* vpA, int nA,
185                        const void* vpB, int nB,
186                        int nElemWidth,
187                        int (*pfnCompare)(void*, const void*, const void*),
188                        void* pCompareCx);
189 
190 extern int   std_uniq(void* vpElems, int nNumElems, int nElemWidth,
191                       int (*pfnCompare)(void*, const void*, const void*),
192                       void* pCompareCx);
193 
194 #ifdef __cplusplus
195 }
196 #endif /* #ifdef __cplusplus */
197 
198 
199 #define STD_SWAPS(us) \
200    ((((us) & 0xff) << 8) + (((us) & 0xff00) >> 8))
201 
202 
std_swaps(unsigned short us)203 static __inline unsigned short std_swaps(unsigned short us)
204 {
205    return STD_SWAPS(us);
206 }
207 
208 /* note, STD_SWAPL() requires that ul be an l-value, and destroyable.
209    this macro is not intended for use outside AEEstd.h */
210 #define STD_SWAPL(ul) \
211     (((ul) = (((ul) & 0x00ff00ff) << 8) | (((ul)>>8) & 0x00ff00ff)),(((ul) >> 16) | ((ul) << 16)))
212 
std_swapl(unsigned long ul)213 static __inline unsigned long std_swapl(unsigned long ul)
214 {
215    return STD_SWAPL(ul);
216 }
217 
218 #ifdef AEE_BIGENDIAN
219 #  define STD_HTONL(u)     (u)
220 #  define STD_HTONS(u)     (u)
221 #  define STD_HTOLEL(u)    (STD_SWAPL(u))
222 #  define STD_HTOLES(u)    (STD_SWAPS(u))
223 #else
224 #  define STD_HTONL(u)     (STD_SWAPL(u))
225 #  define STD_HTONS(u)     (STD_SWAPS(u))
226 #  define STD_HTOLEL(u)    (u)
227 #  define STD_HTOLES(u)    (u)
228 #endif
229 
std_letohs(unsigned short us)230 static __inline unsigned short std_letohs(unsigned short us)
231 {
232    return STD_HTOLES(us);
233 }
234 
std_htoles(unsigned short us)235 static __inline unsigned short std_htoles(unsigned short us)
236 {
237    return STD_HTOLES(us);
238 }
239 
std_letohl(unsigned long ul)240 static __inline unsigned long std_letohl(unsigned long ul)
241 {
242    return STD_HTOLEL(ul);
243 }
244 
std_htolel(unsigned long ul)245 static __inline unsigned long std_htolel(unsigned long ul)
246 {
247    return STD_HTOLEL(ul);
248 }
249 
std_ntohs(unsigned short us)250 static __inline unsigned short std_ntohs(unsigned short us)
251 {
252    return STD_HTONS(us);
253 }
254 
std_htons(unsigned short us)255 static __inline unsigned short std_htons(unsigned short us)
256 {
257    return STD_HTONS(us);
258 }
259 
std_ntohl(unsigned long ul)260 static __inline unsigned long std_ntohl(unsigned long ul)
261 {
262    return STD_HTONL(ul);
263 }
264 
std_htonl(unsigned long ul)265 static __inline unsigned long std_htonl(unsigned long ul)
266 {
267    return STD_HTONL(ul);
268 }
269 
270 
271 #undef STD_HTONL   // private macro; not exported as a supported API
272 #undef STD_HTONS   // private macro; not exported as a supported API
273 #undef STD_HTOLEL  // private macro; not exported as a supported API
274 #undef STD_HTOLES  // private macro; not exported as a supported API
275 #undef STD_SWAPS   // private macro; not exported as a supported API
276 #undef STD_SWAPL   // private macro; not exported as a supported API
277 
278 
279 /*
280 =======================================================================
281 MACROS DOCUMENTATION
282 =======================================================================
283 
284 STD_CONTSTRAIN()
285 
286 Description:
287   STD_CONTSTRAIN() constrains a number to be between two other numbers.
288 
289 Definition:
290    STD_CONSTRAIN( val, min, max ) \
291           (((val) < (min)) ? (min) : ((val) > (max)) ? (max) : (val))
292 
293 Parameters:
294   val: number to constrain
295   min: number to stay greater than or equal to
296   max: number to stay less than or equal to
297 
298 Evaluation Value:
299    the constrained number
300 
301 =======================================================================
302 
303 STD_BETWEEN()
304 
305 Description:
306     STD_BETWEEN() tests whether a number is between two other numbers.
307 
308 Definition:
309     STD_BETWEEN( val, minGE, maxLT ) \
310                ((unsigned)((unsigned)(val) - (unsigned)(minGE)) < \
311                 (unsigned)((unsigned)(maxLT) - (unsigned)(minGE)))
312 
313 Parameters:
314      val: value to test
315      minGE: lower bound
316      maxLT: upper bound
317 
318 Evaluation Value:
319      1 if val >= minGE and val < maxLT
320 
321 =======================================================================
322 
323 STD_ARRAY_SIZE()
324 
325 Description:
326    STD_ARRAY_SIZE() gives the number of elements in a statically allocated array.
327 
328 Definition:
329     STD_ARRAY_SIZE(a) (sizeof((a))/sizeof((a)[0]))
330 
331 Parameters:
332     a: array to test
333 
334 Evaluation Value:
335     number of elements in a
336 
337 =======================================================================
338 
339 STD_ARRAY_MEMBER()
340 
341 Description:
342    STD_ARRAY_MEMBER() tests whether an item is a member of a statically allocated array.
343 
344 Definition:
345    STD_ARRAY_MEMBER(p,a) (((p) >= (a)) && ((p) < ((a) + STD_ARRAY_SIZE(a))))
346 
347 Parameters:
348     p: item to test
349     a: array to check
350 
351 Evaluation Value:
352     1 if p is in a
353 
354 =======================================================================
355 
356 STD_OFFSETOF()
357 
358 Description:
359   STD_OFFSETOF() gives the offset of member of a struct.
360 
361 Definition:
362    STD_OFFSETOF(type,member) (((char *)(&((type *)0)->member))-((char *)0))
363 
364 Parameters:
365     type: structured type
366     member: name of member in the struct
367 
368 Evaluation Value:
369     offset of member (in bytes) in type
370 
371 =======================================================================
372 
373 STD_RECOVER_REC()
374 
375 Description:
376   STD_RECOVER_REC() provides a safe cast from a pointer to a member
377     of a struct to a pointer to the containing struct
378 
379 Definition:
380   STD_RECOVER_REC(type,member,p) ((type*)(((char*)(p))-STD_OFFSETOF(type,member)))
381 
382 Parameters:
383     type: structured type
384     member: name of member in the struct
385     p: pointer to the member of the struct
386 
387 Evaluation Value:
388     a pointer of type type to the containing struct
389 
390 =======================================================================
391 
392 STD_MIN()
393 
394 Description:
395    STD_MIN() finds the smaller of two values.
396 
397 Definition:
398    STD_MIN(a,b)   ((a)<(b)?(a):(b))
399 
400 Parameters:
401     a, b: values to compare
402 
403 Evaluation Value:
404     smaller of a and b
405 
406 =======================================================================
407 
408 STD_MAX()
409 
410 Description:
411   STD_MAX() finds the larger of two values.
412 
413 Definition:
414    STD_MAX(a,b)   ((a)>(b)?(a):(b))
415 
416 Parameters:
417     a, b: values to compare
418 
419 Evaluation Value:
420     larger of a and b
421 
422 =======================================================================
423 
424 STD_ZEROAT()
425 
426 Description:
427    STD_ZEROAT() zero-initializes the contents of a typed chunk of memory.
428 
429 Definition:
430    STD_ZEROAT(p)  std_memset((p), 0, sizeof(*p))
431 
432 Parameters:
433     p: the chunk to initialize
434 
435 Evaluation Value:
436     p
437 
438 =======================================================================
439 
440 STD_BIT_SET()
441 
442 Description:
443    STD_BIT_SET(bits, ix) sets the bit in the memory stored in bits at
444                          index ix
445 
446 Parameters:
447     bits: the memory address holding the  bits
448     ix:   the index of the bit to set;
449 
450 =======================================================================
451 
452 STD_BIT_CLEAR()
453 
454 Description:
455    STD_BIT_CLEAR(bits, ix) clears the bit in the memory stored in bits
456                            at index ix
457 
458 Parameters:
459     bits: the memory address holding the  bits
460     ix:   the index of the bit to clear
461 
462 =======================================================================
463 
464 STD_BIT_TEST()
465 
466 Description:
467    STD_BIT_TEST(bits, ix) returns the bit in the memory stored in bits
468                           at index ix
469 
470 Parameters:
471     bits: the memory address holding the bits
472     ix:   the index of the bit to test
473 
474 Evaluation Value:
475     0x1 if set 0x0 if not set
476 
477 =====================================================================
478 INTERFACES DOCUMENTATION
479 =======================================================================
480 
481 std Interface
482 
483 Description:
484    This library provides a set of general-purpose utility functions.
485    Functionality may overlap that of a subset of the C standard library, but
486    this library differs in a few respects:
487 
488    - Functions are fully reentrant and avoid use of static variables.
489 
490    - The library can be supported consistently across all environments.
491    Compiler-supplied libraries sometimes behave inconsistently and are
492    unavailable in some environments.
493 
494    - Omits "unsafe" functions.  C standard library includes many functions
495    that are best avoided entirely: strcpy, strcat, strtok, etc.
496 
497 
498 =======================================================================
499 
500 std_getversion()
501 
502 Description:
503 
504    The std_getversion() copies the stdlib version to pcDst.  This function
505    takes the size of the destination buffer as an argument and guarantees
506    to zero-terminate the result and not to overflow the nDestSize size.
507 
508    This function copies up to size-1 characters from the stdlib version
509    string to pcDest and NUL-terminates the pcDest string.
510 
511 Prototype:
512    int  std_getversion(char *pcDst, int nDestSize)
513 
514 
515 Parameters:
516    pcDst :     Destination string
517    nDestSize:  Size of the destination buffer in bytes
518 
519 Return Value:
520 
521    Returns the length of the version string (in characters).
522 
523 =======================================================================
524 
525 std_strlen()
526 
527 Description:
528    The std_strlen() computes the length of the given string.
529 
530 Prototype:
531    int std_strlen(const char *cpszStr)
532 
533 Parameters:
534    cpszStr : String whose length will be computed
535 
536 Return Value:
537    Length of the string in characters that precede the terminating NULL character.
538 
539 =======================================================================
540 
541 std_strcmp()
542 
543 Description:
544    The std_strcmp() compares two NUL-terminated character strings.
545    Comparison is strictly by byte values with no character set
546    interpretation.
547 
548 Prototype:
549 
550    int std_strcmp(const char *s1, const char *s2);
551 
552 Parameters:
553    s1, s2: strings to compare
554 
555 Return Value:
556    0 if strings are the same ~
557    < 0 if s1 is less than s2 ~
558    > 0 if s1 is greater than s2
559 
560 See Also:
561    std_wstrcmp
562 
563 =======================================================================
564 
565 std_strncmp()
566 
567 Description:
568    The std_strncmp() compares at most n bytes of two NUL-terminated character strings.
569 
570 Prototype:
571 
572    int std_strncmp(const char *s1, const char *s2, int n);
573 
574 Parameters:
575    s1, s2: strings to compare
576    n: maximum number of bytes to compare.  if either s1 or s2 is
577        shorter than n, the function terminates there
578 
579 Return Value:
580    0 if strings are the same ~
581    < 0 if s1 is less than s2 ~
582    > 0 if s1 is greater than s2
583 
584 See Also:
585    std_wstrncmp
586 
587 =======================================================================
588 
589 std_stricmp()
590 
591 Description:
592    The std_stricmp() compares two NUL-terminated character strings, case-folding any
593    ASCII characters.
594 
595 Prototype:
596 
597    int std_stricmp(const char *s1, const char *s2);
598 
599 Parameters:
600    s1, s2: strings to compare
601 
602 Return Value:
603    0 if strings are the same ~
604    < 0 if s1 is less than s2 ~
605    > 0 if s1 is greater than s2
606 
607 =======================================================================
608 
609 std_strnicmp()
610 
611 Description:
612    The std_strnicmp() compares at most n bytes of 2 NUL-terminated character strings,
613    case-folding any ASCII characters.
614 
615 Prototype:
616 
617    int std_strnicmp(const char *s1, const char *s2, int n);
618 
619 Parameters:
620    s1, s2: strings to compare
621    n: maximum number of bytes to compare.  if either s1 or s2 is
622        shorter than n, the function terminates there
623 
624 Return Value:
625    0 if strings are the same ~
626    < 0 if s1 is less than s2 ~
627    > 0 if s1 is greater than s2
628 
629 =======================================================================
630 
631 std_strlcpy()
632 
633 Description:
634 
635    The std_strlcpy() copies pszSrc string to the pcDst.  It is a safer
636    alternative to strcpy() or strncpy().  This function takes the size of the
637    destination buffer as an argument and guarantees to NUL-terminate the
638    result and not to overflow the nDestSize size.
639 
640    This function copies up to nDestSize-1 characters from the pszSrc string
641    to pcDest and NUL-terminates the pcDest string.
642 
643 Prototype:
644    int std_strlcpy(char *pcDst, const char *pszSrc, int nDestSize)
645 
646 Parameters:
647    pcDst :     Destination string
648    pcSrc :     Source string
649    nDestSize:  Size of the destination buffer in bytes
650 
651 Return Value:
652 
653    Returns the length of the string (in characters) it tried to create,
654    which is same as length of pszSrc.
655 
656    Example:
657 
658    {
659       char buf[64];
660       if (std_strlcpy(buf, file_name, STD_ARRAY_SIZE(buf) >=
661           STD_ARRAY_SIZE(buf)) {
662          //Truncated -- Handle overflow....
663       }
664    }
665 
666 Comment:
667 
668    Unlike strlcpy, std_strlcpy accepts an integer size and does nothing when a
669    negative value is passed.  When passing valid sizes for objects on our
670    supported platforms, this should not result in any observed difference.
671    However, calling strlcpy() with UINT_MAX will result in the entire source
672    string being copied, whereas std_strlcpy() will do nothing.  Passing INT_MAX
673    to str_strlcpy() will achieve the same result (although both these cases are
674    bad practice since they defeat bounds checking).
675 
676 
677 =======================================================================
678 
679 std_strlcat()
680 
681 Description:
682 
683    The std_strlcat() function concatenates a string to a string already
684    residing in a buffer.  It is a safer alternative to strcat() or strncat().
685    This function takes the size of the destination buffer as an argument and
686    guarantees not to create an improperly terminated string and not to
687    overflow the nDestSize size.
688 
689    This function appends pszSrc to pcDst, copying at most nDestSize minus
690    the length of the string in pcDest minus 1 bytes, always NUL-terminating
691    the result.
692 
693    For compatibility with "strlcat()", std_strlcat() does *not* zero-terminate
694    the destination buffer in cases where the buffer lacks termination on entry
695    to the function.  Do not rely on std_strlcat() to zero-terminate a buffer
696    that is not already zero-terminated; instead ensure that the buffer is
697    properly initialized using std_strlcpy() or some other means.
698 
699 Prototype:
700 
701    int std_strlcat(char *pcDst, const char *pszSrc, int nDestSize)
702 
703 Parameters:
704 
705    pcDst :     Destination string
706    pcSrc :     Source string
707    nDestSize:  Size of the destination buffer in bytes
708 
709 Return Value:
710 
711    Returns the length of the string (in characters) it tried to create,
712    which is same as length of pszSrc plus the length of pszDest.
713 
714    Example:
715 
716    {
717       char buf[64];
718       if (std_strlcat(buf, file_name, STD_ARRAY_SIZE(buf) >=
719           STD_ARRAY_SIZE(buf)) {
720          //Truncated -- Handle overflow....
721       }
722    }
723 
724 
725 =======================================================================
726 
727 std_strstr()
728 
729 Description:
730    The std_strstr() finds the first occurrence of a substring in a string.
731 
732 Prototype:
733 
734    char * std_strstr(const char *pszString, const char *pszSearch);
735 
736 Parameters:
737    pszString: string to search
738    pszSearch: sub string to search for
739 
740 Return Value:
741    A pointer to the first character in the first occurrence of the substring if found, NULL otherwise
742 
743 =======================================================================
744 
745 std_tolower()
746 
747 Description:
748    The std_tolower() converts an uppercase letter to the corresponding
749    lowercase letter.
750 
751 Prototype:
752    char std_tolower(char c);
753 
754 Parameters:
755    c: A character.
756 
757 Return Value:
758    the corresponding lowercase letter if c is an ASCII character whose
759    value is representable as an uppercase letter, else the same character
760    c is returned.
761 
762 =======================================================================
763 
764 std_toupper()
765 
766 Description:
767    The std_toupper() converts an lowercase letter to the corresponding
768    uppercase letter.
769 
770 Prototype:
771    char std_toupper(char c);
772 
773 Parameters:
774    c: is a character.
775 
776 Return Value:
777    The corresponding uppercase letter if c is an ASCII character whose
778    value is representable as an lowercase letter; else the same character
779    c is returned.
780 
781 =======================================================================
782 
783 std_memset()
784 
785 Description:
786    The std_memset() sets each byte in a block of memory to a value.
787 
788 Prototype:
789 
790    void *std_memset(void *p, int c, int nLen);
791 
792 Parameters:
793    p: memory block to set
794    c: value to set each byte to
795    nLen: size of p in bytes
796 
797 Return Value:
798    p
799 
800 =======================================================================
801 
802 std_memmove()
803 
804 Description:
805    The std_memmove() copies a block of memory from one buffer to another.
806 
807 Prototype:
808 
809    void *std_memmove(void *pTo, const void *cpFrom, int nLen);
810 
811 Parameters:
812    pTo: destination buffer
813    cpFrom: source buffer
814    nLen: number of bytes to copy
815 
816 Return Value:
817    pTo
818 
819 =======================================================================
820 
821 std_memsmove()
822 
823 Description:
824 
825   Size bounded memory move.
826 
827   Moves bytes from the source buffer to the destination buffer.
828 
829   This function ensures that there will not be a copy beyond
830   the size of the destination buffer.
831 
832   This function should be used in preference to memscpy() if there
833   is the possiblity of source and destination buffers overlapping.
834   The result of the operation is defined to be as if the copy were from
835   the source to a temporary buffer that overlaps neither source nor
836   destination, followed by a copy from that temporary buffer to the
837   destination.
838 
839 Prototype:
840 
841   int std_memsmove(void *dst, int dst_size, const void *src, int src_size);
842 
843 Parameters:
844   @param[out] dst       Destination buffer.
845   @param[in]  dst_size  Size of the destination buffer in bytes.
846   @param[in]  src       Source buffer.
847   @param[in]  src_size  Number of bytes to copy from source buffer.
848 
849 Return value:
850   The number of bytes copied to the destination buffer.  It is the
851   caller's responsibility to check for trunction if it cares about it -
852   truncation has occurred if the return value is less than src_size.
853   A negative return value indicates an error
854 
855 =======================================================================
856 
857 std_memcmp()
858 
859 Description:
860    The std_memcmp() compares two memory buffers, byte-wise.
861 
862 Prototype:
863 
864    int std_memcmp(const void *a, const void *b, int length);
865 
866 Parameters:
867    a, b: buffers to compare
868    length: number of bytes to compare
869 
870 Return Value:
871    0 if buffers are the same for nLength ~
872    < 0 if a is less than b ~
873    > 0 if a is greater than b
874 
875 =======================================================================
876 
877 std_memscpy - Size bounded memory copy.
878 
879 Description:
880 
881   Copies bytes from the source buffer to the destination buffer.
882 
883   This function ensures that there will not be a copy beyond
884   the size of the destination buffer.
885 
886   The result of calling this on overlapping source and destination
887   buffers is undefined.
888 
889 Prototype:
890 
891    int std_memscpy(void *dst, int dst_size, const void *src, int src_size);
892 
893 Parameters:
894 
895   @param[out] dst       Destination buffer.
896   @param[in]  dst_size  Size of the destination buffer in bytes.
897   @param[in]  src       Source buffer.
898   @param[in]  src_size  Number of bytes to copy from source buffer.
899 
900 Return value:
901 
902   The number of bytes copied to the destination buffer.  It is the
903   caller's responsibility to check for trunction if it cares about it -
904   truncation has occurred if the return value is less than src_size.
905   Returs a negative value on error.
906 
907 =======================================================================
908 
909 std_memchr()
910 
911 Description:
912    The std_memchr() finds the first occurrence of a character in a memory
913    buffer.
914 
915 Prototype:
916 
917    void *std_memchr(const void* s, int c, int n);
918 
919 Parameters:
920    s: buffer to search
921    c: value of byte to look for
922    n: size of s in bytes
923 
924 Return Value:
925    A pointer to the occurrence of c. NULL if not found.
926 
927 =======================================================================
928 
929 std_memstr()
930 
931 Description:
932    The std_memstr() finds the first occurrence of a substring in a memory
933    buffer.
934 
935 Prototype:
936 
937    void *std_memstr(const char* cpHaystack, const char* cpszNeedle,
938                     int nHaystackLen);
939 
940 Parameters:
941    cpHaystack: buffer to search
942    cpszNeedle: NUL-terminated string to search for
943    nHaystackLen: size of cpHaystack in bytes
944 
945 Return Value:
946    a pointer to the first occurrence of cpszNeedle if found,
947        NULL otherwise
948 
949 Comments:
950    None
951 
952 Side Effects:
953    None
954 
955 See Also:
956    None
957 
958 =======================================================================
959 
960 std_memrchr()
961 
962 Description:
963 
964    The std_memrchr() finds the last occurrence of a character in a memory
965    buffer.
966 
967 Prototype:
968 
969    void *std_memrchr(const void* s, int c, int n);
970 
971 Parameters:
972    s: buffer to search
973    c: value of byte to look for
974    n: size of s in bytes
975 
976 Return Value:
977    a pointer to the last occurrence of c, NULL if not found
978 
979 =======================================================================
980 
981 std_memrchrbegin()
982 
983 Description:
984    The std_memrchrbegin() finds the last occurrence of a character in a
985    memory buffer.
986 
987 Prototype:
988 
989    void *std_memrchrbegin(const void* s, int c, int n);
990 
991 Parameters:
992    s: buffer to search
993    c: value of byte to look for
994    n: size of s in bytes
995 
996 Return Value:
997    a pointer to the last occurrence of c, or s if not found
998 
999 =======================================================================
1000 
1001 std_memchrend()
1002 
1003 Description:
1004    The std_memchrend() finds the first occurrence of a character in a
1005    memory buffer.
1006 
1007 Prototype:
1008 
1009    void *std_memchrend(const void* s, int c, int n);
1010 
1011 Parameters:
1012    s: buffer to search
1013    c: value of byte to look for
1014    n: size of s in bytes
1015 
1016 Return Value:
1017    a pointer to the occurrence of c, s + n if not found
1018 
1019 =======================================================================
1020 std_memchrsend()
1021 
1022 Description:
1023    The std_memchrsend() finds the first occurrence of any character in a
1024    NUL-terminated list of characters in a memory buffer.
1025 
1026 Prototype:
1027 
1028    void *std_memchrend(const void* s, const char* cpszChars, int n);
1029 
1030 Parameters:
1031    s: buffer to search
1032    cpszChars: characters to look for
1033    n: size of s in bytes
1034 
1035 Return Value:
1036    a pointer to the first occurrence of one of cpszChars, s + n if not found
1037 
1038 =======================================================================
1039 
1040 std_strchr()
1041 
1042 Description:
1043    The std_strchr() finds the first occurrence of a character in a
1044    NUL-terminated string.
1045 
1046 Prototype:
1047 
1048    char *std_strchr(const char* s, int c);
1049 
1050 Parameters:
1051    s: string to search
1052    c: char to search for
1053 
1054 Return Value:
1055    pointer to first occurrence, NULL if not found
1056 
1057 See Also:
1058    std_wstrchr
1059 
1060 =======================================================================
1061 
1062 std_strchrs()
1063 
1064 Description:
1065    The std_strchrs() searches s, a NUL-terminated string, for the first
1066    occurrence of any characters in cpszSrch, a NUL-terminated list of
1067    characters.
1068 
1069 Prototype:
1070 
1071    char *std_strchrs(const char* s, const char *cpszSrch);
1072 
1073 Parameters:
1074    s: string to search
1075    cpszSrch: a list of characters to search for
1076 
1077 Return Value:
1078    first occurrence of any of cpszSrch, NULL if not found
1079 
1080 =======================================================================
1081 
1082 std_strrchr()
1083 
1084 Description:
1085    The std_strrchr() finds the last occurrence of a character in a
1086    NUL-terminated string.
1087 
1088 Prototype:
1089 
1090    char *std_strrchr(const char* s, int c);
1091 
1092 Parameters:
1093    s: string to search
1094    c: char to search for
1095 
1096 Return Value:
1097    pointer to last occurrence, NULL if not found
1098 
1099 See Also:
1100    std_wstrrchr
1101 
1102 =======================================================================
1103 
1104 std_strchrend()
1105 
1106 Description:
1107    The std_strchrend() finds the first occurrence of a character in a
1108    NUL-terminated string.
1109 
1110 Prototype:
1111 
1112    char *std_strchrend(const char* s, int c);
1113 
1114 Parameters:
1115    s: string to search
1116    c: char to search for
1117 
1118 Return Value:
1119    pointer to first occurrence, s + std_strlen(s) if not found
1120 
1121 =======================================================================
1122 
1123 std_strchrsend()
1124 
1125 Description:
1126    The std_strchrsend() searches s, a NUL-terminated string, for the first
1127    occurrence of any characters in cpszSrch, a NUL-terminated list of
1128    characters.
1129 
1130 Prototype:
1131 
1132    char *std_strchrsend(const char* s, const char* cpszSrch);
1133 
1134 Parameters:
1135    s: string to search
1136    cpszSrch: a list of characters to search for
1137 
1138 Return Value:
1139    first occurrence of any of cpszSrch or s+strlen(s) if not found
1140 
1141 =======================================================================
1142 
1143 std_strends()
1144 
1145 Description:
1146    The std_strends() tests whether a string ends in a particular suffix.
1147 
1148 Prototype:
1149 
1150    char *std_strends(const char* cpsz, const char* cpszSuffix);
1151 
1152 Parameters:
1153    cpsz: string to test
1154    cpszSuffix: suffix to test for
1155 
1156 Return Value:
1157    the first character of cpsz+std_strlen(cpsz)-std_strlen(cpszSuffix)
1158      if cpsz ends with cpszSuffix.  NULL otherwise.
1159 
1160 =======================================================================
1161 
1162 std_striends()
1163 
1164 Description:
1165    The std_striends() tests whether a string ends in a particular suffix,
1166    case-folding ASCII characters.
1167 
1168 Prototype:
1169 
1170    char *std_striends(const char* cpsz, const char* cpszSuffix);
1171 
1172 Parameters:
1173    cpsz: string to test
1174    cpszSuffix: suffix to test for
1175 
1176 Return Value:
1177    the first character of cpsz+std_strlen(cpsz)-std_strlen(cpszSuffix)
1178      if cpsz ends with cpszSuffix.  NULL otherwise.
1179 
1180 =======================================================================
1181 
1182 std_strbegins()
1183 
1184 Description:
1185    The std_strbegins() tests whether a string begins with a particular
1186    prefix string.
1187 
1188 Prototype:
1189 
1190    char *std_strbegins(const char* cpsz, const char* cpszPrefix);
1191 
1192 Parameters:
1193    cpsz: string to test
1194    cpszPrefix: prefix to test for
1195 
1196 Return Value:
1197    cpsz + std_strlen(cpszPrefix) if cpsz does begin with cpszPrefix,
1198      NULL otherwise
1199 
1200 =======================================================================
1201 
1202 std_stribegins()
1203 
1204 Description:
1205    The std_stribegins() tests whether a string begins with a particular
1206    prefix string, case-folding ASCII characters.
1207 
1208 Prototype:
1209 
1210    char *std_stribegins(const char* cpsz, const char* cpszPrefix);
1211 
1212 Parameters:
1213    cpsz: string to test
1214    cpszPrefix: prefix to test for
1215 
1216 Return Value:
1217    cpsz + std_strlen(cpszPrefix) if cpsz does begin with cpszPrefix,
1218      NULL otherwise
1219 
1220 
1221 =======================================================================
1222 
1223 std_strcspn()
1224 
1225 Description:
1226    The std_strcspn() function searches s, a NUL-terminated string, for
1227    the first occurrence of any characters in cpszSrch, a NUL-terminated
1228    list of characters. This function returns the length of the longest
1229    initial substring of s which consists of characters not present in
1230    cpszSrch.
1231 
1232 Prototype:
1233 
1234    int std_strcspn(const char* s, const char* cpszSrch);
1235 
1236 Parameters:
1237    s: string to search
1238    cpszSrch: a list of characters to search for
1239 
1240 Return Value:
1241    The index into the string s of the first occurrence of any of the
1242    characters in cpszSrch. If no match is found, then index of the
1243    terminating NUL character is returned.
1244 
1245 See Also:
1246    std_strspn, std_strchr, std_strchrs
1247 
1248 =======================================================================
1249 
1250 std_strspn()
1251 
1252 Description:
1253    The std_strspn() functions searches s, a NUL-terminated string, for
1254    the first occurrence of a character that matches none of the
1255    characters in cpszSrch, a NUL-terminated list of characters. This
1256    function returns the length of the longest initial substring of s
1257    which consists of characters present in cpszSrch.
1258 
1259 Prototype:
1260 
1261    int std_strspn(const char* s, const char* cpszSrch);
1262 
1263 Parameters:
1264    s: string to search
1265    cpszSrch: a list of characters to search for
1266 
1267 Return Value:
1268    The index into the string s of the first occurrence of any character
1269    that matches none of the characters in cpszSrch. If all characters
1270    in s are present in cpszSrch, the index of the terminating NUL
1271    character is returned.
1272 
1273 See Also:
1274    std_strcspn, std_strchr, std_strchrs
1275 
1276 =======================================================================
1277 
1278 std_wstrlcpy()
1279 
1280 Description:
1281 
1282    The std_wstrlcpy() function copies a string.  It is equivalent to
1283    str_strlcpy() except that it operates on wide (16-bit) character strings.
1284    See std_strlcpy() for details.
1285 
1286 
1287 Prototype:
1288 
1289    int std_wstrlcpy(AECHAR *pcDest, const AECHAR *pszSrc, int nDestSize);
1290 
1291 Parameters:
1292    pcDst: destination string
1293    pszSrc: source string
1294    int nDestSize: size of pcDest __in AECHARs__
1295 
1296 Return Value:
1297    Returns the length of the string (in AECHARs) it tried to create,
1298    which is same as length of pszSrc.
1299 
1300    Example:
1301 
1302    {
1303       AECHAR buf[64];
1304       if (std_wstrlcpy(buf, file_name, STD_ARRAY_SIZE(buf)) >=
1305           STD_ARRAY_SIZE(buf)) {
1306          //Truncated -- Handle overflow....
1307       }
1308    }
1309 
1310 See Also:
1311    std_wstrlcat
1312 
1313 =======================================================================
1314 
1315 std_wstrlcat()
1316 
1317 Description:
1318 
1319    The std_wstrlcat() function concatenates two strings.  It is equivalent to
1320    std_strlcat() except that it operates on wide (16-bit) character strings.
1321    See std_strlcat() for more information.
1322 
1323 Prototype:
1324    int std_wstrlcat(AECHAR *pcDst, const AECHAR *pszSrc, int nDestSize)
1325 
1326 Parameters:
1327    pcDst[out]: Destination string
1328    pcSrc :     Source string
1329    nDestSize:  Size of the destination buffer in AECHARs
1330 
1331 Return Value:
1332    Returns the length of the string (in AECHARs) it tried to create,
1333    which is same as length of pszSrc + the length of pszDest.
1334 
1335    Example:
1336 
1337    {
1338       char buf[64];
1339       if (std_wstrlcat(buf, file_name, STD_ARRAY_SIZE(buf)) >=
1340           STD_ARRAY_SIZE(buf)) {
1341          //Truncated -- Handle overflow....
1342       }
1343    }
1344 
1345 See Also:
1346    std_wstrlcpy
1347 
1348 =======================================================================
1349 
1350 std_wstrncmp()
1351 
1352 Description:
1353 
1354    The std_wstrncmp() function compares up to a specified number of bytes
1355    in two NUL-terminated strings. It is equivalent to std_strncmp() except
1356    that it operates on wide (16-bit) character strings.
1357 
1358 Prototype:
1359    int std_wstrncmp(const AECHAR* s1, const AECHAR* s2, int nLen);
1360 
1361 Parameters:
1362    s1, s2: strings to compare
1363    n: maximum number of AECHARs to compare.  if either s1 or s2 is
1364       shorter than n, the function terminates there.
1365 
1366 Return Value:
1367    0 if strings are the same ~
1368    < 0 if s1 is less than s2 ~
1369    > 0 if s1 is greater than s2
1370 
1371 See Also:
1372    std_strncmp
1373 
1374 =======================================================================
1375 
1376 std_wstrcmp()
1377 
1378 Description:
1379    The std_wstrcmp() compares two NUL-terminated strings. It is equivalent
1380    to std_strncmp() except that it operates on wide (16-bit) character
1381    strings. Comparison is strictly by byte values with no character set
1382    interpretation.
1383 
1384 Prototype:
1385 
1386    int std_wstrcmp(const AECHAR* s1, const AECHAR* s2);
1387 
1388 Parameters:
1389    s1, s2: strings to compare
1390 
1391 Return Value:
1392    0 if strings are the same ~
1393    < 0 if s1 is less than s2 ~
1394    > 0 if s1 is greater than s2
1395 
1396 See Also:
1397    std_strcmp
1398 
1399 =======================================================================
1400 
1401 std_wstrchr()
1402 
1403 Description:
1404    This function is the wide string counterpart of std_strchr().
1405    The std_wstrchr() finds the first occurrence of a character in a
1406    NUL-terminated wide (16-bit) character string.
1407 
1408 Prototype:
1409 
1410    AECHAR* std_wstrchr(const AECHAR* s, AECHAR ch);
1411 
1412 Parameters:
1413    s: string to search
1414    ch: char to search for
1415 
1416 Return Value:
1417    pointer to first occurrence, NULL if not found
1418 
1419 See Also:
1420    std_strchr
1421 
1422 =======================================================================
1423 
1424 std_wstrrchr()
1425 
1426 Description:
1427    This function is the wide string counterpart of std_strrchr().
1428    The std_wstrrchr() finds the last occurrence of a character in a
1429    NUL-terminated wide (16-bit) character string.
1430 
1431 Prototype:
1432 
1433    AECHAR* std_wstrrchr(const AECHAR* s, AECHAR ch);
1434 
1435 Parameters:
1436    s: string to search
1437    ch: char to search for
1438 
1439 Return Value:
1440    pointer to last occurrence, NULL if not found
1441 
1442 See Also:
1443    std_strrchr
1444 
1445 =======================================================================
1446 
1447 std_makepath()
1448 
1449 Description:
1450    The std_makepath() constructs a path from a directory portion and a file
1451    portion, using forward slashes, adding necessary slashes and deleting extra
1452     slashes.  This function guarantees NUL-termination of pszDest
1453 
1454 Prototype:
1455 
1456    int std_makepath(const char *cpszDir, const char *cpszFile,
1457                     char *pszDest, int nDestSize)
1458 
1459 Parameters:
1460    cpszDir: directory part
1461    cpszFile: file part
1462    pszDest: output buffer
1463    nDestSize: size of output buffer in bytes
1464 
1465 Return Value:
1466    the required length to construct the path, not including
1467    NUL-termination
1468 
1469 Comments:
1470    The following list of examples shows the strings returned by
1471    std_makepath() for different paths.
1472 
1473 Example:
1474 
1475    cpszDir  cpszFile  std_makepath()
1476    ""        ""           ""
1477    ""        "/"          ""
1478    "/"       ""           "/"
1479    "/"       "/"          "/"
1480    "/"       "f"          "/f"
1481    "/"       "/f"         "/f"
1482    "d"       "f"          "d/f"
1483    "d/"      "f"          "d/f"
1484    "d"       "/f"         "d/f"
1485    "d/"      "/f"         "d/f"
1486 
1487 See Also:
1488    std_splitpath
1489 
1490 =======================================================================
1491 
1492 std_splitpath()
1493 
1494 Description:
1495    The std_splitpath() finds the filename part of a path given an inclusive
1496    directory, tests for cpszPath being in cpszDir. The forward slashes are
1497    used as directory delimiters.
1498 
1499 Prototype:
1500 
1501    char *std_splitpath(const char *cpszPath, const char *cpszDir);
1502 
1503 Parameters:
1504    cpszPath: path to test for inclusion
1505    cpszDir: directory that cpszPath might be in
1506 
1507 Return Value:
1508    the part of cpszPath that actually falls beneath cpszDir, NULL if
1509    cpszPath is not under cpszDir
1510 
1511 Comments:
1512    The std_splitpath() is similar to std_strbegins(), but it ignores trailing
1513    slashes on cpszDir, and it returns a pointer to the first character of
1514    the subpath.
1515 
1516    The return value of std_splitpath() will never begin with a '/'.
1517 
1518    The following list of examples shows the strings returned by
1519    std_splitpath() for different paths.
1520 
1521 Example:
1522    cpszPath cpszDir  std_splitpath()
1523    ""        ""           ""
1524    ""        "/"          ""
1525    "/"       ""           ""
1526    "/"       "/"          ""
1527    "/d"      "d"          null
1528    "/d"      "/"          "d"
1529    "/d/"     "/d"         ""
1530    "/d/f"    "/"          "d/f"
1531    "/d/f"    "/d"         "f"
1532    "/d/f"    "/d/"        "f"
1533 
1534 See Also:
1535    std_makepath
1536 
1537 =======================================================================
1538 
1539 std_cleanpath()
1540 
1541 Description:
1542    The std_cleanpath() removes double slashes, ".", and ".." from
1543    slash-delimited paths,. It operates in-place.
1544 
1545 Prototype:
1546 
1547    char *std_cleanpath(char *pszPath);
1548 
1549 Parameters:
1550    pszPath[in/out]: path to "clean"
1551 
1552 Return Value:
1553    pszPath
1554 
1555 Comments:
1556    Passing an "fs:/" path to this function may produce undesirable
1557    results.  This function assumes '/' is the root.
1558 
1559 Examples:
1560        pszPath  std_cleanpath()
1561          "",           "",
1562          "/",          "/",
1563 
1564          // here"s, mostly alone
1565          "./",         "/",
1566          "/.",         "/",
1567          "/./",        "/",
1568 
1569          // "up"s, mostly alone
1570          "..",         "",
1571          "/..",        "/",
1572          "../",        "/",
1573          "/../",       "/",
1574 
1575          // fun with x
1576          "x/.",        "x",
1577          "x/./",       "x/",
1578          "x/..",       "",
1579          "/x/..",      "/",
1580          "x/../",      "/",
1581          "/x/../",     "/",
1582          "/x/../..",   "/",
1583          "x/../..",    "",
1584          "x/../../",   "/",
1585          "x/./../",    "/",
1586          "x/././",     "x/",
1587          "x/.././",    "/",
1588          "x/../.",     "",
1589          "x/./..",     "",
1590          "../x",       "/x",
1591          "../../x",    "/x",
1592          "/../x",      "/x",
1593          "./../x",     "/x",
1594 
1595          // double slashes
1596          "//",         "/",
1597          "///",        "/",
1598          "////",       "/",
1599          "x//x",       "x/x",
1600 
1601 
1602 Side Effects:
1603    None
1604 
1605 See Also:
1606    None
1607 
1608 
1609 =======================================================================
1610 
1611 std_basename()
1612 
1613 Description:
1614    The std_basename() returns the filename part of a string,
1615    assuming '/' delimited filenames.
1616 
1617 Prototype:
1618 
1619    char *std_basename(const char *cpszPath);
1620 
1621 Parameters:
1622    cpszPath: path of interest
1623 
1624 Return Value:
1625    pointer into cpszPath that denotes part of the string immediately
1626    following the last '/'
1627 
1628 Examples:
1629      cpszPath       std_basename()
1630          ""            ""
1631          "/"           ""
1632          "x"           "x"
1633          "/x"          "x"
1634          "y/x"         "x"
1635          "/y/x"        "x"
1636 
1637  See Also:
1638     None
1639 
1640 =======================================================================
1641 
1642 std_rand_next()
1643 
1644 Description:
1645   The std_rand_next() generates pseudo-random bytes.
1646 
1647 Prototype:
1648 
1649    unsigned std_rand_next(unsigned uRand);
1650 
1651 Parameters:
1652    uRand: a seed for the pseudo-random generator
1653 
1654 Return Value:
1655    the next value in the generator from uRand
1656 
1657 Comments:
1658    for best results, this function should be called with its last
1659    generated output.
1660 
1661    This is an example of code to generate 256 bytes of pseudo-random data.
1662 
1663    This is not crypto quality and should not be used for key generation
1664    and the like.
1665 
1666 Example:
1667    {
1668        unsigned rand_buf[256/sizeof(unsigned)];
1669        int      i;
1670        unsigned uLast = std_rand_next(uCurrentTime);
1671        for (i = 0; i < STD_ARRAY_SIZE(rand_buf); i++) {
1672           rand_buf[i] = (uLast = std_rand_next(uLast));
1673        }
1674    }
1675 
1676 See Also:
1677    std_rand()
1678 
1679 =======================================================================
1680 
1681 std_rand()
1682 
1683 Description:
1684   The std_rand() functions generates pseudo-random bytes and places it
1685   in an output buffer of specified size.
1686 
1687 Prototype:
1688 
1689    uint32 std_rand(uint32 uSeed, byte* pDest, int nSize);
1690 
1691 Parameters:
1692    uSeed: A seed for the pseudo-random generator
1693    pDest: The output buffer where the random bytes are placed.
1694    nSize: The size in bytes of pDest.
1695 
1696 Return Value:
1697    The new seed value that can be used in a subsequent call to
1698    std_rand().
1699 
1700 Comments:
1701 
1702    std_rand() is a linear congruent psuedo-random number generator that
1703    is seeded using the input seed. This makes the ouput predictable if
1704    you can determine (or influence) the seed value used. Furthermore,
1705    the random sequence of bytes generated by two different calls to this
1706    function will be identical if both the calls use the same seed value.
1707 
1708    This is not crypto quality and should not be used for key generation
1709    and other cryptographic uses.
1710 
1711 See Also:
1712    std_rand_next()
1713 
1714 =======================================================================
1715 
1716 std_CopyLE()
1717 
1718 Description:
1719 
1720    The std_CopyLE() function copies data while translating numeric values
1721    between host byte ordering and "little endian" byte ordering.
1722 
1723    pvDest and pvSrc are NOT required to be 16 or 32-bit word aligned.
1724 
1725    Behavior is undefined when the destination and source arrays overlap,
1726    except in the special case where pvDest and pvSrc are equal.  In that case,
1727    std_CopyLE() modifies the buffer in-place.
1728 
1729    When the target byte ordering (little endian) matches the host byte
1730    ordering, in-place translations reduce to a no-op, and copies are
1731    delegated directly to std_memmove().
1732 
1733 
1734 Prototype:
1735    int std_CopyLE(void *pvDest, int nDestSize,
1736                   const void *pvSrc,  int nSrcSize,
1737                   const char *pszFields);
1738 
1739 Parameters:
1740    pvDest:    Pointer to destination buffer.
1741    nDestSize: Size of the destination buffer.
1742    pvSrc:     Pointer to buffer containing source data.
1743    nSrcSize:  Size of source data.
1744    pszFields: Description of the fields that comprise the source data.
1745 
1746               Each field size is given by a positive decimal integer or one of
1747               the following characters: "S", "L", "Q", or "*".  The letters
1748               denote fields that should be converted to the desired byte
1749               ordering:
1750 
1751 ===pre>
1752                 S : a 2 byte (16 bit) value.
1753                 L : a 4 byte (32 bit) value.
1754                 Q : a 8 byte (64 bit) value.
1755 ===/pre>
1756 
1757               An integer gives a number of bytes and "*" represents the
1758               remainder of the pvSrc[] buffer.  No reordering is performed on
1759               data in these fields.
1760 
1761               Comparisons are case-sensitive.  Behavior is undefined when
1762               other characters are supplied in pszFields.
1763 
1764               For example: "L12S*" would be appropriate to copy a structure
1765               containing a uint32 followed by a 12 byte character array,
1766               followed by a uint16, followed by an arbitrary amount of
1767               character data.
1768 
1769               If nSrcSize is greater than the structure size (total of all the
1770               sizes in pszFields[]) then pvSrc[] is treated as an array of
1771               structures, each of which is described by pszFields.
1772 
1773 Return Value:
1774 
1775    The number of bytes actually copied or translated in-place.  This will be
1776    the smaller of nDestSize and nSrcSize, or zero if one of them are negative.
1777 
1778 
1779 =======================================================================
1780 
1781 std_CopyBE()
1782 
1783 Description:
1784 
1785    The std_CopyBE() function has the same semantics as std_CopyLE() except it
1786    copies between host byte ordering and big-endian ("network") byte order.
1787 
1788    See std_CopyLE() for more details.
1789 
1790 
1791 Prototype:
1792    void *std_CopyBE(void *pvDest, const void *pvSrc,
1793                            int cbDest, int nItems, const char *pszFields);
1794 
1795 Parameters:
1796    pvDest:    Pointer to destination buffer.
1797    nDestSize: Size of the destination buffer.
1798    pvSrc:     Pointer to buffer containing source data.
1799    nSrcSize:  Size of source data.
1800    pszFields: Description of the fields that comprise the source data,
1801               as defined in std_CopyLE.
1802 
1803 Return Value:
1804 
1805    The number of bytes actually copied or translated in-place.  This will be
1806    the smaller of nDestSize and nSrcSize, or zero if one of them are negative.
1807 
1808 =======================================================================
1809 
1810 std_swapl()
1811 
1812 Description:
1813    The std_swapl() changes endianness of an unsigned long.
1814 
1815 Prototype:
1816 
1817    unsigned long std_swapl(unsigned long ul)
1818 
1819 Parameters:
1820    ul: input unsigned long
1821 
1822 Return Value:
1823    ul, reversed in byte-ordering
1824 
1825 =======================================================================
1826 
1827 std_swaps()
1828 
1829 Description:
1830    The std_swaps() changes endianness of an unsigned short.
1831 
1832 Prototype:
1833 
1834    unsigned short std_swaps(unsigned short us)
1835 
1836 Parameters:
1837    us: input unsigned short
1838 
1839 Return Value:
1840    us, reversed in byte-ordering
1841 
1842 =======================================================================
1843 
1844 std_letohs()
1845 
1846 Description:
1847    The std_letohs() changes a short from little-endian to host byte order.
1848 
1849 Prototype:
1850 
1851    unsigned short std_letohs(unsigned short us)
1852 
1853 Parameters:
1854    us: short to convert
1855 
1856 Return Value:
1857    us converted from little-endian to host byte order.  If the
1858      host is little endian, just returns us
1859 
1860 =======================================================================
1861 
1862 std_htoles()
1863 
1864 Description:
1865    The std_htoles() converts a short from host byte-order to little-endian.
1866 
1867 Prototype:
1868 
1869    unsigned short std_htoles(unsigned short us)
1870 
1871 Parameters:
1872    us: short to convert
1873 
1874 Return Value:
1875    us converted from host byte order to little-endian.  If the
1876    host is little endian, just returns us
1877 
1878 =======================================================================
1879 
1880 std_letohl()
1881 
1882 Description:
1883    The std_letohl() changes a long from little-endian to host byte order.
1884 
1885 Prototype:
1886 
1887    unsigned long std_letohl(unsigned long ul)
1888 
1889 Parameters:
1890    ul: long to convert
1891 
1892 Return Value:
1893    ul converted from little-endian to host byte order.  If the
1894    host is little endian, just returns ul
1895 
1896 =======================================================================
1897 
1898 std_htolel()
1899 
1900 Description:
1901    The std_htolel() converts a long from host byte-order to little-endian.
1902 
1903 Prototype:
1904 
1905    unsigned long std_htolel(unsigned long ul)
1906 
1907 Parameters:
1908    ul: long to convert
1909 
1910 Return Value:
1911    ul converted from host byte order to little-endian.  If the
1912    host is little endian, just returns ul.
1913 
1914 
1915 =======================================================================
1916 
1917 std_ntohs()
1918 
1919 Description:
1920    The std_ntohs() changes a short from big-endian to host byte order.
1921 
1922 Prototype:
1923 
1924    unsigned short std_ntohs(unsigned short us)
1925 
1926 Parameters:
1927    us: short to convert
1928 
1929 Return Value:
1930    us converted from big-endian to host byte order.  If the
1931    host is big endian, just returns us.
1932 
1933 =======================================================================
1934 
1935 std_htons()
1936 
1937 Description:
1938    The std_htons() converts a short from host byte-order to big-endian.
1939 
1940 Prototype:
1941 
1942    unsigned short std_htons(unsigned short us)
1943 
1944 Parameters:
1945    us: short to convert
1946 
1947 Return Value:
1948    us converted from host byte order to big-endian.  If the
1949    host is big endian, just returns us.
1950 
1951 =======================================================================
1952 
1953 std_ntohl()
1954 
1955 Description:
1956    The std_ntohl() changes a long from big-endian to host byte order.
1957 
1958 Prototype:
1959 
1960    unsigned long std_ntohl(unsigned long ul)
1961 
1962 Parameters:
1963    ul: long to convert
1964 
1965 Return Value:
1966    ul converted from big-endian to host byte order.  If the
1967    host is big endian, just returns ul.
1968 
1969 =======================================================================
1970 
1971 std_htonl()
1972 
1973 Description:
1974    The std_htonl() converts a long from host byte-order to big-endian.
1975 
1976 Prototype:
1977 
1978    unsigned long std_htonl(unsigned long ul)
1979 
1980 Parameters:
1981    ul: long to convert
1982 
1983 Return Value:
1984    ul converted from host byte order to big-endian.  If the
1985    host is big endian, just returns ul.
1986 
1987 
1988 =======================================================================
1989 
1990 std_strlprintf()
1991 
1992 Description:
1993 
1994    The functions std_strlprintf() and std_vstrlprintf() write formatted
1995    output to a string.  These functions guarantee NUL-termination of
1996    the output buffer when its size is greater than zero.
1997 
1998    A format string is copied to the output buffer, except for conversion
1999    specifiers contained within the format string.  Conversion specifiers
2000    begin with a "%" and specify some action that consumes an argument from
2001    the argument list.
2002 
2003    Conversion specifiers have the following form:
2004 ===pre>
2005        %[FLAGS] [WIDTH] [.PRECISION] [TYPE] CONV
2006 ===/pre>
2007 
2008    CONV is the only required field.  It is always a single character,
2009    and determines the action to be taken.  Supported values are:
2010 
2011 ===pre>
2012     CONV | Description
2013    ======|=======================================================
2014      c   | Output a single character.
2015          |
2016      s   | Output a NUL-terminated single-byte character string.
2017          |
2018     d, i | Ouptut a signed decimal integer.
2019          |
2020      u   | Output an unsigned decimal integer.
2021          |
2022      o   | Output an unsigned octal integer.
2023          |
2024      x   | Output an unsigned hexadecimal integer, using
2025          | lower case digits.
2026          |
2027      X   | Output an unsigned hexadecimal integer, using
2028          | upper case digits.
2029          |
2030      p   | Output a pointer value as eight hexadecimal digits,
2031          | using upper case digits.
2032 ===/pre>
2033 
2034    The next argument from the argument list supplies the value to be
2035    formatted and output.
2036 
2037    FLAGS, WIDTH, and PRECISION can modify the formatting of the value.
2038 
2039    FLAGS consists of one or more of the following characters:
2040 
2041 ===pre>
2042    Flag | Meaning
2043    =====|=================================================================
2044      +  | Prefix positive numbers with "+" (%d and %i only).
2045    -----|-----------------------------------------------------------------
2046      -  | When padding to meet WIDTH, pad on the right.
2047    -----|-----------------------------------------------------------------
2048      0  | Pad with '0' characters when padding on the left to meet WIDTH.
2049    -----|-----------------------------------------------------------------
2050    blank| Prefix positive numbers with " " (%d and %i only).
2051    space|
2052    -----|-----------------------------------------------------------------
2053      #  | With %x or %X: prefixes non-zero values with "0x"/"0X".
2054         | With %o, ensure the value begins with "0" (increasing PRECISION
2055         |    if necessary).
2056         | Ignored for all other CONV specifiers.
2057    -----|-----------------------------------------------------------------
2058 ===/pre>
2059 
2060    WIDTH is an unsigned decimal integer or the character "*".
2061 
2062    WIDTH gives the minimum number of characters to be written.  The
2063    formatted value will be padded with spaces until the minimum size is
2064    met; it never causes a value to be truncated The sign of the WIDTH
2065    integer selects between left and right padding.  Padding will be on
2066    the left unless the "-" flag is specified.
2067 
2068    When "*" is used, an 'int' argument is consumed from the argument
2069    list and used as the WIDTH.  A negative argument specifies padding on
2070    the right, and its absolute value gives the amount of padding.
2071 
2072    If the "0" flags is specified, any padding on the left will consist
2073    of "0" characters.  An exception to this rule is that the "0" flag is
2074    ignored when precision is specified for a numeric value.
2075 
2076    PRECISION is a non-negative decimal integer or "*" preceded by ".".
2077 
2078    When PRECISION accompanies any of the numeric conversions, it
2079    specifies the minimum number of digits to output.  Values are padded
2080    on the left with '0' to meet the specified size.  PRECISION defaults
2081    to 1 for numbers.
2082 
2083    When PRECISION accompanies other conversions, it specifies the
2084    maximum number of characters from the value to output.  The value
2085    will be truncated to ensure that at most PRECISION characters are
2086    output.
2087 
2088    TYPE provides information about the type of arguments.  This is used
2089    to determine the size of integer arguments. Values larger than 'int'
2090    can be properly obtained from the argument list.  Their behavior
2091    should be considered undefined for CONV operations other than integer
2092    formatting.
2093 
2094 ===pre>
2095     TYPE  | Meaning
2096    =======|=====================
2097      hh   | sizeof(char)
2098    -------|---------------------
2099       h   | sizeof(short)
2100    -------|---------------------
2101       l   | sizeof(long)
2102    -------|---------------------
2103     L, ll | sizeof(long long)
2104    -------|---------------------
2105       j   | sizeof(int64)
2106    -------|---------------------
2107       z   | sizeof(size_t)
2108    -------|---------------------
2109 ===/pre>
2110 
2111    For 64-bit integers, "ll" may be the most widely-supported type
2112    specifier in other printf implementation, but "j" has been introduced
2113    in ISO C99. This implementation supports both.
2114 
2115    Note that arguments to variadic functions are promoted to 'int' when
2116    smaller than 'int', so 'h' and 'hh' have no observable effect.
2117    Static analysis tools that understand standard format string syntax
2118    may use this information for other purposes.
2119 
2120 Prototype:
2121 
2122    int std_strlprintf(char *pszDest, int nDestSize,
2123                       const char *pszFmt, ...);
2124 Parameters:
2125    pszDest [out]: output buffer, where output will be placed
2126    nDestSize:     size of pszDest in bytes
2127    pszFmt:        format string
2128 
2129 Return Value:
2130 
2131    The size required to hold the entire untruncated output, NOT
2132    including NUL-termination.
2133 
2134 Comments:
2135 
2136    Notable omissions from std_strlprintf() are lack of support for
2137    floating point and lack of support for "%n".
2138 
2139 Side Effects:
2140    None
2141 
2142 See Also:
2143    None
2144 
2145 =======================================================================
2146 
2147 std_vstrlprintf()
2148 
2149 Description:
2150 
2151   The std_vstrlprintf() is documented with std_strlprintf(), it's the
2152   vector form of std_strlprintf().  See std_strlprintf() for a
2153   more complete description.
2154 
2155 Prototype:
2156    int std_vstrlprintf(char *pszDest, int nDestSize,
2157                        const char *pszFmt, AEEVaList args);
2158 
2159 Parameters:
2160    pszDest [out]: output buffer, where output will be placed
2161    nDestSize:     size of pszDest in bytes
2162    pszFmt:        format string
2163    args:          arguments
2164 
2165 
2166 =======================================================================
2167 
2168 std_snprintf()
2169 
2170 Description:
2171 
2172    The functions std_snprintf() and std_vsnprintf() are similar to
2173    std_strlprintf and std_vstrlprintf that write formatted output to a
2174    string. Unlike std_strlprintf, std_snprintf also support the floating
2175    point conversion specifiers. These functions guarantee NUL-termination
2176    of the output buffer when its size is greater than zero.
2177 
2178    A format string is copied to the output buffer, except for conversion
2179    specifiers contained within the format string.  Conversion specifiers
2180    begin with a "%" and specify some action that consumes an argument from
2181    the argument list.
2182 
2183    Conversion specifiers have the following form:
2184 ===pre>
2185        %[FLAGS] [WIDTH] [.PRECISION] [TYPE] CONV
2186 ===/pre>
2187 
2188    CONV is the only required field.  It is always a single character,
2189    and determines the action to be taken.  For a detailed description of
2190    conversion sepcifiers, please refer to the documentation of
2191    std_strlprintf(). Here. we only provide description of these fields
2192    as it applies to the additional CONV values supported by
2193    std_snprintf().
2194 
2195    In addition to the values for CONV supported by std_strlprintf, this
2196    function supports the following values:
2197 
2198 ===pre>
2199     CONV | Description
2200    ======|=======================================================
2201     e, E | Outputs a double value representing a floating point
2202          | number in the style [-]d.ddd e�dd, where there is one
2203          | digit (which is nonzero if the argument is nonzero)
2204          | before the decimal-point character and the number of
2205          | digits after it is equal to the precision. If the
2206          | precision is missing, it is taken as 6. If the precision
2207          | is zero and the # flag is not specified, no decimal-point
2208          | character appears. The value is rounded to the appropriate
2209          | number of digits. The E conversion specifier produces a
2210          | number with E instead of e introducing the exponent. The
2211          | exponent always contains at least two digits, and only as
2212          | many more digits as necessary to represent the exponent.
2213          | If the value is zero, the exponent is zero.
2214          |
2215     f, F | Outputs a double value representing a floating point
2216          | number in the style [-]ddd.ddd, where the number of
2217          | digits after the decimal-point character is equal to the
2218          | precision specification. If the precision is missing, it
2219          | is taken as 6. If the precision is zero and the # flag is
2220          | not specified, no decimal-point character appears. If a
2221          | decimal-point character appears, at least one digit
2222          | appears before it. The value is rounded to the appropriate
2223          | number of digits.
2224          |
2225     g, G | Outputs a double value representing a floating point
2226          | number in the style f or e (or in style F or E in the case
2227          | of a G conversion specifier), with the precision specifying
2228          | the number of significant digits. If the precision is zero,
2229          | it is taken as 1. The style used depends on the value
2230          | converted. Style e (or E) is used only if the exponent
2231          | resulting from such a conversion is less than -4 or greater
2232          | than or equal to the precision. Trailing zeros are removed
2233          | from the fractional portion of the result unless the # flag
2234          | is specified; a decimal-point character appears only if it
2235          | is followed by a digit.
2236          |
2237     a, A | Outputs a double value representing a floating point
2238          | number in the style [-]0xh.hhhh p�d, where there is one
2239          | non-zero hexadecimal digit before the decimal-point
2240          | character and the number of hexadecimal digits after it is
2241          | equal to the precision. If the precision is missing then
2242          | the precision is assumed to be sufficient for an exact
2243          | representation of the value, except that trailing zeros
2244          | may be omitted. If the precision is zero and the # flag is
2245          | not specified, no decimal point character appears. The
2246          | letters 'abcdef' are used for '%a' conversion and the
2247          | letters ABCDEF for '%A' conversion. The '%A' conversion
2248          | specifier produces a number with 'X' and 'P' instead of 'x'
2249          | and 'p'. The exponent always contains at least one digit,
2250          | and only as many more digits as necessary to represent the
2251          | decimal exponent of 2. If the value is zero, the exponent
2252          | is zero.
2253          |
2254 ===/pre>
2255 
2256    For 'e', 'f', 'g' and 'a' convervsion specifiers, a double argument
2257    representing an infinity is converted in to the style '[-]inf' and
2258    a double argument representing a NaN is converted in to the stlye
2259    'nan'. The 'E', 'F', 'G' and 'A' conversion specifiers result in
2260    'INF' or 'NAN' instead of 'inf' or 'nan', respectively.
2261 
2262 Prototype:
2263 
2264    int std_snprintf(char *pszDest, int nDestSize,
2265                     const char *pszFmt, ...);
2266 Parameters:
2267    pszDest [out]: output buffer, where output will be placed
2268    nDestSize:     size of pszDest in bytes
2269    pszFmt:        format string
2270 
2271 Return Value:
2272 
2273    The size required to hold the entire untruncated output, NOT
2274    including NUL-termination.
2275 
2276 Comments:
2277 
2278    Notable omissions from std_strlprintf() lack of support for "%n".
2279 
2280 Side Effects:
2281    None
2282 
2283 See Also:
2284    std_strlprintf()
2285 
2286 =======================================================================
2287 
2288 std_vsnprintf()
2289 
2290 Description:
2291 
2292   The std_vsnprintf() is documented with std_snprintf(), it's the
2293   vector form of std_snprintf(). See std_snprintf() for a more complete
2294   description.
2295 
2296 Prototype:
2297    int std_vsnprintf(char *pszDest, int nDestSize,
2298                      const char *pszFmt, AEEVaList args);
2299 
2300 Parameters:
2301    pszDest [out]: output buffer, where output will be placed
2302    nDestSize:     size of pszDest in bytes
2303    pszFmt:        format string
2304    args:          arguments
2305 
2306 
2307 =======================================================================
2308 
2309 std_scanul()
2310 
2311 Description:
2312 
2313     The std_scanul() converts an ASCII representation of a number to an unsigned
2314     long.  It expects strings that match the following pattern:
2315 ===pre>
2316          spaces [+|-] digits
2317 ===/pre>
2318 
2319     'Spaces' is zero or more ASCII space or tab characters.
2320 
2321     'Digits' is any number of digits valid in the radix.  Letters 'A' through
2322     'Z' are treated as digits with values 10 through 35.  'Digits' may begin
2323     with "0x" when a radix of 0 or 16 is specified.
2324 
2325     Upper and lower case letters can be used interchangeably.
2326 
2327 
2328 Prototype:
2329 
2330     uint32 std_scanul( const char *pchBuf, int nRadix, const char **ppchEnd,
2331                        int *pnError)
2332 
2333 Parameters:
2334 
2335     pchBuf [in] : the start of the string to scan.
2336 
2337     nRadix [in] : the numeric radix (or base) of the number.  Valid values are
2338                   2 through 36 or zero, which implies auto-detection.
2339                   Auto-detection examines the digits field.  If it begins with
2340                   "0x", radix 16 is selected.  Otherwise, if it begins with
2341                   "0" radix 8 is selected.  Otherwise, radix 10 is selected.
2342 
2343     ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first
2344                     character that did not match the expected pattern shown
2345                     above, except on STD_BADPARAM and STD_OVERFLOW when it is
2346                     set to the start of the string.
2347 
2348     pnError [out] : If pnError is not NULL, *pnError holds the error code,
2349                     which is one of the following:
2350 ~
2351         0 : Numeric value is from 0 to MAX_UINT32.
2352 
2353         STD_NEGATIVE : The scanned value was negative and its absolute value was
2354                        from 1 to MAX_UINT32.  The result is the negated value
2355                        (cast to a uint32).
2356 
2357         STD_NODIGITS : No digits were found.  The result is zero.
2358 
2359         STD_OVERFLOW : The absolute value exceeded MAX_UINT32.  The result
2360                        is set to MAX_UINT32 and *ppchEnd is set to pchBuf.
2361 
2362         STD_BADPARAM : An improper value for nRadix was received.  The result
2363                        is set to zero, and *ppchEnd is set to pchBuf.
2364 *
2365 
2366 Return Value:
2367 
2368     The converted numeric result.
2369 
2370 Comments:
2371 
2372    The std_scanul() is similar to ANSI C's strtoul() but differs in the following
2373    respects:
2374 
2375      1. It returns an error/success code.  strtoul() results are ambiguous
2376         unless the caller sets errno to zero before calling it.
2377 
2378      2. std_scanul() is free of references to current locale and errno.  Some
2379         strtoul() implementations use locale; some don't.
2380 
2381      3. It provides more complete reporting of range underflow.  strtoul()
2382         does not distinguish between "-1" and "0xFFFFFFFF", and underflow is
2383         poorly defined.
2384 
2385      4. std_scanul() reports a "no digits" error code to distinguish "0" from
2386         whitespace, "+", etc..
2387 
2388 See Also:
2389 
2390    std_scanull()
2391 
2392 =======================================================================
2393 
2394 std_scanull()
2395 
2396 Description:
2397 
2398     The std_scanull() converts an ASCII representation of a number to an
2399     unsigned long long.  It expects strings that match the following pattern:
2400 ===pre>
2401          spaces [+|-] digits
2402 ===/pre>
2403 
2404     'Spaces' is zero or more ASCII space or tab characters.
2405 
2406     'Digits' is any number of digits valid in the radix.  Letters 'A' through
2407     'Z' are treated as digits with values 10 through 35.  'Digits' may begin
2408     with "0x" when a radix of 0 or 16 is specified.
2409 
2410     Upper and lower case letters can be used interchangeably.
2411 
2412 
2413 Prototype:
2414 
2415     uint64 std_scanull(const char *pchBuf, int nRadix, const char **ppchEnd,
2416                        int *pnError)
2417 
2418 Parameters:
2419 
2420     pchBuf [in] : the start of the string to scan.
2421 
2422     nRadix [in] : the numeric radix (or base) of the number.  Valid values are
2423                   2 through 36 or zero, which implies auto-detection.
2424                   Auto-detection examines the digits field.  If it begins with
2425                   "0x", radix 16 is selected.  Otherwise, if it begins with
2426                   "0" radix 8 is selected.  Otherwise, radix 10 is selected.
2427 
2428     ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first
2429                     character that did not match the expected pattern shown
2430                     above, except on STD_BADPARAM and STD_OVERFLOW when it is
2431                     set to the start of the string.
2432 
2433     pnError [out] : If pnError is not NULL, *pnError holds the error code,
2434                     which is one of the following:
2435 ~
2436         0 : Numeric value is from 0 to MAX_UINT64.
2437 
2438         STD_NEGATIVE : The scanned value was negative and its absolute value was
2439                        from 1 to MAX_UINT64.  The result is the negated value
2440                        (cast to a uint64).
2441 
2442         STD_NODIGITS : No digits were found.  The result is zero.
2443 
2444         STD_OVERFLOW : The absolute value exceeded MAX_UINT64.  The result
2445                        is set to MAX_UINT64 and *ppchEnd is set to pchBuf.
2446 
2447         STD_BADPARAM : An improper value for nRadix was received.  The result
2448                        is set to zero, and *ppchEnd is set to pchBuf.
2449 *
2450 
2451 Return Value:
2452 
2453     The converted numeric result.
2454 
2455 Comments:
2456 
2457    The std_scanull() is similar to ANSI C's strtoull() but differs in the following
2458    respects:
2459 
2460      1. It returns an error/success code.  strtoull() results are ambiguous
2461         unless the caller sets errno to zero before calling it.
2462 
2463      2. std_scanull() is free of references to current locale and errno.  Some
2464         strtoull() implementations use locale; some don't.
2465 
2466      3. It provides more complete reporting of range underflow.  strtoul()
2467         does not distinguish between "-1" and "0xFFFFFFFFFFFFFFFF", and underflow
2468         is poorly defined.
2469 
2470      4. std_scanull() reports a "no digits" error code to distinguish "0" from
2471         whitespace, "+", etc..
2472 
2473 See Also:
2474 
2475    std_scanul()
2476 
2477 =======================================================================
2478 
2479 std_qsort()
2480 
2481 Description:
2482 
2483   An implementation of the quicksort algorithm, a massively recursive,
2484   in-place sorting algorithm for an array.
2485 
2486   The contents of the array are sorted in ascending order according to
2487   the comparison function pointed to by pfnCompare.
2488 
2489   pfnCompare must return a value less than, equal to, or
2490   greater than zero if the first argument is considered to be
2491   less than, equal to, or greater than the second, respectively.
2492 
2493   std_qsort() is not a stable sort.
2494 
2495 Prototype:
2496    void std_qsort(void* pElems, int nNumElems, int nElemWidth,
2497                   int (*pfnCompare)(void*, const void*, const void*),
2498                   void* pCompareCx);
2499 
2500 
2501 Parameters:
2502    pElems: array of elements to be sorted in place.  It's size
2503            must be nNumElems * nElemWidth in bytes.
2504    nNumElems: number of elements in pElems
2505    nElemWidth: the width, in bytes of each element of pElems
2506    pfnCompare: callback comparison function, should return 0, less than
2507                zero or greater than zero if the left comparand is equal to, less
2508                than, or greater than, the right comparand, respectively.
2509    pCompareCx: the context passed as the first parameter by pfnCompare
2510 
2511 Return Value:
2512    None
2513 
2514 Comments:
2515    If nElemWidth is 2, 4, or 8, pElems is accessed internally as
2516    integer values for the purposes of reading and writing elements.
2517    Therefore, pElems must be aligned on a memory boundary compatible
2518    with integer access of the array elements.  I.e. if you pass 4 as
2519    nElemWidth, *(int*)pElems must succeed.
2520 
2521 =======================================================================
2522 
2523 std_bisect()
2524 
2525 Description:
2526 
2527    Find an element in a sorted array of elements.  Uses a binary
2528    search.
2529 
2530 Prototype:
2531    int std_bisect(const void* pElems, int nNumElems, int nElemWidth,
2532                   const void* pElemFind,
2533                   int (*pfnCompare)(void*, const void*, const void*),
2534                   void* pCompareCx);
2535 
2536 Parameters:
2537    pElems: array of elements to be searched.  It's size
2538            must be nNumElems * nElemWidth in bytes.
2539    nNumElems: number of elements in pElems
2540    nElemWidth: the width, in bytes of each element of pElems
2541    pElemFind: the element value to find in the array
2542    pfnCompare: callback comparison function, should return 0, less than
2543                zero or greater than zero if the left comparand is equal to, less
2544                than, or greater than, the right comparand, respectively.
2545    pCompareCx: the context passed as the first parameter by pfnCompare
2546 
2547 Return Value:
2548    index of the element such that pElems[index] <= elem < pElems[index + 1]
2549    nNumElems if elem is greater than all the elements in the list
2550    0 if the elem is less than or equal to the all the elements in the list
2551 
2552 =======================================================================
2553 
2554 std_merge()
2555 
2556 Description:
2557 
2558    Merge two sorted arrays into another array.
2559 
2560 Prototype:
2561    void std_merge(void* vpDst, int nDst,
2562                   const void* vpA, int nA,
2563                   const void* vpB, int nB,
2564                   int nElemWidth,
2565                   int (*pfnCompare)(void*, const void*, const void*),
2566                   void* pCompareCx);
2567 
2568 Parameters:
2569    vpDst: destination array.  It's size must be nDst * nElemWidth in bytes.
2570    nDst: number of elements that vpDst can accomodate
2571    vpA: array of elements to be merged,  it's size must be nA * nElemWidth
2572          in bytes.
2573    nA: number of elements in vpA
2574    vpB: array of elements to be merged,  it's size must be nB * nElemWidth
2575          in bytes.
2576    nB: number of elements in vpB
2577    nElemWidth: the width, in bytes of each element of pElems
2578    pfnCompare: callback comparison function, should return 0, less than
2579                zero or greater than zero if the left comparand is equal to, less
2580                than, or greater than, the right comparand, respectively.
2581    pCompareCx: the context passed as the first parameter by pfnCompare
2582 
2583 Return Value:
2584   none
2585 
2586 =======================================================================
2587 
2588 std_uniq()
2589 
2590 Description:
2591    Removes duplicate entries from a sorted array.
2592 
2593 Prototype:
2594    int std_uniq(void* vpElems, int nNumElems, int nElemWidth,
2595                 int (*pfnCompare)(void*, const void*, const void*),
2596                 void* pCompareCx);
2597 
2598 Parameters:
2599    pElems: array of elements to be searched.  It's size
2600            must be nNumElems * nElemWidth in bytes.
2601    nNumElems: number of elements in pElems
2602    nElemWidth: the width, in bytes of each element of pElems
2603    pfnCompare: callback comparison function, should return 0, less than
2604                zero or greater than zero if the left comparand is equal to, less
2605                than, or greater than, the right comparand, respectively.
2606    pCompareCx: the context passed as the first parameter by pfnCompare
2607 
2608 Return Value:
2609    the number of uniq elements left in vpElems
2610 
2611 =======================================================================
2612 
2613 std_scand()
2614 
2615 Description:
2616 
2617    The std_scand() converts the initial portion of an input ASCII string
2618    to it's corresponding floating point value. It expects the input
2619    string to match the following pattern:
2620 ===pre>
2621          <Spaces><Subject String><Rest Of The String>
2622 ===/pre>
2623 
2624    'Spaces' - is zero or more ASCII space or tab characters.
2625    'Subject String' - is the part of the input string that represents a
2626                       valid floating point constant.
2627    'Rest Of The String' - is the remaining sequence of one or more
2628                           characters including the terminating null
2629                           character of the input string.
2630 
2631    A valid subject string can be one of the following:
2632       -- <NAN>, ignoring case. This is interpreted as a quiet NAN.
2633       -- [+|-]<INF|INFINITY>, ignoring case. This is interpreted as an
2634          infinity.
2635       -- [+|-]<Valid Floating Point Number>
2636 
2637    In general, a valid floating poing number can either be a decimal
2638    number or an hexadecimal number, and has the following form:
2639       <Integral Part>[.[<Fractional Part>]][<Exponent>]
2640    where the intergral, fractional and the exponent part may consist of
2641    sequence of valid decimal or hexadecimal digits. More specifically:
2642 
2643    For a decimal floating point number:
2644       'Integral Part' - <Decimal Digits>
2645       'Fractional Part' - <Decimal Digits>
2646       'Exponent' - <e|E><Decimal Digits>
2647    For a hexadecimal floating point number:
2648       'Integral Part' - <Hexadecimal Digits>
2649       'Fractional Part' - <Hexadecimal Digits>
2650       'Exponent' - <p|P><Decimal Digits>
2651 
2652    where:
2653       'Decimal Digits' - is any number of digits in the range [0,10].
2654       'Hexadecimal Digits' - is any number of digits in the range [0,10]
2655                              or the alphabets A through F.
2656       'e','E','p','P' - represent the exponent characters
2657 
2658 Prototype:
2659 
2660     double std_scand(const char *pchBuf, const char **ppchEnd);
2661 
2662 Parameters:
2663 
2664     pchBuf [in] : the start of the string to scan.
2665 
2666     ppchEnd [out] : if ppchEnd is not NULL, *ppchEnd points to the first
2667                     character after the parsed number.
2668 
2669 Return Value:
2670 
2671     This function returns the converted numeric result. If the string
2672     does not contain a valid floating point number then the function
2673     returns zero. If the converted value is outside the range of
2674     representable values (overflow), [-]INFINITY is
2675     returned. In case of an underflow, the function returns zero.
2676 
2677 =======================================================================*/
2678 
2679 #endif // AEESTD_H
2680 
2681 
2682