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