LIB API#

API LIB Ascii
API LIB Def
API LIB Math
API LIB Memory
API LIB String
API LIB Utilities

API LIB Ascii#

ASCII_IS_ALPHA() / ASCII_IsAlpha()
ASCII_IS_ALPHA_NUM() / ASCII_IsAlphaNum()
ASCII_IS_LOWER() / ASCII_IsLower()
ASCII_IS_UPPER() / ASCII_IsUpper()
ASCII_IS_DIG() / ASCII_IsDig()
ASCII_IS_DIG_OCT() / ASCII_IsDigOct()
ASCII_IS_DIG_HEX() / ASCII_IsDigHex()
ASCII_IS_BLANK() / ASCII_IsBlank()
ASCII_IS_SPACE() / ASCII_IsSpace()
ASCII_IS_PRINT() / ASCII_IsPrint()
ASCII_IS_GRAPH() / ASCII_IsGraph()
ASCII_IS_PUNCT() / ASCII_IsPunct()
ASCII_IS_CTRL() / ASCII_IsCtrl()
ASCII_TO_LOWER() / ASCII_ToLower()
ASCII_TO_UPPER() / ASCII_ToUpper()
ASCII_Cmp()

ASCII_IS_ALPHA() / ASCII_IsAlpha()#

Description#

Determines whether a character is an alphabetic character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsAlpha (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is alphabetic.
DEF_NO, the character is NOT alphabetic.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.2.(2) states that "isalpha() returns true only for the characters for which isupper() or islower() is true".

ASCII_IS_ALPHA_NUM() / ASCII_IsAlphaNum()#

Description#

Determines whether a character is an alphanumeric character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsAlphaNum (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is alphanumeric.
DEF_NO , the character is NOT alphanumeric.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.1.(2) states that "isalnum() ... tests for any character for which isalpha() or isdigit() is true".

ASCII_IS_LOWER() / ASCII_IsLower()#

Description#

Determines whether a character is a lowercase alphabetic character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsLower (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is lowercase alphabetic.
DEF_NO, the character is lowercase alphabetic.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.7.(2) states that "islower() returns true only for the lowercase letters".

ASCII_IS_UPPER() / ASCII_IsUpper()#

Description#

Determines whether a character is an uppercase alphabetic character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsUpper (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is uppercase alphabetic.
DEF_NO, the character is uppercase alphabetic.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.11.(2) states that "isupper() returns true only for the uppercase letters".

ASCII_IS_DIG() / ASCII_IsDig()#

Description#

Determines whether a character is a decimal-digit character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsDig (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a decimal-digit character.
DEF_NO, the character is NOT a decimal-digit character.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.5.(2) states that "isdigit() ... tests for any decimal-digit character".

ASCII_IS_DIG_OCT() / ASCII_IsDigOct()#

Description#

Determines whether a character is an octal-digit character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsDigOct (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is an octal-digit.
DEF_NO, the character is NOT an octal-digit.

Notes / Warnings#

None.

ASCII_IS_DIG_HEX() / ASCII_IsDigHex()#

Description#

Determine whether a character is a hexadecimal-digit character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsDigHex (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a hexadecimal-digit character.
DEF_NO, the character is NOT a hexadecimal-digit character.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.12.(2) states that "isxdigit() ... tests for any hexadecimal-digit character".

ASCII_IS_BLANK() / ASCII_IsBlank()#

Description#

Determines whether a character is a standard blank character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsBlank (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a standard blank character.
DEF_NO, the character is NOT a standard blank character.

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.1.3.(2) states that "isblank() returns true only for the standard blank characters".
(b) ISO/IEC 9899:TC2, Section 7.4.1.3.
defines "the standard blank characters" as the "space (' '), and horizontal tab ('\t')".

ASCII_IS_SPACE() / ASCII_IsSpace()#

Description#

Determines whether a character is a white-space character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsSpace (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a white-space character.
DEF_NO, the character is NOT a white-space character.

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.1.10.(2) states that "isspace() returns true only for the standard white-space characters".
(b) ISO/IEC 9899:TC2, Section 7.4.1.10.(2) defines "the standard white-space characters" as the "space (' '), form feed ('\f'), new-line ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v')".

ASCII_IS_PRINT() / ASCII_IsPrint()#

Description#

Determines whether a character is a printing character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsPrint (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a printing character.
DEF_NO, the character is NOT a printing character.

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.1.8.(2) states that "isprint() ... tests for any printing character including space (' ')".
(b) ISO/IEC 9899:TC2, Section 7.4.(3), Note 169, states that in "the 7-bit US ASCII character set, the printing characters are those whose values lie from 0x20 (space) through 0x7E (tilde)".

ASCII_IS_GRAPH() / ASCII_IsGraph()#

Description#

Determines whether a character is any printing character except a space character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsGraph (CPU_CHAR  c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a graphic.
DEF_NO, the character is NOT a graphic.

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.1.6.(2) states that "isgraph() ... tests for any printing character except space (' ')".
(b) ISO/IEC 9899:TC2, Section 7.4.(3), Note 169, states that in "the 7-bit US ASCII character set, the printing characters are those whose values lie from 0x20 (space) through 0x7E (tilde)".

ASCII_IS_PUNCT() / ASCII_IsPunct()#

Description#

Determines whether a character is a punctuation character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsPunct (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is punctuation.
DEF_NO, the character is NOT punctuation.

Notes / Warnings#

ISO/IEC 9899:TC2, Section 7.4.1.9.(2) states that "ispunct() returns true for every printing character for which neither isspace() nor isalnum() is true".

ASCII_IS_CTRL() / ASCII_IsCtrl()#

Description#

Determines whether a character is a control character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

  CPU_BOOLEAN  ASCII_IsCtrl (CPU_CHAR   c)

Arguments#

c

Character to examine.

Returned Value#

DEF_YES, the character is a control character.
DEF_NO, the character is NOT a control character.

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.1.4.(2) states that "iscntrl() ... tests for any control character".
(b) ISO/IEC 9899:TC2, Section 7.4.(3), Note 169, states that in "the 7-bit US ASCII character set, ... the control characters are those whose values lie from 0 (NUL) through 0x1F (US), and the character 0x7F (DEL)".

ASCII_TO_LOWER() / ASCII_ToLower()#

Description#

Converts an uppercase alphabetic character to its corresponding lowercase alphabetic character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

CPU_CHAR  ASCII_ToLower (CPU_CHAR   c)

Arguments#

c

Character to convert.

Returned Value#

Lowercase equivalent of 'c', the character 'c' is an uppercase character (see Note #1b1).

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.2.1.(2) states that "tolower() ... converts an uppercase letter to a corresponding lowercase letter".
(b) ISO/IEC 9899:TC2, Section 7.4.2.1.(3) states that :
1. (A) "if the argument is a character for which isupper() is true and there are one or more corresponding characters ... for which islower() is true,".
  (B) "tolower() ... returns one of the corresponding characters".
2. "otherwise, the argument is returned unchanged."

ASCII_TO_UPPER() / ASCII_ToUpper()#

Description#

Converts a lowercase alphabetic character to its corresponding uppercase alphabetic character.

Files#

lib_ascii.h/lib_ascii.c

Prototype#

CPU_CHAR  ASCII_ToUpper (CPU_CHAR   c)

Arguments#

c

Character to convert.

Returned Value#

Uppercase equivalent of 'c', the character 'c' is a lowercase character (see Note #1b1).

Notes / Warnings#

(a) ISO/IEC 9899:TC2, Section 7.4.2.2. (2) states that "toupper() ... converts a lowercase letter to a corresponding uppercase letter".
(b) ISO/IEC 9899:TC2, Section 7.4.2.2.(3) states that :
1. (A)"if the argument is a character for which islower() is true and there are one or more corresponding characters ... for which isupper() is true," ...
  (B) "toupper() ... returns one of the corresponding characters" ...
2. "otherwise, the argument is returned unchanged."

ASCII_Cmp()#

Description#

Determines if two characters are identical (case-insensitive).

Files#

lib.ascii.h/lib.ascii.c

Prototype#

ASCII_Cmp (CPU_CHAR     c1,
           CPU_CHAR     c2)

Arguments#

c1

First character.

c2

Second character.

Returned Value#

DEF_YES, the characters are identical.
DEF_NO, the characters are different.

Notes / Warnings#

None.

DEF_CHK_VAL_MIN()#

Description#

Validate a value as greater than or equal to a specified minimum value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_CHK_VAL_MIN (val, val_min)

Arguments#

val

Value to validate.

val_min

Minimum value to test.

Returned Value#

DEF_OK, Value is greater than or equal to minimum value.

Notes / Warnings#

DEF_CHK_VAL_MIN() avoids directly comparing any two values if only one of the values is negative since the negative value might be incorrectly promoted to an arbitrary unsigned value if the other value to compare is unsigned.
Validation of values is limited to the range supported by the compiler &/or target environment. All other values that underflow/overflow the supported range will modulo/wrap into the supported range as arbitrary signed or unsigned values.
(a) Note that the most negative value, -2^(N-1), is NOT included in the supported range since many compilers do NOT always correctly handle this value.
'val' and 'val_min' are compared to 1 instead of 0 to avoid warning generated for unsigned numbers.

DEF_CHK_VAL_MAX()#

Description#

Validate a value as less than or equal to a specified maximum value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_CHK_VAL_MAX (val, val_max)

Arguments#

val

Value to validate.

val_max

Maximum value to test.

Returned Value#

DEF_OK, Value is less than or equal to maximum value.

Notes / Warnings#

DEF_CHK_VAL_MAX() avoids directly comparing any two values if only one of the values is negative since the negative value might be incorrectly promoted to an arbitrary unsigned value if the other value to compare is unsigned.
Validation of values is limited to the range supported by the compiler &/or target environment. All other values that underflow/overflow the supported range will modulo/wrap into the supported range as arbitrary signed or unsigned values.
(a) Note that the most negative value, -2^(N-1), is NOT included in the supported range since many compilers do NOT always correctly handle this value.
'val' and 'val_max' are compared to 1 instead of 0 to avoid warning generated for unsigned numbers.

DEF_CHK_VAL()#

Description#

Validate a value as greater than or equal to a specified minimum value & less than or equal to a specified maximum value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_CHK_VAL (val, val_min, val_max)

Arguments#

val

Value to validate.

val_min

Minimum value to test.

val_max

Maximum value to test.

Returned Value#

DEF_OK, Value is greater than or equal to minimum value AND less than or equal to maximum value.

Notes / Warnings#

DEF_CHK_VAL() avoids directly comparing any two values if only one of the values is negative since the negative value might be incorrectly promoted to an arbitrary unsigned value if the other value to compare is unsigned.
Validation of values is limited to the range supported by the compiler &/or target environment. All other values that underflow/overflow the supported range will modulo/wrap into the supported range as arbitrary signed or unsigned values.
(a) Note that the most negative value, -2^(N-1), is NOT included in the supported range since many compilers do NOT always correctly handle this value.
DEF_CHK_VAL() does NOT validate that the maximum value ('val_max') is greater than or equal to the minimum value ('val_min').

DEF_MIN()#

Description#

Determine the minimum of two values.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_MIN (a, b)

Arguments#

a

First value.

b

Second value.

Returned Value#

Minimum of the two values.

Notes / Warnings#

None.

DEF_MAX()#

Description#

Determine the maximum of two values.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_MAX (a, b)

Arguments#

a

First value.

b

Second value.

Returned Value#

Maximum of the two values.

Notes / Warnings#

None.

DEF_ABS()#

Description#

Determine the absolute value of a value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_ABS (a)

Arguments#

a

Value to calculate absolute value.

Returned Value#

Absolute value of the value.

Notes / Warnings#

None.

DEF_IS_ADDR_ALIGNED()#

Description#

Determine if specified address is aligned.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_ADDR_IS_ALIGNED (addr, align)

Arguments#

addr

Memory address to evaluate.

align

Alignment needed (in bytes).

Returned Value#

DEF_YES Address is aligned.

Notes / Warnings#

Align value MUST be a power of 2.

API LIB Math#

Math_RandSetSeed()
Math_Rand()
Math_RandSeed()
Math_Init()
MATH_IS_PWR2()
MATH_ROUND_INC_UP_PWR2()
MATH_ROUND_INC_UP()

Math_RandSetSeed()#

Description#

Sets the current pseudo-random number generator seed.

Files#

lib_math.h/lib_math.c

Prototype#

void Math_RandSetSeed (RAND_NBR  seed)

Arguments#

seed

Initial (or current) value to set for the pseudo-random number sequence.

Returned Value#

None.

Notes / Warnings#

IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "srand() ... uses the argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand()".
'Math_RandSeedCur' MUST always be accessed exclusively in critical sections. See also 'Math_Rand() Note #1b'.

Math_Rand()#

Description#

Calculates the next pseudo-random number.

Files#

lib_math.h/lib_math.c

Prototype#

RAND_NBR Math_Rand (void)

Arguments#

None.

Returned Value#

Next pseudo-random number in the sequence after 'Math_RandSeedCur'.

Notes / Warnings#

See 'Math_RandSeed() Note #1'.
(a) The pseudo-random number generator is implemented as a Linear Congruential Generator (LCG).
(b) The pseudo-random number generated is in the range [0, RAND_LCG_PARAM_M].
See 'Math_RandSeed() Note #2'.
(a) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "rand() ... need not be reentrant ... [and] is not required to be thread-safe".
(b) However, to implement Math_Rand() as re-entrant; 'Math_RandSeedCur' MUST always be accessed & updated exclusively in critical sections.

Math_RandSeed()#

Description#

Calculates the next pseudo-random number.

Files#

lib_math.h/lib_math.c

Prototype#

RAND_NBR Math_RandSeed (RAND_NBR   seed)

Arguments#

seed

Initial (or current) value for the pseudo-random number sequence.

Returned Value#

Next pseudo-random number in the sequence after 'seed'.

Notes / Warnings#

See 'lib_math.h RANDOM NUMBER DEFINES Note #1b'.
(a) BSD/ANSI-C implements rand() as a Linear Congruential Generator (LCG):
random_number = [(a \* random_number ) + b] modulo m
1. (a) random_number on the left: Next random number to generate (b) random_number on the right: Previous random number generated
2. a = RAND_LCG_PARAM_A LCG multiplier
3. b = RAND_LCG_PARAM_B LCG incrementor
4. m = RAND_LCG_PARAM_M + 1 LCG modulus
(b) The pseudo-random number generated is in the range [0, ][0, `RAND_LCG_PARAM_M`].
(a) IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "rand() ... need not be reentrant ... [and] is not required to be thread-safe".
(b) However, Math_RandSeed() is re-entrant since it calculates the next random number using ONLY local variables.

Math_Init()#

Description#

Initializes the Mathematic Module.

Files#

lib_math.h/lib_math.c

Prototype#

void Math_Init (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

IEEE Std 1003.1, 2004 Edition, Section 'rand() : DESCRIPTION' states that "if rand() is called before any calls to srand() are made, the same sequence shall be generated as when srand() is first called with a seed value of 1".
The following function is deprecated. Unless already used, it should no longer be used, since they will be removed in a future version.

MATH_IS_PWR2()#

Description#

Determine if a value is a power of 2.

Files#

lib_math.h/lib_math.c

Prototype#

    MATH_IS_PWR2 (nbr)

Arguments#

nbr

Value.

Returned Value#

DEF_YES, 'nbr' is a power of 2.

Notes / Warnings#

None.

MATH_ROUND_INC_UP_PWR2()#

Description#

Round value up to the next (power of 2) increment.

Files#

lib_math.h/lib_math.c

Prototype#

    MATH_ROUND_INC_UP_PWR2(nbr, inc)

Arguments#

nbr

Value to round.

inc

Increment to use. MUST be a power of 2.

Returned Value#

Rounded up value.

Notes / Warnings#

None.

MATH_ROUND_INC_UP()#

Description#

Round value up to the next increment.

Files#

lib_math.h/lib_math.c

Prototype#

    MATH_ROUND_INC_UP(nbr, inc)

Arguments#

nbr

Value to round.

inc

Increment to use.

Returned Value#

Rounded up value.

Notes / Warnings#

None.

API LIB Memory#

Mem_Clr()
Mem_Set()
Mem_Copy()
Mem_Move()
Mem_Cmp()
Mem_SegCreate()
MEM_SEG_INIT()
Mem_SegReg()
Mem_SegClr()
Mem_SegAlloc()
Mem_SegAllocExt()
Mem_SegAllocHW()
Mem_SegRemSizeGet()
Mem_OutputUsage()
Mem_DynPoolCreate()
Mem_DynPoolCreatePersistent()
Mem_DynPoolCreateHW()
Mem_DynPoolBlkNbrAvailGet()
Mem_DynPoolBlkGet()
Mem_DynPoolBlkFree()
MEM_VAL_BIG_TO_LITTLE_xx() / MEM_VAL_LITTLE_TO_BIG_xx()
MEM_VAL_BIG_TO_HOST_xx() / MEM_VAL_HOST_TO_BIG_xx()
MEM_VAL_LITTLE_TO_HOST_xx() / MEM_VAL_HOST_TO_LITTLE_xx()
MEM_VAL_GET_INTxxU_xxx()
MEM_VAL_SET_INTxxU_xxx()
MEM_VAL_COPY_GET_INTxxU_xxx()
MEM_VAL_COPY_GET_INTU_xxx()
MEM_VAL_COPY_SET_INTxxU_xxx()
MEM_VAL_COPY_SET_INTU_xxx()
MEM_VAL_COPY_xx()

Mem_Clr()#

Description#

Clears the data buffer (see Note #2).

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_STD_C_LIB_EN == DEF_DISABLED)
void  Mem_Clr (void        \*p_mem,
               CPU_SIZE_T   size)

Arguments#

p_mem

Pointer to the memory buffer to clear.

size

Number of data buffer octets to clear (see Note #1).

Returned Value#

None.

Notes / Warnings#

Null clears are allowed (i.e. zero-length clears). See also 'Mem_Set() Note #1'.

Mem_Set()#

Description#

Fills the data buffer with specified data octet.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_STD_C_LIB_EN == DEF_DISABLED)

void Mem_Set (void         \*p_mem,
              CPU_INT08U    data_val,
              CPU_SIZE_T    size)

Arguments#

p_mem

Pointer to the memory buffer to fill with the specified data octet.

data_val

Data filled octet value.

size

Number of data buffer octets to fill (see Note #1).

Returned Value#

None.

Notes / Warnings#

Null sets are allowed (i.e. zero-length sets).
For the best CPU performance, this function fills the data buffer using 'CPU_ALIGN'-sized data words. Since many word-aligned processors REQUIRE that multi-octet words be accessed on word-aligned addresses, 'CPU_ALIGN'-sized words MUST be accessed on 'CPU_ALIGN' addresses.*
Modulo arithmetic determines if a memory buffer starts on a 'CPU_ALIGN' address boundary.

Modulo arithmetic in ANSI-C REQUIREs operations are performed on integer values, so address values MUST be cast to an appropriately-sized integer value before any 'mem_align_mod' arithmetic operation.

Mem_Copy()#

Description#

Copies data octets from one memory buffer to another memory buffer.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_STD_C_LIB_EN == DEF_DISABLED)
void Mem_Copy (       void        \*p_dest,
                const void        \*p_src,
                      CPU_SIZE_T   size)

Arguments#

p_dest

Pointer to the destination memory buffer.

p_src

Pointer to the source memory buffer.

size

Number of octets to copy (see Note #1).

Returned Value#

None.

Notes / Warnings#

Null copies are allowed (i.e. zero-length copies).
Memory buffers NOT checked for overlapping.
(a) IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "if copying takes place between objects that overlap, the behavior is undefined".
(b) Data octets from a source memory buffer at a higher address value SHOULD successfully copy to a destination memory buffer at a lower address value. This occurs even if any octets of the memory buffers overlap, as long as there are no individual, atomic CPU word copy overlaps.
For the best CPU performance, this function copies data buffers using 'CPU_ALIGN'-sized data words. Since many word-aligned processors REQUIRE that multi-octet words be accessed on word-aligned addresses, 'CPU_ALIGN'-sized words MUST be accessed on 'CPU_ALIGN' addresses.
Modulo arithmetic determines if a memory buffer starts on a 'CPU_ALIGN' address boundary.

Modulo arithmetic in ANSI-C REQUIRE operations are performed on integer values, so address values MUST be cast to an appropriately-sized integer value before any 'mem_align_mod' arithmetic operation.

Mem_Move()#

Description#

Moves data octets from one memory buffer to another memory buffer, or within the same memory buffer. Overlapping is correctly handled for all move operations.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_STD_C_LIB_EN == DEF_DISABLED)
void Mem_Move (       void        *p_dest,
                const void        *p_src,
                      CPU_SIZE_T   size)

Arguments#

p_dest

Pointer to destination memory buffer.

p_src

Pointer to source memory buffer.

size

Number of octets to move (see Note #1).

Returned Value#

None.

Notes / Warnings#

Null move operations are allowed (i.e. zero-length).
Memory buffers checked for overlapping.
For the best CPU performance, this function copies data buffer using 'CPU_ALIGN'-sized data words. Since many word-aligned processors REQUIRE that multi-octet words be accessed on word-aligned addresses, 'CPU_ALIGN'-sized words MUST be accessed on 'CPU_ALIGN'd addresses.
Modulo arithmetic determines if a memory buffer starts on a 'CPU_ALIGN' address boundary.

Modulo arithmetic in ANSI-C REQUIREs operations performed on integer values, so address values MUST be cast to an appropriately-sized integer value before any 'mem_align_mod' arithmetic operation.

Mem_Cmp()#

Description#

Verifies that ALL data octets in the two memory buffers are identical in sequence.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_STD_C_LIB_EN == DEF_DISABLED)
CPU_BOOLEAN  Mem_Cmp (const  void        *p1_mem,
                      const  void        *p2_mem,
                             CPU_SIZE_T   size)

Arguments#

p1_mem

Pointer to first memory buffer.

p2_mem

Pointer to second memory buffer.

size

Number of data buffer octets to compare (see Note #1).

Returned Value#

DEF_YES, if the 'size' of data octets is identical in both memory buffers.
DEF_NO, if the 'size' of data octets is different in both memory buffers.

Notes / Warnings#

Null compares are allowed (i.e. zero-length compares); 'DEF_YES' is returned to indicate identical null compare.
Many memory buffer comparisons vary ONLY in the least significant octets (e.g., network address buffers). Consequently, memory buffer comparison is more efficient if the comparison starts from the end of the memory buffers. This aborts sooner on dissimilar memory buffers that vary only in the least significant octets.
For the best CPU performance, this function compares data buffers using 'CPU_ALIGN'-sized data words. Since many word-aligned processors REQUIRE that multi-octet words be accessed on word-aligned addresses, 'CPU_ALIGN'-sized words MUST be accessed on 'CPU_ALIGN'd addresses.
Modulo arithmetic determines if a memory buffer starts on a 'CPU_ALIGN' address boundary.

Modulo arithmetic in ANSI-C REQUIREs operations performed on integer values, so address values MUST be cast to an appropriately-sized integer value before any 'mem_align_mod' arithmetic operation.

Mem_SegCreate()#

Description#

Creates a new memory segment to be used for runtime memory allocation.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_SegCreate (const CPU_CHAR     *p_name,
                          MEM_SEG      *p_seg,
                          CPU_ADDR      seg_base_addr,
                          CPU_SIZE_T    size,
                          CPU_SIZE_T    padding_align,
                          RTOS_ERR     *p_err)

Arguments#

p_name

Pointer to segment name.

p_seg

Pointer to segment data. Must be allocated by caller.

seg_base_addr

Address of segment's first byte.

size

Total size of segment (in bytes).

padding_align

Padding alignment (in bytes) that will be added to any allocated buffer from this memory segment. MUST be a power of 2. LIB_MEM_PADDING_ALIGN_NONE means no padding.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

New segments are checked for overlap with existing segments. A critical section must be maintained during the whole list search and adds a procedure to prevent a re-entrant call from creating another segment that would overlaps with the new one.

MEM_SEG_INIT()#

Description#

Creates a new memory segment to be used for runtime memory allocation. Created segment will not be added to list checked for overlap or to debug, it must be added afterwards by calling the Mem_SegReg() function.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_SEG_INIT (p_name, seg_base_addr, size, padding_align)

Arguments#

p_name

Pointer to segment name.

seg_base_addr

Address of segment's first byte.

size

Total size of segment (in bytes).

padding_align

Padding alignment (in bytes) that will be added to any allocated buffer from this memory segment. MUST be a power of 2. LIB_MEM_PADDING_ALIGN_NONE means no padding.

Returned Value#

None.

Notes / Warnings#

Contrary to the Mem_SegCreate() function, this segment is not checked for overlap at run-time. Therefore, extra care should be taken when using this macro.
Usage is as follows:

MEM_SEG My_MemSeg = MEM_SEG_INIT("My Segment", (CPU_ADDR)&My_SegmentData[0u],
                                  MY_SEGMENT_SIZE, LIB_MEM_CFG_HEAP_PADDING_ALIGN);

Mem_SegReg()#

Description#

Registers a memory segment that was created at compile-time to enable both usage output and overlap checks when creating a new memory segment.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_SegReg (MEM_SEG   *p_seg,
                 RTOS_ERR  *p_err)

Arguments#

p_seg

Pointer to segment data already created.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_ALREADY_EXISTS

Returned Value#

None.

Notes / Warnings#

None.

Mem_SegClr()#

Description#

Clears a memory segment.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_DBG_INFO_EN == DEF_DISABLED)
void Mem_SegClr (MEM_SEG   \*p_seg,
                 RTOS_ERR  \*p_err)

Arguments#

p_seg

Pointer to segment data and must be allocated by caller.

p_err

Pointer to a variable that will receive the following return error code from this function :

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

Use this function with extreme caution. It must only be called on memory segments that are no longer used.
This function is disabled when debug mode is enabled to avoid heap memory leaks.

Mem_SegAlloc()#

Description#

Allocates memory from a specified segment. The returned memory block will be aligned on a CPU word boundary.

Files#

lib_mem.h/lib_mem.c

Prototype#

void *Mem_SegAlloc (const CPU_CHAR   *p_name,
                    MEM_SEG          *p_seg,
                    CPU_SIZE_T        size,
                    RTOS_ERR         *p_err)

Arguments#

p_name

Pointer to the allocated object name, which may track allocations. May be DEF_NULL.

p_seg

Pointer to the segment from which to allocate memory. If NULL, it will allocate from the general-purpose heap.

size

Size of memory block to allocate (bytes).

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_SEG_OVF

Returned Value#

Pointer to allocated memory block, if successful.
DEF_NULL, if the memory is not allocated.

Notes / Warnings#

The memory block returned by this function will be aligned on a word boundary. To specify an alignment value, use either Mem_SegAllocExt() or Mem_SegAllocHW().
No logging can be done in this function or called functions, since they may be used before the logging mechanism is initialized.

Mem_SegAllocExt()#

Description#

Allocates memory from specified memory segment.

Files#

lib_mem.h/lib_mem.c

Prototype#

void *Mem_SegAllocExt (const CPU_CHAR    *p_name,
                             MEM_SEG     *p_seg,
                             CPU_SIZE_T   size,
                             CPU_SIZE_T   align,
                             CPU_SIZE_T  *p_bytes_reqd,
                             RTOS_ERR    *p_err)

Arguments#

p_name

Pointer to allocated object name, which may track allocations. May be DEF_NULL.

p_seg

Pointer to segment from which to allocate memory. If NULL, it will allocate from the general-purpose heap.

size

Size of memory block to allocate (in bytes).

align

Required alignment of memory block (in bytes). MUST be a power of 2.

p_bytes_reqd

Pointer to a variable that will receive the number of free bytes missing for the allocation to succeed. Set to DEF_NULL to skip calculation.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_SEG_OVF

Returned Value#

Pointer to allocated memory block, if successful.

DEF_NULL, if memory is not allocated.

Notes / Warnings#

None.

Mem_SegAllocHW()#

Description#

Allocates memory from specified segment. The returned buffer will be padded in function of memory segment's properties.

Files#

lib_mem.h/lib_mem.c

Prototype#

void *Mem_SegAllocHW (const CPU_CHAR     *p_name,
                            MEM_SEG      *p_seg,
                            CPU_SIZE_T    size,
                            CPU_SIZE_T    align,
                            CPU_SIZE_T   *p_bytes_reqd,
                            RTOS_ERR     *p_err)

Arguments#

p_name

Pointer to allocated object name, which may track allocations. May be DEF_NULL.

p_seg

Pointer to segment from which to allocate memory. If NULL, it will allocate from the general-purpose heap.

size

Size of memory block to allocate (in bytes).

align

Required alignment of memory block (in bytes). MUST be a power of 2.

p_bytes_reqd

Pointer to a variable that will receive the number of free bytes missing for the allocation to succeed. Set to DEF_NULL to skip calculation.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_SEG_OVF

Returned Value#

Pointer to allocated memory block, if successful.

DEF_NULL, if memory is not allocated.

Notes / Warnings#

None.

Mem_SegRemSizeGet()#

Description#

Calculates the remaining free space in the memory segment.

Files#

lib_mem.h/lib_mem.c

Prototype#

CPU_SIZE_T Mem_SegRemSizeGet (MEM_SEG        *p_seg,
                              CPU_SIZE_T      align,
                              MEM_SEG_INFO   *p_seg_info,
                              RTOS_ERR       *p_err)

Arguments#

p_seg

Pointer to segment data.

align

Alignment in bytes to assume for calculation of free space.

p_seg_info

Pointer to structure that will receive further segment info data (used size, total size, base address, and next allocation address).

p_err

Pointer to a variable that will receive the following return error code from this function :

RTOS_ERR_NONE

Returned Value#

The amount of free space in the memory segment (bytes), if successful.
0, otherwise or if the memory segment empty.

Notes / Warnings#

None.

Mem_OutputUsage()#

Description#

Outputs the memory usage report through 'out_fnct'.

Files#

lib_mem.h/lib_mem.c

Prototype#

#if (LIB_MEM_CFG_DBG_INFO_EN == DEF_ENABLED)
void  Mem_OutputUsage(void      (\*out_fnct) (CPU_CHAR  \*p_str),
                      RTOS_ERR   \*p_err)

Arguments#

out_fnct

Pointer to output function.

p_err

Pointer to a variable that will receive the following return error code from this function :

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

Mem_DynPoolCreate()#

Description#

Creates a dynamic memory pool.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_DynPoolCreate (const CPU_CHAR      *p_name,
                              MEM_DYN_POOL  *p_pool,
                              MEM_SEG       *p_seg,
                              CPU_SIZE_T     blk_size,
                              CPU_SIZE_T     blk_align,
                              CPU_SIZE_T     blk_qty_init,
                              CPU_SIZE_T     blk_qty_max,
                              RTOS_ERR      *p_err)

Arguments#

p_name

Pointer to a pool name.

p_pool

Pointer to a pool data.

p_seg

Pointer to segment from which to allocate memory. If NULL, it will allocate from the general-purpose heap.

blk_size

Size of memory block to allocate from pool (in bytes). See Note #1.

blk_align

Required alignment of memory block (in bytes). MUST be a power of 2.

blk_qty_init

Initial number of elements to be allocated in pool.

blk_qty_max

Maximum number of elements that can be allocated from this pool. Set to LIB_MEM_BLK_QTY_UNLIMITED if there is no limit.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

'blk_size' must be big enough to fit a pointer since the pointer to the next free block is stored in the block itself (only when free/unused).

Mem_DynPoolCreatePersistent()#

Description#

Creates a persistent dynamic memory pool.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_DynPoolCreatePersistent (const CPU_CHAR           *p_name,
                                  MEM_DYN_POOL             *p_pool,
                                  MEM_SEG                  *p_seg,
                                  CPU_SIZE_T                blk_size,
                                  CPU_SIZE_T                blk_align,
                                  CPU_SIZE_T                blk_qty_init,
                                  CPU_SIZE_T                blk_qty_max,
                                  MEM_DYN_POOL_ALLOC_FNCT   alloc_callback,
                                  void                     *p_callback_arg,
                                  RTOS_ERR                 *p_err)

Arguments#

p_name

Pointer to a pool name.

p_pool

Pointer to a pool data.

p_seg

Pointer to segment from which to allocate memory.

blk_size

Size of memory block to allocate from pool (in bytes). See Note #1.

blk_align

Required alignment of memory block (in bytes). MUST be a power of 2.

blk_qty_init

Initial number of elements to be allocated in pool.

blk_qty_max

Maximum number of elements that can be allocated from this pool. Set to LIB_MEM_BLK_QTY_UNLIMITED if there is no limit.

alloc_callback

Function that will be called the first time each block is allocated.

p_callback_arg

Pointer to argument that will be passed to callback.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

'blk_size' must be big enough to fit a pointer since the pointer to the next free block is stored in the block itself (only when free/unused).

Mem_DynPoolCreateHW()#

Description#

Creates a dynamic memory pool. Memory blocks will be padded according to memory segment's properties.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_DynPoolCreateHW (const CPU_CHAR      *p_name,
                                MEM_DYN_POOL  *p_pool,
                                MEM_SEG       *p_seg,
                                CPU_SIZE_T     blk_size,
                                CPU_SIZE_T     blk_align,
                                CPU_SIZE_T     blk_qty_init,
                                CPU_SIZE_T     blk_qty_max,
                                RTOS_ERR      *p_err)

Arguments#

p_name

Pointer to a pool name.

p_pool

Pointer to a pool data.

p_seg

Pointer to the segment from which to allocate memory. If NULL, it will allocate from the general-purpose heap.

blk_size

Size of memory block to allocate from pool (in bytes). See Note #1.

blk_align

Required alignment of memory block (in bytes). MUST be a power of 2.

blk_qty_init

Initial number of elements to be allocated in pool.

blk_qty_max

Maximum number of elements that can be allocated from this pool. Set to LIB_MEM_BLK_QTY_UNLIMITED if no limit.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

'blk_size' must be big enough to fit a pointer since the pointer to the next free block is stored in the block itself (only when free/unused).

Mem_DynPoolBlkNbrAvailGet()#

Description#

Gets a number of available blocks in dynamic memory pool. If 'p_pool_info' is DEF_NULL, this call will fail with a dynamic memory pool for which no limit was set at creation.

Files#

lib_mem.h/lib_mem.c

Prototype#

CPU_SIZE_T Mem_DynPoolBlkNbrAvailGet (MEM_DYN_POOL       *p_pool,
                                      MEM_DYN_POOL_INFO  *p_pool_info,
                                      RTOS_ERR           *p_err)

Arguments#

p_pool

Pointer to a pool data.

p_pool_info

Pointer to MEM_DYN_POOL_INFO that will be filled by this function. If DEF_NULL and if pool has a block limit, only the number of blocks remaining is returned.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_POOL_UNLIMITED

Returned Value#

Number of blocks remaining in dynamic memory pool, if successful.

0, if pool is empty or if an error occurred.

Notes / Warnings#

None.

Mem_DynPoolBlkGet()#

Description#

Gets a memory block from specified pool, growing it if needed.

Files#

lib_mem.h/lib_mem.c

Prototype#

void *Mem_DynPoolBlkGet (MEM_DYN_POOL  *p_pool,
                         RTOS_ERR      *p_err)

Arguments#

p_pool

Pointer to a pool data.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_POOL_EMPTY
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF

Returned Value#

Pointer to memory block, if successful.

DEF_NULL, if it is not successful.

Notes / Warnings#

None.

Mem_DynPoolBlkFree()#

Description#

Frees a memory block, making it available for future use.

Files#

lib_mem.h/lib_mem.c

Prototype#

void Mem_DynPoolBlkFree (MEM_DYN_POOL  *p_pool,
                         void          *p_blk,
                         RTOS_ERR      *p_err)

Arguments#

p_pool

Pointer to a pool data.

p_blk

Pointer to first byte of memory block.

p_err

Pointer to a variable that will receive the following return error codes from this function :

RTOS_ERR_NONE
RTOS_ERR_POOL_FULL

Returned Value#

None.

Notes / Warnings#

None.

MEM_VAL_BIG_TO_LITTLE_xx() / MEM_VAL_LITTLE_TO_BIG_xx()#

Description#

Convert data values to & from big- or little-endian CPU word order.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_BIG_TO_LITTLE_16 (val)

    MEM_VAL_BIG_TO_LITTLE_32 (val)

    MEM_VAL_LITTLE_TO_BIG_16 (val)

    MEM_VAL_LITTLE_TO_BIG_32 (val)

Arguments#

val

Data value to convert (see Notes #1 & #2).

Returned Value#

Converted data value (see Notes #1 & #2).

Notes / Warnings#

Convert data values to the desired data-word order :
'val' data value to convert & any variable to receive the returned conversion MUST start on appropriate CPU word-aligned addresses.
MEM_VAL_COPY_xxx() macro's are more efficient than generic endian word order macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
Generic endian word order macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_BIG_TO_HOST_xx() / MEM_VAL_HOST_TO_BIG_xx()#

Description#

Convert data values to & from big- or host-endian CPU word order.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_BIG_TO_HOST_16 (val)

    MEM_VAL_BIG_TO_HOST_32 (val)

    MEM_VAL_HOST_TO_BIG_16 (val)

    MEM_VAL_HOST_TO_BIG_32 (val)

Arguments#

val

Data value to convert (see Notes #1 & #2).

Returned Value#

Converted data value (see Notes #1 & #2).

Notes / Warnings#

Convert data values to the desired data-word order :
'val' data value to convert & any variable to receive the returned conversion MUST start on appropriate CPU word-aligned addresses.
MEM_VAL_COPY_xxx() macro's are more efficient than generic endian word order macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
Generic endian word order macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_LITTLE_TO_HOST_xx() / MEM_VAL_HOST_TO_LITTLE_xx()#

Description#

Convert data values to & from little- or host-endian CPU word order.

Files#

lib_mem.h/lib_mem.c

Prototype#

MEM_VAL_LITTLE_TO_HOST_16 (val)

MEM_VAL_LITTLE_TO_HOST_32 (val)

MEM_VAL_HOST_TO_LITTLE_16 (val)

MEM_VAL_HOST_TO_LITTLE_32 (val)

Arguments#

val

Data value to convert (see Notes #1 & #2).

Returned Value#

Converted data value (see Notes #1 & #2).

Notes / Warnings#

Convert data values to the desired data-word order :
'val' data value to convert & any variable to receive the returned conversion MUST start on appropriate CPU word-aligned addresses.
MEM_VAL_COPY_xxx() macro's are more efficient than generic endian word order macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
Generic endian word order macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_GET_INTxxU_xxx()#

Description#

Decode data values from any CPU memory address.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_GET_INT08U (addr)

    MEM_VAL_GET_INT16U (addr)

    MEM_VAL_GET_INT32U (addr)

    MEM_VAL_GET_INT64U (addr)

    MEM_VAL_GET_INT08U_BIG (addr)

    MEM_VAL_GET_INT16U_BIG (addr)

    MEM_VAL_GET_INT32U_BIG (addr)

    MEM_VAL_GET_INT64U_BIG (addr)

    MEM_VAL_GET_INT08U_LITTLE (addr)

    MEM_VAL_GET_INT16U_LITTLE (addr)

    MEM_VAL_GET_INT32U_LITTLE (addr)

    MEM_VAL_GET_INT64U_LITTLE (addr)

Arguments#

addr

Lowest CPU memory address of data value to decode (see Notes #2 & #3a).

Returned Value#

Decoded data value from CPU memory address (see Notes #1 & #3b).

Notes / Warnings#

Decode data values based on the values' data-word order in CPU memory :
CPU memory addresses/pointers NOT checked for NULL.
(a) MEM_VAL_GET_xxx() macro's decode data values without regard to CPU word-aligned addresses. Thus for processors that require data word alignment, data words can be decoded from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
(b) However, any variable to receive the returned data value MUST start on an appropriate CPU word-aligned address.
MEM_VAL_COPY_GET_xxx() macro's are more efficient than MEM_VAL_GET_xxx() macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
MEM_VAL_GET_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_SET_INTxxU_xxx()#

Description#

Encode data values to any CPU memory address.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_SET_INT08U (addr, val)

    MEM_VAL_SET_INT16U (addr, val)

    MEM_VAL_SET_INT32U (addr, val)

    MEM_VAL_SET_INT64U (addr, val)

    MEM_VAL_SET_INT08U_BIG (addr, val)

    MEM_VAL_SET_INT16U_BIG (addr, val)

    MEM_VAL_SET_INT32U_BIG (addr, val)

    MEM_VAL_SET_INT64U_BIG (addr, val)

    MEM_VAL_SET_INT08U_LITTLE (addr, val)

    MEM_VAL_SET_INT16U_LITTLE (addr, val)

    MEM_VAL_SET_INT32U_LITTLE (addr, val)

    MEM_VAL_SET_INT64U_LITTLE (addr, val)

Arguments#

addr

Lowest CPU memory address to encode data value (see Notes #2 & #3a).

val

Data value to encode (see Notes #1 & #3b).

Returned Value#

None.

Notes / Warnings#

Encode data values into CPU memory based on the values' data-word order :
CPU memory addresses/pointers NOT checked for NULL.
(a) MEM_VAL_SET_xxx() macro's encode data values without regard to CPU word-aligned addresses. Thus for processors that require data word alignment, data words can be encoded to any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
(b) However, 'val' data value to encode MUST start on an appropriate CPU word-aligned address.
MEM_VAL_COPY_SET_xxx() macro's are more efficient than MEM_VAL_SET_xxx() macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
MEM_VAL_SET_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_COPY_GET_INTxxU_xxx()#

Description#

Copy & decode data values from any CPU memory address to any CPU memory address.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_COPY_GET_INTxxU (addr_dest, addr_src)

    MEM_VAL_COPY_GET_INTxxU_BIG (addr_dest, addr_src)

    MEM_VAL_COPY_GET_INTxxU_LITTLE (addr_dest, addr_src)

Arguments#

addr_dest

Lowest CPU memory address to copy/decode source address's data value (see Notes #2 & #3).

addr_src

Lowest CPU memory address of data value to copy/decode (see Notes #2 & #3).

Returned Value#

None.

Notes / Warnings#

Copy/decode data values based on the values' data-word order :
(a) CPU memory addresses/pointers NOT checked for NULL.
(b) CPU memory addresses/buffers NOT checked for overlapping.
1. IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "copying ... between objects that overlap ... is undefined".
MEM_VAL_COPY_GET_xxx() macro's copy/decode data values without regard to CPU word-aligned addresses. Thus for processors that require data word alignment, data words can be copied/ decoded to/from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
MEM_VAL_COPY_GET_xxx() macro's are more efficient than MEM_VAL_GET_xxx() macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
Since octet-order copy/conversion are inverse operations, MEM_VAL_COPY_GET_xxx() & MEM_VAL_COPY_SET_xxx() macros are inverse, but identical, operations & are provided in both forms for semantics & consistency.
MEM_VAL_COPY_GET_xxx() macro's are NOT atomic operations & MUST NOT be used on any non- static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_COPY_GET_INTU_xxx()#

Description#

Copy & decode data values from any CPU memory address to any CPU memory address for any sized data values.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_COPY_GET_INTU (addr_dest, addr_src, val_size)

    MEM_VAL_COPY_GET_INTU_BIG (addr_dest, addr_src, val_size)

    MEM_VAL_COPY_GET_INTU_LITTLE (addr_dest, addr_src, val_size)

Arguments#

addr_dest

Lowest CPU memory address to copy/decode source address's data value (see Notes #2 & #3).

addr_src

Lowest CPU memory address of data value to copy/decode (see Notes #2 & #3).

val_size

Number of data value octets to copy/decode.

Returned Value#

None.

Notes / Warnings#

Copy/decode data values based on the values' data-word order :
(a) CPU memory addresses/pointers NOT checked for NULL.
(b) CPU memory addresses/buffers NOT checked for overlapping.
1. IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "copying ... between objects that overlap ... is undefined".
MEM_VAL_COPY_GET_INTU_xxx() macro's copy/decode data values without regard to CPU word- aligned addresses. Thus for processors that require data word alignment, data words can be copied/decoded to/from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
MEM_VAL_COPY_GET_xxx() macro's are more efficient than MEM_VAL_COPY_GET_INTU_xxx() macro's & SHOULD be used whenever possible.
Since octet-order copy/conversion are inverse operations, MEM_VAL_COPY_GET_INTU_xxx() & MEM_VAL_COPY_SET_INTU_xxx() macros are inverse, but identical, operations & are provided in both forms for semantics & consistency.
MEM_VAL_COPY_GET_INTU_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
MISRA-C 2004 Rule 5.2 states that "identifiers in an inner scope shall not use the same name as an identifier in an outer scope, and therefore hide that identifier".
The 'CPU_CFG_ENDIAN_TYPE' pre-processor 'else'-conditional code SHOULD never be compiled/ linked since each 'cpu.h' SHOULD ensure that the CPU data-word-memory order configuration constant (CPU_CFG_ENDIAN_TYPE) is configured with an appropriate data-word-memory order value (see 'cpu.h CPU WORD CONFIGURATION Note #2'). The 'else'-conditional code is included as an extra precaution in case 'cpu.h' is incorrectly configured.

MEM_VAL_COPY_SET_INTxxU_xxx()#

Description#

Copy & encode data values from any CPU memory address to any CPU memory address.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_COPY_SET_INTxxU (addr_dest, addr_src)

    MEM_VAL_COPY_SET_INTxxU_BIG (addr_dest, addr_src)

    MEM_VAL_COPY_SET_INTxxU_LITTLE (addr_dest, addr_src)

Arguments#

addr_dest

Lowest CPU memory address to copy/encode source address's data value (see Notes #2 & #3).

addr_src

Lowest CPU memory address of data value to copy/encode (see Notes #2 & #3).

Returned Value#

None.

Notes / Warnings#

Copy/encode data values based on the values' data-word order :
(a) CPU memory addresses/pointers NOT checked for NULL.
(b) CPU memory addresses/buffers NOT checked for overlapping.
1. IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "copying ... between objects that overlap ... is undefined".
MEM_VAL_COPY_SET_xxx() macro's copy/encode data values without regard to CPU word-aligned addresses. Thus for processors that require data word alignment, data words can be copied/ encoded to/from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
MEM_VAL_COPY_SET_xxx() macro's are more efficient than MEM_VAL_SET_xxx() macro's & are also independent of CPU data-word-alignment & SHOULD be used whenever possible.
Since octet-order copy/conversion are inverse operations, MEM_VAL_COPY_GET_xxx() & MEM_VAL_COPY_SET_xxx() macros are inverse, but identical, operations & are provided in both forms for semantics & consistency.
MEM_VAL_COPY_SET_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).

MEM_VAL_COPY_SET_INTU_xxx()#

Description#

Copy & encode data values from any CPU memory address to any CPU memory address for any sized data values.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_COPY_SET_INTU (addr_dest, addr_src, val_size)

    MEM_VAL_COPY_SET_INTU_BIG (addr_dest, addr_src, val_size)

    MEM_VAL_COPY_SET_INTU_LITTLE (addr_dest, addr_src, val_size)

Arguments#

addr_dest

Lowest CPU memory address to copy/encode source address's data value (see Notes #2 & #3).

addr_src

Lowest CPU memory address of data value to copy/encode (see Notes #2 & #3).

val_size

Number of data value octets to copy/encode.

Returned Value#

None.

Notes / Warnings#

Copy/encode data values based on the values' data-word order :
(a) CPU memory addresses/pointers NOT checked for NULL.
(b) CPU memory addresses/buffers NOT checked for overlapping.
1. IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "copying ... between objects that overlap ... is undefined".
MEM_VAL_COPY_SET_INTU_xxx() macro's copy/encode data values without regard to CPU word- aligned addresses. Thus for processors that require data word alignment, data words can be copied/encoded to/from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
MEM_VAL_COPY_SET_xxx() macro's are more efficient than MEM_VAL_COPY_SET_INTU_xxx() macro's & SHOULD be used whenever possible.
Since octet-order copy/conversion are inverse operations, MEM_VAL_COPY_GET_INTU_xxx() & MEM_VAL_COPY_SET_INTU_xxx() macros are inverse, but identical, operations & are provided in both forms for semantics & consistency.
MEM_VAL_COPY_SET_INTU_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).

MEM_VAL_COPY_xx()#

Description#

Copy data values from any CPU memory address to any CPU memory address.

Files#

lib_mem.h/lib_mem.c

Prototype#

    MEM_VAL_COPY_08 (addr_dest, addr_src)

    MEM_VAL_COPY_16 (addr_dest, addr_src)

    MEM_VAL_COPY_32 (addr_dest, addr_src)

    MEM_VAL_COPY (addr_dest, addr_src, val_size)

Arguments#

addr_dest

Lowest CPU memory address to copy source address's data value (see Notes #2 & #3).

addr_src

Lowest CPU memory address of data value to copy (see Notes #2 & #3).

val_size

Number of data value octets to copy. Present only for the MEM_VAL_COPY() macro.

Returned Value#

None.

Notes / Warnings#

MEM_VAL_COPY_xxx() macro's copy data values based on CPU's native data-word order.
(a) CPU memory addresses/pointers NOT checked for NULL.
(b) CPU memory addresses/buffers NOT checked for overlapping.
1. IEEE Std 1003.1, 2004 Edition, Section 'memcpy() : DESCRIPTION' states that "copying ... between objects that overlap ... is undefined".
MEM_VAL_COPY_xxx() macro's copy data values without regard to CPU word-aligned addresses. Thus for processors that require data word alignment, data words can be copied to/from any CPU address, word-aligned or not, without generating data-word-alignment exceptions/faults.
MEM_VAL_COPY_xxx() macro's are more efficient than MEM_VAL_COPY() macro & SHOULD be used whenever possible.
MEM_VAL_COPY_xxx() macro's are NOT atomic operations & MUST NOT be used on any non-static (i.e., volatile) variables, registers, hardware, etc.; without the caller of the macro's providing some form of additional protection (e.g., mutual exclusion).
MISRA-C 2004 Rule 5.2 states that "identifiers in an inner scope shall not use the same name as an identifier in an outer scope, and therefore hide that identifier".

API LIB String#

Str_Len()
Str_Len_N()
Str_Copy()
Str_Copy_N()
Str_Cat()
Str_Cat_N()
Str_Cmp()
Str_Cmp_N()
Str_CmpIgnoreCase()
Str_CmpIgnoreCase_N()
Str_Char()
Str_Char_N()
Str_Char_Last()
Str_Char_Last_N()
Str_Char_Replace()
Str_Char_Replace_N()
Str_Str()
Str_Str_N()
Str_Printf()
Str_FmtNbr_Int32U()
Str_FmtNbr_Int32S()
Str_FmtNbr_32()
Str_ParseNbr_Int32U()
Str_ParseNbr_Int32S()

Str_Len()#

Description#

Calculates the length of a string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_SIZE_T Str_Len (const CPU_CHAR  *p_str)

Arguments#

p_str

Pointer to the string (see Note #1).

Returned Value#

Length of a string; number of characters in a string before the terminating NULL character (see Note #2b1).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strlen() : DESCRIPTION' states that :
1. "The strlen() function shall compute the number of bytes in the string to which 's' ('p_str') points," ...
2. "not including the terminating null byte."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strlen() : RETURN VALUE' states that :
1. "The strlen() function shall return the length of 's' ('p_str');" ...
2. "no return value shall be reserved to indicate an error."
String length calculation terminates when :
(a) String pointer points to NULL.
1. String buffer overlaps with NULL address.
2. String length calculated for string up to but NOT beyond or including the NULL address.
(b) Terminating NULL character found.
1. String length calculated for string up to but NOT including the NULL character (see Note #2a2).

Str_Len_N()#

Description#

Calculates the length of a string, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_SIZE_T Str_Len_N (const CPU_CHAR   *p_str,
                             CPU_SIZE_T  len_max)

Arguments#

p_str

Pointer to the string (see Note #1).

len_max

Maximum number of characters to search (see Note #3c).

Returned Value#

Length of string; number of characters in string before terminating NULL character, if terminating NULL character found (see Note #2b1).

Requested maximum number of characters to search, if terminating NULL character NOT found (see Note #3c).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strlen() : DESCRIPTION' states that :
1. "The strlen() function shall compute the number of bytes in the string to which 's' ('p_str') points," ...
2. "not including the terminating null byte."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strlen() : RETURN VALUE' states that :
1. "The strlen() function shall return the length of 's' ('p_str');" ...
2. "no return value shall be reserved to indicate an error."
String length calculation terminates when :
(a) String pointer points to NULL.
1. String buffer overlaps with NULL address.
2. String length calculated for string up to but NOT beyond or including the NULL address.
(b) Terminating NULL character found.
1. String length calculated for string up to but NOT including the NULL character (see Note #2a2).
(c) 'len_max' number of characters searched.
1. 'len_max' number of characters does NOT include the terminating NULL character.

Str_Copy()#

Description#

Copies the source string to destination string buffer.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Copy (       CPU_CHAR  *p_str_dest,
                      const CPU_CHAR  *p_str_src)

Arguments#

p_str_dest

Pointer to the destination string buffer to receive source string copy (see Note #1a).

p_str_src

Pointer to the source string to copy into destination string buffer (see Note #1b).

Returned Value#

Pointer to the destination string, if NO error(s) [see Note #2b1].

Pointer to NULL, if any errors occur (see Note #2b2A).

Notes / Warnings#

(a) Destination buffer size is NOT validated; buffer overruns MUST be prevented by caller.
1. Destination buffer size MUST be large enough to accommodate the entire source string size including the terminating NULL character.
(b) Source buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strcpy() : DESCRIPTION' states that :
1. "The strcpy() function shall copy the string pointed to by 's2' ('p_str_src') ... into the array pointed to by 's1' ('p_str_dest')" ...
2. "(including the terminating null byte)."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strcpy() : RETURN VALUE' states that :
1. "The strcpy() function shall return 's1' ('p_str_dest');" ...
2. "no return value is reserved to indicate an error."
  (A) #### This requirement is intentionally NOT implemented in order to return NULL for any error(s).
(c) IEEE Std 1003.1, 2004 Edition, Section 'strcpy() : DESCRIPTION' states that "if copying takes place between objects that overlap, the behavior is undefined".
String copy terminates when :
(a) Destination/Source string pointer(s) are passed as NULL pointers.
1. No string copy performed; NULL pointer is returned.
(b) Destination/Source string pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) Source string's terminating NULL character found.
1. Entire source string copied into destination string buffer (see Note #2a).

Str_Copy_N()#

Description#

Copies the source string to the destination string buffer, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Copy_N (       CPU_CHAR   *p_str_dest,
                       const CPU_CHAR   *p_str_src,
                             CPU_SIZE_T  len_max)

Arguments#

p_str_dest

Pointer to the destination string buffer to receive the source string copy (see Note #1a).

p_str_src

Pointer to the source string to copy into the destination string buffer (see Note #1b).

len_max

Maximum number of characters to copy (see Notes #2a2 and #3d).

Returned Value#

Pointer to destination string, if NO error(s) [see Note #2b1].

Pointer to NULL, if any errors occur (see Note #2b2A).

Notes / Warnings#

(a) Destination buffer size is NOT validated; buffer overruns MUST be prevented by caller.
1. Destination buffer size MUST be large enough to accommodate the entire source string size including the terminating NULL character.
(b) Source string buffer NOT modified.
(a)
1. IEEE Std 1003.1, 2004 Edition, Section 'strncpy() : DESCRIPTION' states that :
  (A) "The strncpy() function shall copy ... the array pointed to by 's2' ('p_str_src') to the array pointed to by 's1' ('p_str_dest')";
  (B) but "not more than 'n' ('len_max') bytes"
  (C) & "(bytes that follow a null byte are not copied)".
2. (A) IEEE Std 1003.1, 2004 Edition, Section 'strncpy() : DESCRIPTION' adds that "if the array pointed to by 's2' ('p_str_src') is a string that is shorter than 'n' ('len_max') bytes, null bytes shall be appended to the copy in the array pointed to by 's1' ('p_str_dest'), until 'n' ('len_max') bytes in all are written."
  1. #### Since Str_Copy() limits the maximum number of characters to copy via Str_Copy_N() by the CPU's maximum number of addressable characters, this requirement is intentionally NOT implemented to avoid appending a potentially large number of unnecessary terminating NULL characters.
  (B) IEEE Std 1003.1, 2004 Edition, Section 'strncpy() : APPLICATION USAGE' also states that "if there is no null byte in the first 'n' ('len_max') bytes of the array pointed to by 's2' ('p_str_src'), the result is not null-terminated".
(b) IEEE Std 1003.1, 2004 Edition, Section 'strncpy() : RETURN VALUE' states that :
1. "The strncpy() function shall return 's1' ('p_str_dest');"
2. "no return value is reserved to indicate an error."
  (A) #### This requirement is intentionally ignored in order to return NULL for any error(s).
(c) IEEE Std 1003.1, 2004 Edition, Section 'strncpy() : DESCRIPTION' states that "if copying takes place between objects that overlap, the behavior is undefined".
String copy terminates when :
(a) Destination/Source string pointer(s) are passed as NULL pointers.
1. No string copy performed; NULL pointer is returned.
(b) Destination/Source string pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) Source string's terminating NULL character found.
1. Entire source string copied into destination string buffer (see Note #2a1A).
(d) 'len_max' number of characters copied.
1. 'len_max' number of characters MAY include the terminating NULL character (see Note #2a1C).
2. Null copies allowed (i.e. zero-length copies).
  (A) No string copy performed; destination string returned (see Note #2b1).

Str_Cat()#

Description#

Appends the concatenation string to the destination string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Cat (       CPU_CHAR  *p_str_dest,                     const CPU_CHAR  *p_str_cat)

Arguments#

p_str_dest

Pointer to the destination string to append concatenation string (see Note #1a).

p_str_cat

Pointer to the concatenation string to append to destination string (see Note #1b).

Returned Value#

Pointer to the destination string, if NO error(s) [see Note #2b1].

Pointer to NULL, if any errors occur (see Note #2b2A).

Notes / Warnings#

(a) Destination buffer size is NOT validated; buffer overruns MUST be prevented by caller.
1. Destination buffer size MUST be large enough to accommodate the entire concatenated string size including the terminating NULL character.
(b) Concatenation string buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strcat() : DESCRIPTION' states that :
1. "The strcat() function shall append a copy of the string pointed to by 's2' ('p_str_cat') ... to the end of the string pointed to by 's1' ('p_str_dest')."
2. (A) "The initial byte of 's2' ('p_str_cat') overwrites the null byte at the end of 's1' ('p_str_dest')."
  (B) A "terminating null byte" is appended at the end of the concatenated destination strings.
(b) IEEE Std 1003.1, 2004 Edition, Section 'strcat() : RETURN VALUE' states that :
1. "The strcat() function shall return 's1' ('p_str_dest');" ...
2. "no return value shall be reserved to indicate an error."
  (A) #### This requirement is intentionally NOT implemented in order to return NULL for any error(s).
(c) IEEE Std 1003.1, 2004 Edition, Section 'strcat() : DESCRIPTION' states that "if copying takes place between objects that overlap, the behavior is undefined."
String concatenation terminates when :
(a) Destination/Concatenation string pointer(s) are passed as NULL pointers.
1. No string concatenation performed; NULL pointer is returned.
(b) Destination/Concatenation string pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) Concatenation string's terminating NULL character found.
1. Entire concatenation string appended to destination string (see Note #2a1).

Str_Cat_N()#

Description#

Appends concatenation string to destination string, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Cat_N (       CPU_CHAR   *p_str_dest,
                      const CPU_CHAR   *p_str_cat,
                            CPU_SIZE_T  len_max)

Arguments#

p_str_dest

Pointer to the destination string to append concatenation string (see Note #1a).

p_str_cat

Pointer to the concatenation string to append to destination string (see Note #1b).

len_max

Maximum number of characters to concatenate (see Notes #2a1B and #3d).

Returned Value#

Pointer to the destination string, if NO error(s) [see Note #2b1].

Pointer to NULL, if any errors occur (see Note #2b2A).

Notes / Warnings#

(a) Destination buffer size is NOT validated; buffer overruns MUST be prevented by caller.
1. Destination buffer size MUST be large enough to accommodate the entire concatenated string size including the terminating NULL character.
(b) Concatenation string buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strncat() : DESCRIPTION' states that :
1. (A) "The strncat() function shall append ... the array pointed to by 's2' ('p_str_cat') to the end of the string pointed to by 's1' ('p_str_dest')" ...
  (B) but "not more than 'n' ('len_max') bytes".
2. (A) "The initial byte of 's2' ('p_str_cat') overwrites the null byte at the end of 's1' ('p_str_dest')."
  (B) "(a null byte and bytes that follow it are not appended)."
  (C) "A terminating null byte is always appended to the result."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strncat() : RETURN VALUE' states that :
1. "The strncat() function shall return 's1' ('p_str_dest');" ...
2. "no return value shall be reserved to indicate an error."
  (A) #### This requirement is intentionally NOT implemented in order to return NULL for any error(s).
(c) IEEE Std 1003.1, 2004 Edition, Section 'strncat() : DESCRIPTION' states that "if copying takes place between objects that overlap, the behavior is undefined."
String concatenation terminates when :
(a) Destination/Concatenation string pointer(s) are passed as NULL pointers.
1. No string concatenation performed; NULL pointer is returned.
(b) Destination/Concatenation string pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) Concatenation string's terminating NULL character found.
1. Entire concatenation string appended to destination string (see Note #2a1A).
(d) 'len_max' number of characters concatenated.
1. 'len_max' number of characters does NOT include the terminating NULL character (see Note #2a2).
2. Null concatenations allowed (i.e. zero-length concatenations).
  (A) No string concatenation performed; destination string returned (see Note #2b1).

Str_Cmp()#

Description#

Determines if two strings are identical.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT16S Str_Cmp (const CPU_CHAR  *p1_str,
                    const CPU_CHAR  *p2_str)

Arguments#

p1_str

Pointer to the first string (see Note #1).

p2_str

Pointer to the second string (see Note #1).

Returned Value#

0, if strings are identical (see Notes #3a1A, #3a2A, and #3b).

Negative value, if 'p1_str' is less than 'p2_str' (see Notes #3a1B1, #3a2B1, and #3c).

Positive value, if 'p1_str' is greater than 'p2_str' (see Notes #3a1B2, #3a2B2, and #3c).

See also Note #2b.

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strcmp() : DESCRIPTION' states that "the strcmp() function shall compare the string pointed to by 's1' ('p1_str') to the string pointed to by 's2' ('p2_str)".
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strcmp() : RETURN VALUE' states that "upon successful completion, strcmp() shall return an integer greater than, equal to, or less than 0".
2. IEEE Std 1003.1, 2004 Edition, Section 'strcmp() : DESCRIPTION' adds that "the sign of a non-zero return value shall be determined by the sign of the difference between the values of the first pair of bytes ... that differ in the strings being compared".
String comparison terminates when :
(a)
1. (A) BOTH string pointer(s) are passed as NULL pointers.
  1. NULL strings identical; 0 returned.
  (B)
  1. 'p1_str' passed a NULL pointer.
    (a) Return negative value of character pointed to by 'p2_str'.
  2. 'p2_str' passed a NULL pointer.
    (a) Return positive value of character pointed to by 'p1_str'.
2. (A) BOTH strings point to NULL.
  1. Strings overlap with NULL address.
  2. Strings identical up to but NOT beyond or including the NULL address; 0 returned.
  (B)
  1. 'p1_str_cmp_next' points to NULL.
    (a) 'p1_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return negative value of character pointed to by 'p2_str_cmp_next'.
  2. 'p2_str_cmp_next' points to NULL.
    (a) 'p2_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return positive value of character pointed to by 'p1_str_cmp_next'.
(b) Terminating NULL character found in both strings.
1. Strings identical; 0 returned.
2. Only one NULL character test required in conditional since the previous condition tested character equality.
(c) Non-matching characters found.
1. Return signed-integer difference of the character pointed to by 'p2_str' from the character pointed to by 'p1_str'.
Since 16-bit signed arithmetic is performed to calculate a non-identical comparison return value, 'CPU_CHAR' native data type size MUST be 8-bit.

Str_Cmp_N()#

Description#

Determines if two strings are identical for up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT16S Str_Cmp_N (const CPU_CHAR    *p1_str,
                      const CPU_CHAR    *p2_str,
                            CPU_SIZE_T   len_max)

Arguments#

p1_str

Pointer to the first string (see Note #1).

p2_str

Pointer to the second string (see Note #1).

len_max

Maximum number of characters to compare (see Note #3d).

Returned Value#

0, if strings are identical (see Notes #3a1A, #3a2A, #3b, and #3d).

Negative value, if 'p1_str' is less than 'p2_str' (see Notes #3a1B1, #3a2B1, and #3c).

Positive value, if 'p1_str' is greater than 'p2_str' (see Notes #3a1B2, #3a2B2, and #3c).

See also Note #2b.

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strncmp() : DESCRIPTION' states that :
1. "The strncmp() function shall compare ... the array pointed to by 's1' ('p1_str') to the array pointed to by 's2' ('p2_str)" ...
2. but "not more than 'n' ('len_max') bytes" of either array.
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strncmp() : RETURN VALUE' states that "upon successful completion, strncmp() shall return an integer greater than, equal to, or less than 0".
2. IEEE Std 1003.1, 2004 Edition, Section 'strncmp() : DESCRIPTION' adds that "the sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes ... that differ in the strings being compared".
3. String comparison terminates when :
  (a)
  1. (A) BOTH string pointer(s) are passed as NULL pointers.
    1. NULL strings identical; 0 returned.
    (B)
    1. 'p1_str' passed a NULL pointer.
      (a) Return negative value of character pointed to by 'p2_str'.
    2. 'p2_str' passed a NULL pointer.
      (a) Return positive value of character pointed to by 'p1_str'.
  2. (A) BOTH strings point to NULL.
    1. Strings overlap with NULL address.
    2. Strings identical up to but NOT beyond or including the NULL address; 0 returned.
    (B)
    1. 'p1_str_cmp_next' points to NULL.
      (a) 'p1_str' overlaps with NULL address.
      (b) Strings compared up to but NOT beyond or including the NULL address.
      (c) Return negative value of character pointed to by 'p2_str_cmp_next'.
    2. 'p2_str_cmp_next' points to NULL.
      (a) 'p2_str' overlaps with NULL address.
      (b) Strings compared up to but NOT beyond or including the NULL address.
      (c) Return positive value of character pointed to by 'p1_str_cmp_next'.
  (b) Terminating NULL character found in both strings.
  1. Strings identical; 0 returned.
  2. Only one NULL character test required in conditional since the previous condition tested character equality.
  (c) Non-matching characters found.
  1. Return signed-integer difference of the character pointed to by 'p2_str' from the character pointed to by 'p1_str'.
  (d)
  1. 'len_max' passed a zero length.
    (A) Zero-length strings identical; 0 returned.
  2. First 'len_max' number of characters identical.
    (A) Strings identical; 0 returned.
  See also Note #2a2.
Since 16-bit signed arithmetic is performed to calculate a non-identical comparison return value, 'CPU_CHAR' native data type size MUST be 8-bit.

Str_CmpIgnoreCase()#

Description#

Determines if two strings are identical, ignoring case.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT16S Str_CmpIgnoreCase (const CPU_CHAR   *p1_str,
                              const CPU_CHAR   *p2_str)

Arguments#

p1_str

Pointer to the first string (see Note #1).

p2_str

Pointer to the second string (see Note #1).

Returned Value#

0, if strings are identical (see Notes #3a1A, #3a2A, and #3b).

Negative value, if 'p1_str' is less than 'p2_str' (see Notes #3a1B1, #3a2B1, and #3c).

Positive value, if 'p1_str' is greater than 'p2_str' (see Notes #3a1B2, #3a2B2, and #3c).

See also Note #2b.

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strcasecmp() : DESCRIPTION' states that :
1. (A) "The strcasecmp() function shall compare ... the string pointed to by 's1' ('p1_str') to the string pointed to by 's2' ('p2_str')" ...
  (B) "ignoring differences in case".
2. "strcasecmp() ... shall behave as if the strings had been converted to lowercase and then a byte comparison performed."
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strcasecmp() : RETURN VALUE' states that "upon successful completion, strcasecmp() shall return an integer greater than, equal to, or less than 0".
2. IEEE Std 1003.1, 2004 Edition, Section 'strcmp() : DESCRIPTION' adds that "the sign of a non-zero return value shall be determined by the sign of the difference between the values of the first pair of bytes ... that differ in the strings being compared".
String comparison terminates when :
(a)
1. (A) BOTH string pointer(s) are passed as NULL pointers.
  1. NULL strings identical; 0 returned.
  (B)
  1. 'p1_str' passed a NULL pointer.
    (a) Return negative value of character pointed to by 'p2_str', converted to lower case (see Note #2a2).
  2. 'p2_str' passed a NULL pointer.
    (a) Return positive value of character pointed to by 'p1_str', converted to lower case (see Note #2a2).
2. (A) BOTH strings point to NULL.
  1. Strings overlap with NULL address.
  2. Strings identical up to but NOT beyond or including the NULL address; 0 returned.
  (B)
  1. 'p1_str_cmp_next' points to NULL.
    (a) 'p1_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return negative value of character pointed to by 'p2_str_cmp_next', converted to lower case (see Note #2a2).
  2. 'p2_str_cmp_next' points to NULL.
    (a) 'p2_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return positive value of character pointed to by 'p1_str_cmp_next', converted to lower case (see Note #2a2).
(b) Terminating NULL character found in both strings.
1. Strings identical; 0 returned.
2. Only one NULL character test required in conditional since the previous condition tested character equality.
(c) Non-matching characters found.
1. Return signed-integer difference of the character pointed to by 'p2_str', converted to lower case, from the character pointed to by 'p1_str', converted to lower case.
Since 16-bit signed arithmetic is performed to calculate a non-identical comparison return value, 'CPU_CHAR' native data type size MUST be 8-bit.

Str_CmpIgnoreCase_N()#

Description#

Determines if two strings are identical for up to a maximum number of characters, ignoring case.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT16S Str_CmpIgnoreCase_N (const CPU_CHAR    *p1_str,
                                const CPU_CHAR    *p2_str,
                                      CPU_SIZE_T   len_max)

Arguments#

p1_str

Pointer to the first string (see Note #1).

p2_str

Pointer to the second string (see Note #1).

len_max

Maximum number of characters to compare (see Note #3d).

Returned Value#

0, if strings are identical (see Notes #3a1A, #3a2A, #3b, and #3d).

Negative value, if 'p1_str' is less than 'p2_str' (see Notes #3a1B1, #3a2B1, and #3c).

Positive value, if 'p1_str' is greater than 'p2_str' (see Notes #3a1B2, #3a2B2, and #3c).

See also Note #2b.

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strncasecmp() : DESCRIPTION' states that :
1. (A) "The strncasecmp() function shall compare ... the string pointed to by 's1' ('p1_str') to the string pointed to by 's2' ('p2_str')" ...
  (B) "ignoring differences in case" ...
  (C) but "not more than 'n' ('len_max') bytes" of either string.
2. "strncasecmp() shall behave as if the strings had been converted to lowercase and then a byte comparison performed."
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strncasecmp() : RETURN VALUE' states that "upon successful completion, strncasecmp() shall return an integer greater than, equal to, or less than 0".
2. IEEE Std 1003.1, 2004 Edition, Section 'strcmp() : DESCRIPTION' adds that "the sign of a non-zero return value shall be determined by the sign of the difference between the values of the first pair of bytes ... that differ in the strings being compared".
String comparison terminates when :
(a)
1. (A) BOTH string pointer(s) are passed as NULL pointers.
  1. NULL strings identical; 0 returned.
  (B)
  1. 'p1_str' passed a NULL pointer.
    (a) Return negative value of character pointed to by 'p2_str', converted to lower case (see Note #2a2).
  2. 'p2_str' passed a NULL pointer.
    (a) Return positive value of character pointed to by 'p1_str', converted to lower case (see Note #2a2).
2. (A) BOTH strings point to NULL.
  1. Strings overlap with NULL address.
  2. Strings identical up to but NOT beyond or including the NULL address; 0 returned.
  (B)
  1. 'p1_str_cmp_next' points to NULL.
    (a) 'p1_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return negative value of character pointed to by 'p2_str_cmp_next', converted to lower case (see Note #2a2).
  2. 'p2_str_cmp_next' points to NULL.
    (a) 'p2_str' overlaps with NULL address.
    (b) Strings compared up to but NOT beyond or including the NULL address.
    (c) Return positive value of character pointed to by 'p1_str_cmp_next', converted to lower case (see Note #2a2).
(b) Terminating NULL character found in both strings.
1. Strings identical; 0 returned.
2. Only one NULL character test required in conditional since the previous condition tested character equality.
(c) Non-matching characters found.
1. Return signed-integer difference of the character pointed to by 'p2_str', converted to lower case, from the character pointed to by 'p1_str', converted to lower case.
(d) See also Note #2a1C.
1. 'len_max' passed a zero length.
  (A) Zero-length strings identical; 0 returned.
2. First 'len_max' number of characters identical.
  (A) Strings identical; 0 returned.
Since 16-bit signed arithmetic is performed to calculate a non-identical comparison return value, 'CPU_CHAR' native data type size MUST be 8-bit.

Str_Char()#

Description#

Searches the string for first occurrence of specific character.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char (const CPU_CHAR   *p_str,
                          CPU_CHAR    srch_char)

Arguments#

p_str

Pointer to the string (see Note #1).

srch_char

Search character.

Returned Value#

Pointer to the first occurrence of search character in string, if any occur (see Note #2b1).

Pointer to NULL, if no search character is found (see Note #2b2).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strchr() : DESCRIPTION' states that :
1. "The strchr() function shall locate the first occurrence of 'c' ('srch_char') ... in the string pointed to by 's' ('p_str')."
2. "The terminating null byte is considered to be part of the string."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strchr() : RETURN VALUE' states that "upon completion, strchr() shall return" :
1. "a pointer to the byte," ...
2. "or a null pointer if the byte was not found."
  (A) #### Although NO strchr() specification states to return NULL for any other reason
  (s), NULL is also returned for any error(s).
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String's terminating NULL character found.
1. Search character NOT found in search string; NULL pointer is returned (see Note #2b2).
2. Applicable even if search character is the terminating NULL character (see Note #2a2).
(d) Search character found.
1. Return pointer to first occurrence of search character in search string (see Note #2a1).

Str_Char_N()#

Description#

Searches the string for first occurrence of specific character, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char_N (const CPU_CHAR    *p_str,
                            CPU_SIZE_T   len_max,
                            CPU_CHAR     srch_char)

Arguments#

p_str

Pointer to the string (see Note #1).

len_max

Maximum number of characters to search (see Notes #2c and #3e).

srch_char

Search character.

Returned Value#

Pointer to the first occurrence of search character in string, if any occur (see Note #2b1).

Pointer to the NULL, if no search character is found (see Note #2b2).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strchr() : DESCRIPTION' states that :
1. "The strchr() function shall locate the first occurrence of 'c' ('srch_char') ... in the string pointed to by 's' ('p_str')."
2. "The terminating null byte is considered to be part of the string."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strchr() : RETURN VALUE' states that "upon completion, strchr() shall return" :
1. "a pointer to the byte," ...
2. "or a null pointer if the byte was not found."
  (A) #### Although NO strchr() specification states to return NULL for any other reason(s), NULL is also returned for any error(s).
(c) Ideally, the 'len_max' argument would be the last argument in this function's argument list for consistency with all other custom string library functions. However, the 'len_max' argument is sequentially ordered as the second argument to comply with most standard library's strnchr() argument list.
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String's terminating NULL character found.
1. Search character NOT found in search string; NULL pointer is returned (see Note #2b2).
2. Applicable even if search character is the terminating NULL character (see Note #2a2).
(d) Search character found.
1. Return pointer to first occurrence of search character in search string (see Note #2a1).
(e) 'len_max' number of characters searched.
1. Search character NOT found in search string within first 'len_max' number of characters; NULL pointer is returned.
2. 'len_max' number of characters MAY include terminating NULL character (see Note #2a2).

Str_Char_Last()#

Description#

Searches the string for last occurrence of specific character.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char_Last (const CPU_CHAR   *p_str,
                               CPU_CHAR    srch_char)

Arguments#

p_str

Pointer to the string (see Note #1).

srch_char

Search character.

Returned Value#

Pointer to the last occurrence of search character in string, if any occur (see Note #2b1).

Pointer to NULL, if no search character is found (see Note #2b2).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strrchr() : DESCRIPTION' states that :
1. "The strrchr() function shall locate the last occurrence of 'c' ('srch_char') ... in the string pointed to by 's' ('p_str')."
2. "The terminating null byte is considered to be part of the string."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strrchr() : RETURN VALUE' states that "upon successful completion, strrchr() shall return" :
1. "a pointer to the byte"
2. "or a null pointer if 'c' ('srch_char') does not occur in the string."
  (A) #### Although NO strrchr() specification states to return NULL for any other reason(s), NULL is also returned for any error(s).
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String searched from end to beginning.
1. Search character NOT found in search string; NULL pointer is returned.
2. Applicable even if search character is the terminating NULL character (see Note #2a2).
(d) Search character found.
1. Return pointer to last occurrence of search character in search string (see Note #2a1).

Str_Char_Last_N()#

Description#

Searches the string for last occurrence of specific character, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char_Last_N (const CPU_CHAR    *p_str,
                                 CPU_SIZE_T   len_max,
                                 CPU_CHAR     srch_char)

Arguments#

p_str

Pointer to the string (see Note #1).

len_max

Maximum number of characters to search (see Notes #2c and #3e).

srch_char

Search character.

Returned Value#

Pointer to the last occurrence of search character in string, if any occur (see Note #2b1).

Pointer to NULL, if no search character is found (see Note #2b2).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strrchr() : DESCRIPTION' states that :
1. "The strrchr() function shall locate the last occurrence of 'c' ('srch_char') ... in the string pointed to by 's' ('p_str')."
2. "The terminating null byte is considered to be part of the string."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strrchr() : RETURN VALUE' states that "upon successful completion, strrchr() shall return" :
1. "a pointer to the byte"
2. "or a null pointer if 'c' ('srch_char') does not occur in the string."
  (A) #### Although NO strrchr() specification states to return NULL for any other reason(s), NULL is also returned for any error(s).
(c) Ideally, the 'len_max' argument would be the last argument in this function's argument list for consistency with all other custom string library functions. However, the 'len_max' argument is sequentially ordered as the second argument to comply with most standard library's strnrchr() argument list.
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String searched from end to beginning.
1. Search character NOT found in search string; NULL pointer is returned (see Note #2b2).
2. Applicable even if search character is the terminating NULL character (see Note #2a2).
(d) Search character found.
1. Return pointer to last occurrence of search character in search string (see Note #2a1).
(e) 'len_max' number of characters searched.
1. Search character NOT found in search string within last 'len_max' number of characters; NULL pointer is returned.
2. 'len_max' number of characters MAY include terminating NULL character (see Note #2a2).

Str_Char_Replace()#

Description#

Searches the string for specific character and replace it by another specific character.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char_Replace (CPU_CHAR   *p_str,
                            CPU_CHAR    char_srch,
                            CPU_CHAR    char_replace)

Arguments#

p_str

Pointer to the string (see Note #1).

char_srch

Search character.

char_replace

Replace character.

Returned Value#

Pointer to the string, if NO error(s).

Pointer to NULL, if any errors occur.

Notes / Warnings#

String buffer modified.
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String's terminating NULL character found.
1. Search character NOT found in search string; NULL pointer is returned
2. Applicable even if search character is the terminating NULL character
(d) Search character found.
1. Replace character found by the specified character.

Str_Char_Replace_N()#

Description#

Searches the string for specific character and replace it by another specific character, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Char_Replace_N (CPU_CHAR    *p_str,
                              CPU_CHAR     char_srch,
                              CPU_CHAR     char_replace,
                              CPU_SIZE_T   len_max)

Arguments#

p_str

Pointer to the string (see Note #1).

char_srch

Search character.

char_replace

Replace character.

len_max

Maximum number of characters to search (see Notes #2c and #3e).

Returned Value#

Pointer to the string, if NO error(s).

Pointer to NULL, if any errors occur.

Notes / Warnings#

String buffer modified.
String search terminates when :
(a) String pointer passed a NULL pointer.
1. No string search performed; NULL pointer is returned.
(b) String pointer points to NULL.
1. String overlaps with NULL address; NULL pointer is returned.
(c) String's terminating NULL character found.
1. Search character NOT found in search string; NULL pointer is returned
2. Applicable even if search character is the terminating NULL character
(d) Search character found.
1. Replace character found by the specified character.
(e) 'len_max' number of characters searched.
1. Search character NOT found in search string within first 'len_max' number of characters; NULL pointer is returned.
2. 'len_max' number of characters MAY include terminating NULL character (see Note #2a2).

Str_Str()#

Description#

Searches the string for the first occurrence of a specific search string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Str (const CPU_CHAR   *p_str,
                   const CPU_CHAR   *p_str_srch)

Arguments#

p_str

Pointer to string (see Note #1).

p_str_srch

Pointer to the search string (see Note #1).

Returned Value#

Pointer to the first occurrence of a search string in the string, if any occur (see Note #2b1A).
Pointer to the string, if search string has a zero length (see Note #2b2).
Pointer to NULL, if no search character is found (see Note #2b1B).

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strstr() : DESCRIPTION' states that :
1. "The strstr() function shall locate the first occurrence in the string pointed to by 's1' ('p_str') of the sequence of bytes ... in the string pointed to by 's2' ('p_str_srch')"
2. "(excluding the terminating null byte)."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strstr() : RETURN VALUE' states that :
1. "Upon successful completion, strstr() shall return" :
  (A) "a pointer to the located string"
  (B) "or a null pointer if the string is not found."
  1. #### Although NO strstr() specification states to return NULL for any other reason(s), NULL is also returned for any error(s).
2. "If 's2' ('p_str_srch') points to a string with zero length, the function shall return 's1' ('p_str')."
String search terminates when :
(a) String pointer(s) are passed as NULL pointers.
1. No string search performed; NULL pointer is returned.
(b) String pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) for the first occurrence length equal to zero.
1. No string search performed; string pointer returned (see Note #2b2).
(d) Search string length greater than string length.
1. No string search performed; NULL pointer returned (see Note #2b1B).
(e) Entire string has been searched.
1. Search string not found; NULL pointer is returned (see Note #2b1B).
(f) Search string found.
1. Return pointer to first occurrence of search string in string (see Note #2b1A).

Str_Str_N()#

Description#

Searches the string for the first occurrence of a specific search string, up to a maximum number of characters.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_Str_N (const CPU_CHAR    *p_str,
                     const CPU_CHAR    *p_str_srch,
                           CPU_SIZE_T   len_max)

Arguments#

p_str

Pointer to the string (see Note #1).

p_str_srch

Pointer to the search string (see Note #1).

len_max

Maximum number of characters to search (see Note #3g).

Returned Value#

Pointer to the first occurrence of search string in string, if any occur (see Note #2b1A).

Pointer to the string, if NULL search string (see Note #2b2).

Pointer to NULL, otherwise (see Note #2b1B).

Notes / Warnings#

String buffers are NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strstr() : DESCRIPTION' states that :
1. "The strstr() function shall locate the first occurrence in the string pointed to by 's1' ('p_str') of the sequence of bytes ... in the string pointed to by 's2' ('p_str_srch')"
2. "(excluding the terminating null byte)."
(b) IEEE Std 1003.1, 2004 Edition, Section 'strstr() : RETURN VALUE' states that :
1. "Upon successful completion, strstr() shall return" :
  (A) "a pointer to the located string"
  (B) "or a null pointer if the string is not found."
  1. #### Although NO strstr() specification states to return NULL for any other reason(s), NULL is also returned for any error(s).
2. "If 's2' ('p_str_srch') points to a string with zero length, the function shall return 's1' ('p_str')."
String search terminates when :
(a) String pointer(s) are passed as NULL pointers.
1. No string search performed; NULL pointer is returned.
(b) String pointer(s) point to NULL.
1. String buffer(s) overlap with NULL address; NULL pointer is returned.
(c) Search string length equal to zero.
1. No string search performed; string pointer returned (see Note #2b2).
(d) Search string length greater than string length.
1. No string search performed; NULL pointer returned (see Note #2b1B).
(e) Entire string has been searched.
1. Search string not found; NULL pointer is returned (see Note #2b1B).
2. Maximum size of the search is defined as the subtraction of the search string length from the string length.
(f) Search string found.
1. Return pointer to first occurrence of search string in string (see Note #2b1A).
2. Search string found via Str_Cmp_N().
(g) 'len_max' number of characters searched.
1. 'len_max' number of characters does NOT include terminating NULL character (see Note #2a2).

Str_Printf()#

Description#

Lightweight printf() implementation.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_SIZE_T Str_Printf (STR_PRINTF_OUT_CB   out_cb,
                       void               *p_out_cb_arg,
                       CPU_CHAR           *p_fmt,
                                           ...)

Arguments#

out_cb

Output callback (putchar-like with an extra callback-specific argument).

p_out_cb_arg

Character output callback argument.

p_fmt

Pointer to the format string.

...

Variable number of arguments that will be formatted according to the format specifiers in the format string.

Returned Value#

None.

Notes / Warnings#

None.

Str_FmtNbr_Int32U()#

Description#

Formats a 32-bit unsigned integer into a multi-digit character string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_FmtNbr_Int32U (CPU_INT32U    nbr,
                             CPU_INT08U    nbr_dig,
                             CPU_INT08U    nbr_base,
                             CPU_CHAR      lead_char,
                             CPU_BOOLEAN   lower_case,
                             CPU_BOOLEAN   nul,
                             CPU_CHAR     *p_str)

Arguments#

nbr

Number to format.

nbr_dig

Number of digits to format (see Note #1).

The following may be used to specify the number of digits to format :

DEF_INT_32U_NBR_DIG_MIN Minimum number of 32-bit unsigned digits
DEF_INT_32U_NBR_DIG_MAX Maximum number of 32-bit unsigned digits

nbr_base

Base of number to format (see Note #2).

The following may be used to specify the number base :

DEF_NBR_BASE_BIN Base 2
DEF_NBR_BASE_OCT Base 8
DEF_NBR_BASE_DEC Base 10
DEF_NBR_BASE_HEX Base 16

lead_char

Prepend leading character (see Note #3) :

'\0' Do NOT prepend leading character to a string.
Printable character Prepend leading character to a string.
Unprintable character Format invalid string (see Note #6).

lower_case

Format alphabetic characters (if any) in lower case :

DEF_NO Format alphabetic characters in upper case.
DEF_YES Format alphabetic characters in lower case.

nul

Append terminating NULL-character (see Note #4) :

DEF_NO Do NOT append terminating NULL-character to a string.
DEF_YES Append terminating NULL-character to a string.

p_str

Pointer to the character array to return formatted number string (see Note #5).

Returned Value#

Pointer to the formatted string, if NO error(s).
Pointer to NULL, if any errors occur.

Notes / Warnings#

(a) If the number of digits to format ('nbr_dig') is zero; then NO formatting is performed except possible NULL-termination of the string (see Note #4).
Example :
```
      nbr = 23456
      nbr_dig = 0
      nbr_base = 10

      p_str = ""
```
See Note #6a
(b) If the number of digits to format ('nbr_dig') is less than the number of significant integer digits of the number to format ('nbr'); then an invalid string is formatted instead of truncating any significant integer digits.
Example :
```
      nbr = 23456
      nbr_dig = 3
      nbr_base = 10

      p_str = "???"
```
See Note #6b
The number's base MUST be between 2 and 36, inclusive.
Leading character option prepends leading characters prior to the first non-zero digit.
(a)
1. Leading character MUST be a printable ASCII character.
2. (A) Leading character MUST NOT be a number base digit,
  (B) with the exception of '0'.
(b) The number of leading characters is such that the total number of significant integer digits plus the number of leading characters is equal to the requested number of integer digits to format ('nbr_dig').
Example :
```
   nbr = 23456
   nbr_dig = 7
   nbr_base = 10
   lead_char = ' '

   p_str = " 23456"
```
(c)
1. If the value of the number to format is zero
2. & the number of digits to format is non-zero,
3. but NO leading character available;
4. then one digit of '0' value is formatted.
  This is NOT a leading character; but a single integer digit of '0' value.
(a) NULL-character terminate option DISABLED prevents overwriting previous character array formatting.
(b) WARNING: Unless 'p_str' character array is pre-/post-terminated, NULL-character terminate option DISABLED will cause character string run-on.
(a) Format buffer size is NOT validated; buffer overruns MUST be prevented by caller.
(b) To prevent character buffer overrun :
For any unsuccessful string format or error(s), an invalid string of question marks ('?') will be formatted, where the number of question marks is determined by the number of digits to format ('nbr_dig') :
```
Invalid string's { (a) 0 (NULL string) , if 'nbr_dig' = 0
   number of = {
question marks { (b) 'nbr_dig' , if 'nbr_dig' > 0
```

Str_FmtNbr_Int32S()#

Description#

Formats a 32-bit signed integer into a multi-digit character string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_CHAR *Str_FmtNbr_Int32S (CPU_INT32S    nbr,
                             CPU_INT08U    nbr_dig,
                             CPU_INT08U    nbr_base,
                             CPU_CHAR      lead_char,
                             CPU_BOOLEAN   lower_case,
                             CPU_BOOLEAN   nul,
                             CPU_CHAR     *p_str)

Arguments#

nbr

Number to format.

nbr_dig

Number of digits to format (see Note #1).

The following may be used to specify the number of digits to format :

DEF_INT_32S_NBR_DIG_MIN + 1 Minimum number of 32-bit signed digits
DEF_INT_32S_NBR_DIG_MAX + 1 Maximum number of 32-bit signed digits

(plus 1 digit for possible negative sign)

nbr_base

Base of number to format (see Note #2).

The following may be used to specify the number base :

DEF_NBR_BASE_BIN Base 2
DEF_NBR_BASE_OCT Base 8
DEF_NBR_BASE_DEC Base 10
DEF_NBR_BASE_HEX Base 16

lead_char

Prepend leading character (see Note #3) :

'\0' Do NOT prepend leading character to a string. Printable character Prepend leading character to a string. Unprintable character Format invalid string (see Note #6).

lower_case

Format alphabetic characters (if any) in lower case :

DEF_NO Format alphabetic characters in upper case.
DEF_YES Format alphabetic characters in lower case.

nul

Append terminating NULL-character (see Note #4) :

DEF_NO Do NOT append terminating NULL-character to a string.
DEF_YES Append terminating NULL-character to a string.

p_str

Pointer to the character array to return formatted number string (see Note #5).

Returned Value#

Pointer to the formatted string, if NO error(s).
Pointer to NULL, if any errors occur.

Notes / Warnings#

(a) If the number of digits to format ('nbr_dig') is zero; then NO formatting is performed except possible NULL-termination of the string (see Note #4).
Example :
```
nbr = -23456
nbr_dig = 0
nbr_base = 10
p_str = ""
```
See Note #6a
(b) If the number of digits to format ('nbr_dig') is less than the number of significant integer digits of the number to format ('nbr'); then an invalid string is formatted instead of truncating any significant integer digits.
Example :
```
nbr = 23456
nbr_dig = 3
nbr_base = 10
p_str = "???"
```
See Note #6b
(c) If the number to format ('nbr') is negative but the number of digits to format ('nbr_dig') is equal to the number of significant integer digits of the number to format ('nbr'); then an invalid string is formatted instead of truncating the negative sign.
Example :
```
nbr = -23456
nbr_dig = 5
nbr_base = 10
p_str = "?????"
```
See Note #6b
The number's base MUST be between 2 and 36, inclusive.
Leading character option prepends leading characters prior to the first non-zero digit.
(a)
1. Leading character MUST be a printable ASCII character.
2. (A) Leading character MUST NOT be a number base digit,
  (B) with the exception of '0'.
(b)
1. The number of leading characters is such that the total number of significant integer digits plus the number of leading characters plus possible negative sign character is equal to the requested number of integer digits to format ('nbr_dig').
  Examples :
```
nbr = 23456
nbr_dig = 7
nbr_base = 10
lead_char = ' '
p_str = " 23456"
nbr = -23456
nbr_dig = 7
nbr_base = 10
lead_char = ' '
p_str = " -23456"
```
2. (A) If the number to format ('nbr') is negative AND the leading character ('lead_char') is a '0' digit; then the negative sign character prefixes all leading characters prior to the formatted number.
  Examples :
```
nbr = -23456
nbr_dig = 8
nbr_base = 10
lead_char = '0'
p_str = "-0023456"
nbr = -43981
nbr_dig = 8
nbr_base = 16
lead_char = '0'
lower_case = DEF_NO
p_str = "-000ABCD"
```
  (B) If the number to format ('nbr') is negative AND the leading character ('lead_char') is NOT a '0' digit; then the negative sign character immediately prefixes the most significant digit of the formatted number.
  Examples :
```
nbr = -23456
nbr_dig = 8
nbr_base = 10
lead_char = '#'
p_str = "##-23456"
nbr = -43981
nbr_dig = 8
nbr_base = 16
lead_char = '#'
lower_case = DEF_YES
p_str = "###-abcd"
```
(c)
1. If the value of the number to format is zero
2. & the number of digits to format is non-zero,
3. but NO leading character available;
4. then one digit of '0' value is formatted.
(a) NULL-character terminate option DISABLED prevents overwriting previous character array formatting.
(b) WARNING: Unless 'p_str' character array is pre-/post-terminated, NULL-character terminate option DISABLED will cause character string run-on.
(a) Format buffer size is NOT validated; buffer overruns MUST be prevented by caller.
(b) To prevent character buffer overrun :
Character array size MUST be >= ('nbr_dig' + 1 negative sign + 1 'NUL' terminator) characters
For any unsuccessful string format or error(s), an invalid string of question marks ('?') will be formatted, where the number of question marks is determined by the number of digits to format ('nbr_dig') :
```
Invalid string's { (a) 0 (NULL string) ,   if 'nbr_dig' = 0
   number of   = {
question marks   { (b) 'nbr_dig'       ,   if 'nbr_dig' > 0
```

Str_FmtNbr_32()#

Description#

Formats a number into a multi-digit character string.

Files#

lib_str.h/lib_str.c

Prototype#

#if (LIB_STR_CFG_FP_EN == DEF_ENABLED)
CPU_CHAR  *Str_FmtNbr_32 (CPU_FP32      nbr,
                          CPU_INT08U    nbr_dig,
                          CPU_INT08U    nbr_dp,
                          CPU_CHAR      lead_char,
                          CPU_BOOLEAN   nul,
                          CPU_CHAR     *p_str)

Arguments#

nbr

Number to format (see Note #1).

nbr_dig

Number of decimal digits to format (see Note #2).

nbr_dp

Number of decimal point digits to format.

lead_char

Prepend leading character (see Note #3) :

'\0' : Do NOT prepend leading character to a string.
Printable character : Prepend leading character to a string.
Unprintable character : Format invalid string (see Note #6d).

nul

Append terminating NULL-character (see Note #4) :

DEF_NO Do NOT append terminating NULL-character to a string.
DEF_YES Append terminating NULL-character to a string.

p_str

Pointer to the character array to return formatted number string (see Note #5).

Returned Value#

Pointer to the formatted string, if NO error(s) [see Note #6c].

Pointer to NULL, if any errors occur.

Notes / Warnings#

(a) The maximum accuracy for 32-bit floating-point numbers :

Maximum Accuracy                log [Internal-Base ^ (Number-Internal-Base-Digits)]
32-bit Floating-point Number = -----------------------------------------------------
                                                log [External-Base]
                              log [2 ^ 24]
                           = --------------
                               log [10]

                           < 7.225 Base-10 Digits
where
         Internal-Base                 Internal number base of floating-
                                             point numbers (i.e. 2)
         External-Base                 External number base of floating-
                                             point numbers (i.e. 10)
         Number-Internal-Base-Digits   Number of internal number base
                                             significant digits (i.e. 24)

(b) Some CPUs' &/or compilers' floating-point implementations MAY further reduce the maximum accuracy.

(a) If the total number of digits to format ('nbr_dig + nbr_dp') is zero; then NO formatting is performed except possible NULL-termination of the string (see Note #4).
Example :
```
nbr = -23456.789
nbr_dig = 0
nbr_dp = 0
p_str = ""
```
See Note #7a
(b)
1. If the number of digits to format ('nbr_dig') is less than the number of significant integer digits of the number to format ('nbr'); then an invalid string is formatted instead of truncating any significant integer digits.
  Example :
```
nbr = 23456.789
nbr_dig = 3
nbr_dp = 2
p_str = "??????"
```
  See Note #7d
2. If the number to format ('nbr') is negative but the number of digits to format ('nbr_dig') is equal to the number of significant integer digits of the number to format ('nbr'); then an invalid string is formatted instead of truncating the negative sign.
  Example :
```
nbr = -23456.789
nbr_dig = 5
nbr_dp = 2
p_str = "????????"
```
  See Note #7d
3. If the number to format ('nbr') is negative but the number of significant integer digits is zero, and the number of digits to format ('nbr_dig') is one but the number of decimal point digits to format ('nbr_dp') is zero; then an invalid string is formatted instead of truncating the negative sign.
  Example :
```
nbr = -0.7895
nbr_dig = 1
nbr_dp = 0
p_str = "?"
```
  See Note #7d
4. (A) If the number to format ('nbr') is negative but the number of significant integer digits is zero, and the number of digits to format ('nbr_dig') is zero but the number of decimal point digits to format ('nbr_dp') is non- zero; then the negative sign immediately prefixes the decimal point -- with NO decimal digits formatted, NOT even a single decimal digit of '0'.
  Example :
```
nbr = -0.7895
nbr_dig = 0
nbr_dp = 2
p_str = "-.78"
```
  (B) If the number to format ('nbr') is positive but the number of significant integer digits is zero, and the number of digits to format ('nbr_dig') is zero but the number of decimal point digits to format ('nbr_dp') is non- zero; then a single decimal digit of '0' prefixes the decimal point.
  This '0' digit is used whenever a negative sign is not formatted (see Note #2b4A) so that the formatted string's decimal point is not floating, but fixed in the string as the second character.
  Example :
```
nbr = 0.7895
nbr_dig = 0
nbr_dp = 2

p_str = "0.78"
```
(c)
1. If the total number of digits to format ('nbr_dig + nbr_dp') is greater than :
  (A) the maximum accuracy of the CPU's &/or compiler's 32-bit floating-point numbers, digits following all significantly-accurate digits of the number to format ('nbr') will be inaccurate; ...
  (B) the configured maximum accuracy ('LIB_STR_CFG_FP_MAX_NBR_DIG_SIG'), all digits or decimal places following all significantly-accurate digits of the number to format ('nbr') will be replaced & formatted with zeros ('0').
2. Therefore, one or more least-significant digit(s) of the number to format ('nbr') MAY be rounded & not necessarily truncated due to the inaccuracy of the CPU's &/or compiler's floating-point implementation.
Leading character option prepends leading characters prior to the first non-zero digit.
(a)
1. Leading character MUST be a printable ASCII character.
2. (A) Leading character MUST NOT be a base-10 digit,
  (B) with the exception of '0'.
(b)
1. The number of leading characters is such that the total number of significant integer digits plus the number of leading characters plus possible negative sign character is equal to the requested number of integer digits to format ('nbr_dig').
  Examples :
```
nbr = 23456.789
nbr_dig = 7
nbr_dp = 2
lead_char = ' '

p_str = " 23456.78"

nbr = -23456.789
nbr_dig = 7
nbr_dp = 2
lead_char = ' '

p_str = " -23456.78"
```
2. (A) If the number to format ('nbr') is negative AND the leading character ('lead_char') is a '0' digit; then the negative sign character prefixes all leading characters prior to the formatted number.
  Example :
```
nbr = -23456.789
nbr_dig = 8
nbr_dp = 2
lead_char = '0'


p_str = "-0023456.78"
```
  (B) If the number to format ('nbr') is negative AND the leading character ('lead_char') is NOT a '0' digit; then the negative sign character immediately prefixes the most significant digit of the formatted number.
  Examples :
```
nbr = -23456.789
nbr_dig = 8
nbr_dp = 2
lead_char = '#'

p_str = "##-23456.78"
```
(c)
1. If the integer value of the number to format is zero and
2. the number of digits to format is greater than one
3. OR the number is NOT negative,
4. but NO leading character available;
5. then one digit of '0' value is formatted.
  This is NOT a leading character; but a single integer digit of '0' value.
See also Note #2b4B.
(a) NULL-character terminate option DISABLED prevents overwriting previous character array formatting.
(b) WARNING: Unless 'p_str' character array is pre-/post-terminated, NULL-character terminate option DISABLED will cause character string run-on.
(a) Format buffer size is NOT validated; buffer overruns MUST be prevented by caller.
(b) To prevent character buffer overrun :
Character array size MUST be \>= ('nbr_dig' + 'nbr_dp' + 1 negative sign + 1 decimal point + 1 'NUL' terminator) characters
String format terminates when :
(a) Format string pointer is passed a NULL pointer.
1. No string formatted; NULL pointer is returned.
(b) Total number of digits to format ('nbr_dig + nbr_dp') is zero.
1. NULL string formatted (see Note #7a); NULL pointer is returned.
(c) Number of digits to format ('nbr_dig') is less than number of significant integer digits of the number to format ('nbr'), including possible negative sign.
1. Invalid string formatted (see Note #7); NULL pointer is returned.
(d) Lead character is NOT a valid, printable character (see Note #3a).
1. Invalid string formatted (see Note #7); NULL pointer is returned.
(e) Number successfully formatted into character string array.
For any unsuccessful string format or error(s), an invalid string of question marks ('?') will be formatted, where the number of question marks is determined by the number of digits ('nbr_dig') & number of decimal point digits ('nbr_dp') to format :

                     { (a) 0 (NULL string)             , if 'nbr_dig' = 0 AND
                     {                                      'nbr_dp'  = 0
                     {
                     { (b) 'nbr_dig'                   , if 'nbr_dig' > 0 AND
                     {                                      'nbr_dp'  = 0
Invalid string's     {
   number of =       { (c) ['nbr_dp'               +   , if 'nbr_dig' = 0 AND
  question marks     {       1 (for decimal point) +        'nbr_dp'  > 0
                     {       1 (for negative sign) ]
                     {
                     { (d) ['nbr_dig'              +   , if 'nbr_dig' > 0 AND
                     {      'nbr_dp'               +        'nbr_dp'  > 0
                     {       1 (for decimal point) ]

Str_ParseNbr_Int32U()#

Description#

Parses a 32-bit unsigned integer from a string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT32U Str_ParseNbr_Int32U (const CPU_CHAR   *p_str,
                                      CPU_CHAR   *p_str_next,
                                      CPU_INT08U  nbr_base)

Arguments#

p_str

Pointer to the string (see Notes #1 and #2a).

p_str_next

Optional pointer to a variable to :

(a) Return a pointer to first character following the integer string, if NO error(s) [see Note #2a2B2];

(b) Return a pointer to 'p_str', if any errors occur (see Note #2a2A2).

nbr_base

Base of number to parse (see Notes #2a1B1 and #2a2B1).

Returned Value#

Parsed integer, if integer parsed with NO overflow (see Note #2a3A).
DEF_INT_32U_MAX_VAL, if integer parsed but overflowed (see Note #2a3A1).
0, otherwise (see Note #2a3B).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : DESCRIPTION' states that "these functions shall convert the initial portion of the string pointed to by 'str' ('p_str') to a type unsigned long ... representation" :
1. "First, they decompose the input string into three parts" :
  (A) "An initial, possibly empty, sequence of white-space characters [as specified by isspace()]."
  1. "The subject sequence is defined as the longest initial subsequence of the input string, starting with the first non-white-space character that is of the expected form. The subject sequence shall contain no characters if the input string is empty or consists entirely of white-space characters."
  (B)
  1. "A subject sequence interpreted as an integer represented in some radix determined by the value of 'base' ('nbr_base')" :
    (a) "If the value of 'base' ('nbr_base') is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, or hexadecimal constant" :
    1. "A decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits."
    2. "An octal constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to '7' only."
    3. "A hexadecimal constant consists of the prefix '0x' or '0X' followed by a sequence of the decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively."
    (b) "If the value of 'base' ('nbr_base') is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by 'base' ('nbr_base')" :
    1. (A) "The letters from 'a' (or 'A') to 'z' (or 'Z') inclusive are ascribed the values 10 to 35"; ...
      (B) "only letters whose ascribed values are less than that of base are permitted."
    2. (A) "If the value of 'base' ('nbr_base') is 16, the characters '0x' or '0X' may optionally precede the sequence of letters and digits."
      (B) Although NO specification states that "if the value of 'base' ('nbr_base') is" 8, the '0' character "may optionally precede the sequence of letters and digits"; it seems reasonable to allow the '0' character to be optionally parsed.
  2. "A subject sequence .... may be preceded by a '+' or '-' sign."
    (a) However, it does NOT seem reasonable to parse & convert a negative number integer string into an unsigned integer.
  (C)
  1. (a) "A final string of one or more unrecognized characters," ...
    (b) "including the terminating null byte of the input string" ...
  2. "other than a sign or a permissible letter or digit."
2. Second, "they shall attempt to convert the subject sequence to an unsigned integer" :
  (A) "If the subject sequence is empty or does not have the expected form" :
  1. "no conversion [is] performed"; ...
  2. "the value of 'str' ('p_str') [is] stored in the object pointed to by 'endptr' ('p_str_next'), provided that 'endptr' ('p_str_next') is not a null pointer."
  (B) "If the subject sequence has the expected form" :
  1. (a) "and the value of 'base' ('nbr_base') is 0, the sequence of characters starting with the first digit shall be interpreted as an integer constant."
    (b) "and the value of 'base' ('nbr_base') is between 2 and 36, it shall be used as the base for conversion, ascribing to each letter its value as given above" (see Note #2a1B1b1A).
  2. "A pointer to the final string shall be stored in the object pointed to by 'endptr' ('p_str_next'), provided that 'endptr' ('p_str_next') is not a null pointer."
3. Lastly, IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : RETURN VALUE' states that :
  (A) "Upon successful completion, these functions shall return the converted value."
  1. "If the correct value is outside the range of representable values, {ULONG_MAX} ... shall be returned."
  (B) "If no conversion could be performed, 0 shall be returned."
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : ERRORS' states that "these functions shall fail if" :
  (A) "[EINVAL] - The value of 'base' ('nbr_base') is not supported."
  (B) "[ERANGE] - The value to be returned is not representable."
2. IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : ERRORS' states that "these functions may fail if" :
  (A) "[EINVAL] - No conversion could be performed."

Return integer value and next string pointer should be used to diagnose parse success or failure :

(a) Valid parse string integer :

   p_str = " ABCDE xyz"
   nbr_base = 16

   nbr = 703710
   p_str_next = " xyz"

(b) Invalid parse string integer :

   p_str = " ABCDE"
   nbr_base = 10

   nbr = 0
   p_str_next = p_str = " ABCDE"

   p_str = " 0xGABCDE"
   nbr_base = 16

   nbr = 0
   p_str_next = "xGABCDE"

(d) Valid decimal parse string integer ('0x' prefix ignored following invalid hexadecimal characters) :

   p_str = " 0xGABCDE"
   nbr_base = 0

   nbr = 0
   p_str_next = "xGABCDE"

(e) Valid decimal parse string integer ('0' prefix ignored following invalid octal characters) :

   p_str = " 0GABCDE"
   nbr_base = 0

   nbr = 0
   p_str_next = "GABCDE"

(f) Parse string integer overflow :

   p_str = " 12345678901234567890*123456"
   nbr_base = 10

   nbr = DEF_INT_32U_MAX_VAL
   p_str_next = "*123456"

(g) Invalid negative unsigned parse string :

   p_str = " -12345678901234567890*123456"
   nbr_base = 10

   nbr = 0
   p_str_next = p_str = " -12345678901234567890*123456"

Str_ParseNbr_Int32S()#

Description#

Parses a 32-bit signed integer from a string.

Files#

lib_str.h/lib_str.c

Prototype#

CPU_INT32S Str_ParseNbr_Int32S (const CPU_CHAR   *p_str,
                                      CPU_CHAR   *p_str_next,
                                      CPU_INT08U  nbr_base)

Arguments#

p_str

Pointer to the string (see Notes #1 and #2a).

p_str_next

Optional pointer to a variable to ... :

(a) Return a pointer to first character following the integer string, if NO error(s) [see Note #2a2B2];

(b) Return a pointer to 'p_str', otherwise (see Note #2a2A2).

nbr_base

Base of number to parse (see Notes #2a1B1 and #2a2B1).

Returned Value#

Parsed integer, if integer parsed with NO over- or underflow (see Note #2a3A).

DEF_INT_32S_MIN_VAL, if integer parsed but negatively underflowed (see Note #2a3A1a).
DEF_INT_32U_MAX_VAL, if integer parsed but positively overflowed (see Note #2a3A1b).

0, otherwise (see Note #2a3B).

Notes / Warnings#

String buffer NOT modified.
(a) IEEE Std 1003.1, 2004 Edition, Section 'strtol() : DESCRIPTION' states that "these functions shall convert the initial portion of the string pointed to by 'str' ('p_str') to a type long ... representation" :
1. "First, they decompose the input string into three parts" :
  (A) "An initial, possibly empty, sequence of white-space characters [as specified by ][as specified by `isspace()`]."
  1. "The subject sequence is defined as the longest initial subsequence of the input string, starting with the first non-white-space character that is of the expected form. The subject sequence shall contain no characters if the input string is empty or consists entirely of white-space characters."
  (B)
  1. "A subject sequence interpreted as an integer represented in some radix determined by the value of 'base' ('nbr_base')" :
    (a) "If the value of 'base' ('nbr_base') is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, or hexadecimal constant" :
    1. "A decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits."
    2. "An octal constant consists of the prefix '0' optionally followed by a sequence of the digits '0' to '7' only."
    3. "A hexadecimal constant consists of the prefix '0x' or '0X' followed by a sequence of the decimal digits and letters 'a' (or 'A') to 'f' (or 'F') with values 10 to 15 respectively."
    (b) "If the value of 'base' ('nbr_base') is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by 'base' ('nbr_base')" :
    1. (A) "The letters from 'a' (or 'A') to 'z' (or 'Z') inclusive are ascribed the values 10 to 35"; ...
      (B) "only letters whose ascribed values are less than that of base are permitted."
    2. (A) "If the value of 'base' ('nbr_base') is 16, the characters '0x' or '0X' may optionally precede the sequence of letters and digits."
      (B) Although NO specification states that "if the value of 'base' ('nbr_base') is" 8, the '0' character "may optionally precede the sequence of letters and digits"; it seems reasonable to allow the '0' character to be optionally parsed.
  2. "A subject sequence .... may be preceded by a '+' or '-' sign."
    (a) However, it does NOT seem reasonable to parse & convert a negative number integer string into an unsigned integer.
  (C)
  1. (a) "A final string of one or more unrecognized characters," ...
    (b) "including the terminating null byte of the input string" ...
  2. "other than a sign or a permissible letter or digit."
2. Second, "they shall attempt to convert the subject sequence to an integer" :
  (A) "If the subject sequence is empty or does not have the expected form" :
  1. "no conversion is performed"; ...
  2. "the value of 'str' ('p_str') is stored in the object pointed to by 'endptr' ('p_str_next'), provided that 'endptr' ('p_str_next') is not a null pointer."
  (B) "If the subject sequence has the expected form" :
  1. (a) "and the value of 'base' ('nbr_base') is 0, the sequence of characters starting with the first digit shall be interpreted as an integer constant."
    (b) "and the value of 'base' ('nbr_base') is between 2 and 36, it shall be used as the base for conversion, ascribing to each letter its value as given above" (see Note #2a1B1b1A).
  2. "A pointer to the final string shall be stored in the object pointed to by 'endptr' ('p_str_next'), provided that 'endptr' ('p_str_next') is not a null pointer."
3. Lastly, IEEE Std 1003.1, 2004 Edition, Section 'strtol() : RETURN VALUE' states that :
  (A) "Upon successful completion, these functions shall return the converted value."
  1. "If the correct value is outside the range of representable values", either of the following "shall be returned" :
    (a) "{LONG_MIN}" or ...
    (b) "{LONG_MAX}"
  (B) "If no conversion could be performed, 0 shall be returned."
(b)
1. IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : ERRORS' states that "these functions shall fail if" :
  (A) "[EINVAL] - The value of 'base' ('nbr_base') is not supported."
  (B) "[ERANGE] - The value to be returned is not representable."
2. IEEE Std 1003.1, 2004 Edition, Section 'strtoul() : ERRORS' states that "these functions may fail if" :
  (A) "[EINVAL] - No conversion could be performed."

Return integer value and next string pointer should be used to diagnose parse success or failure :

(a) Valid parse string integer :

   p_str = " ABCDE xyz"
   nbr_base = 16

   nbr = 703710
   p_str_next = " xyz"

(b) Invalid parse string integer :

   p_str = " ABCDE"
   nbr_base = 10

   nbr = 0
   p_str_next = p_str = " ABCDE"

   p_str = " 0xGABCDE"
   nbr_base = 16

   nbr = 0
   p_str_next = "xGABCDE"

(d) Valid decimal parse string integer ('0x' prefix ignored following invalid hexadecimal characters) :

   p_str = " 0xGABCDE"
   nbr_base = 0

   nbr = 0
   p_str_next = "xGABCDE"

(e) Valid decimal parse string integer ('0' prefix ignored following invalid octal characters) :

   p_str = " 0GABCDE"
   nbr_base = 0

   nbr = 0
   p_str_next = "GABCDE"

(f) Parse string integer overflow :

   p_str = " 12345678901234567890\*123456"
   nbr_base = 10

   nbr = DEF_INT_32S_MAX_VAL
   p_str_next = "\*123456"

(g) Parse string integer underflow :

   p_str = " -12345678901234567890\*123456"
   nbr_base = 10

   nbr = DEF_INT_32S_MIN_VAL
   p_str_next = "\*123456"

API LIB Utilities#

DEF_BIT()
DEF_BITxx()
DEF_BIT_MASK()
DEF_BIT_MASK_xx()
DEF_BIT_FIELD()
DEF_BIT_FIELD_xx()
DEF_BIT_SET()
DEF_BIT_SET_xx() (deprecated)
DEF_BIT_CLR()
DEF_BIT_CLR_xx() (deprecated)
DEF_BIT_TOGGLE()
DEF_BIT_FIELD_RD()
DEF_BIT_FIELD_ENC()
DEF_BIT_FIELD_WR()
DEF_BIT_IS_SET()
DEF_BIT_IS_CLR()
DEF_BIT_IS_SET_ANY()
DEF_BIT_IS_CLR_ANY()
DEF_GET_U_MAX_VAL()
CONTAINER_OF()

DEF_BIT()#

Description#

Create bit mask with single, specified bit set.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT (bit)

Arguments#

bit

Bit number of bit to set.

Returned Value#

Bit mask with single, specified bit set.

Notes / Warnings#

'bit' SHOULD be a non-negative integer.
(a) 'bit' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.

DEF_BITxx()#

Description#

Create bit mask of specified bit size with single, specified bit set.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT08 (bit)

    DEF_BIT16 (bit)

    DEF_BIT32 (bit)

    DEF_BIT64 (bit)

Arguments#

bit

Bit number of bit to set.

Returned Value#

Bit mask with single, specified bit set.

Notes / Warnings#

'bit' SHOULD be a non-negative integer.
(a) 'bit' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.
(b) To avoid overflowing any target CPU &/or compiler's integer data type, unsigned bit constant '1' is cast to specified integer data type size.
Ideally, DEF_BITxx() macro's should be named DEF_BIT_xx(); however, these names already previously-released for bit constant #define's (see 'STANDARD DEFIN BIT DEFINES').

DEF_BIT_MASK()#

Description#

Shift a bit mask.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_MASK (bit_mask, bit_shift)

Arguments#

bit_mask

Bit mask to shift.

bit_shift

Number of bit positions to left-shift bit mask.

Returned Value#

Shifted bit mask.

Notes / Warnings#

(a) 'bit_mask' SHOULD be an unsigned integer.
(b) 'bit_shift' SHOULD be a non-negative integer.
'bit_shift' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.

DEF_BIT_MASK_xx()#

Description#

Shift a bit mask of specified bit size.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_MASK_08 (bit_mask, bit_shift)

    DEF_BIT_MASK_16 (bit_mask, bit_shift)

    DEF_BIT_MASK_32 (bit_mask, bit_shift)

    DEF_BIT_MASK_64 (bit_mask, bit_shift)

Arguments#

bit_mask

Bit mask to shift.

bit_shift

Number of bit positions to left-shift bit mask.

Returned Value#

Shifted bit mask.

Notes / Warnings#

(a) 'bit_mask' SHOULD be an unsigned integer.
(b) 'bit_shift' SHOULD be a non-negative integer.
'bit_shift' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.

DEF_BIT_FIELD()#

Description#

Create & shift a contiguous bit field.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_FIELD (bit_field, bit_shift)

Arguments#

bit_field

Number of contiguous bits to set in the bit field.

bit_shift

Number of bit positions to left-shift bit field.

Returned Value#

Shifted bit field.

Notes / Warnings#

'bit_field' & 'bit_shift' SHOULD be non-negative integers.
(a) 'bit_field'/'bit_shift' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.
(b) To avoid overflowing any target CPU &/or compiler's integer data type, unsigned bit constant '1' is suffixed with 'L'ong integer modifier.

DEF_BIT_FIELD_xx()#

Description#

Create & shift a contiguous bit field of specified bit size.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_FIELD_08 (bit_field, bit_shift)

    DEF_BIT_FIELD_16 (bit_field, bit_shift)

    DEF_BIT_FIELD_32 (bit_field, bit_shift)

    DEF_BIT_FIELD_64 (bit_field, bit_shift)

Arguments#

bit_field

Number of contiguous bits to set in the bit field.

bit_shift

Number of bit positions to left-shift bit field.

Returned Value#

Shifted bit field.

Notes / Warnings#

'bit_field' & 'bit_shift' SHOULD be non-negative integers.
(a) 'bit_field'/'bit_shift' values that overflow the target CPU &/or compiler environment (e.g., negative or greater-than-CPU-data-size values) MAY generate compiler warnings &/or errors.
(b) To avoid overflowing any target CPU &/or compiler's integer data type, unsigned bit constant '1' is cast to specified integer data type size.

DEF_BIT_SET()#

Description#

Set specified bit(s) in a value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_SET (val, mask)

Arguments#

val

Value to modify by setting specified bit(s).

mask

Mask of bits to set.

Returned Value#

Modified value with specified bit(s) set.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.

DEF_BIT_SET_xx() (deprecated)#

Description#

Set specified bit(s) in a value of specified bit size.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_SET_08 (val, mask)

    DEF_BIT_SET_16 (val, mask)

    DEF_BIT_SET_32 (val, mask)

    DEF_BIT_SET_64 (val, mask)

Arguments#

val

Value to modify by setting specified bit(s).

mask

Mask of bits to set.

Returned Value#

Modified value with specified bit(s) set.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
These macros are deprecated and should be replaced by the DEF_BIT_SET macro.

DEF_BIT_CLR()#

Description#

Clear specified bit(s) in a value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_CLR (val, mask)

Arguments#

val

Value to modify by clearing specified bit(s).

mask

Mask of bits to clear.

Returned Value#

Modified value with specified bit(s) clear.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.

DEF_BIT_CLR_xx() (deprecated)#

Description#

Clear specified bit(s) in a value of specified bit size.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_CLR_08 (val, mask)
    DEF_BIT_CLR_16 (val, mask)
    DEF_BIT_CLR_32 (val, mask)
    DEF_BIT_CLR_64 (val, mask)

Arguments#

val

Value to modify by clearing specified bit(s).

mask

Mask of bits to clear.

Returned Value#

Modified value with specified bit(s) clear.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
These macros are deprecated and should be replaced by the DEF_BIT_CLR macro.

DEF_BIT_TOGGLE()#

Description#

Toggles specified bit(s) in a value.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_TOGGLE (val, mask)

Arguments#

val

Value to modify by toggling specified bit(s).

mask

Mask of bits to toggle.

Returned Value#

Modified value with specified bit(s) toggled.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.

DEF_BIT_FIELD_RD()#

Description#

Reads a 'val' field, masked and shifted, given by mask 'field_mask'.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_FIELD_RD (val, field_mask)

Arguments#

val

Value to read from.

field_mask

Mask of field to read. See note #1, #2 and #3.

Returned Value#

Field value, masked and right-shifted to bit position 0.

Notes / Warnings#

'field_mask' argument must NOT be 0.
'field_mask' argument must contain a mask with contiguous set bits.
'val' & 'field_mask' SHOULD be unsigned integers.

DEF_BIT_FIELD_ENC()#

Description#

Encodes given 'field_val' at position given by mask 'field_mask'.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_FIELD_ENC (field_val, field_mask)

Arguments#

field_val

Value to encode.

field_mask

Mask of field to read. See note #1 and #2.

Returned Value#

Field value, masked and left-shifted to field position.

Notes / Warnings#

'field_mask' argument must contain a mask with contiguous set bits.
'field_val' & 'field_mask' SHOULD be unsigned integers.

DEF_BIT_FIELD_WR()#

Description#

Writes 'field_val' field at position given by mask 'field_mask' in variable 'var'.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_FIELD_WR (var, field_val, field_mask)

Arguments#

var

Variable to write field to. See note #2.

field_val

Desired value for field. See note #2.

field_mask

Mask of field to write to. See note #1 and #2.

Returned Value#

None.

Notes / Warnings#

'field_mask' argument must contain a mask with contiguous set bits.
'var', 'field_val' & 'field_mask' SHOULD be unsigned integers.

DEF_BIT_IS_SET()#

Description#

Determine if specified bit(s) in a value are set.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_IS_SET (val, mask)

Arguments#

val

Value to check for specified bit(s) set.

mask

Mask of bits to check if set (see Note #2).

Returned Value#

DEF_YES, if ALL specified bit(s) are set in value.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
NULL 'mask' allowed; returns 'DEF_NO' since NO mask bits specified.

DEF_BIT_IS_CLR()#

Description#

Determine if specified bit(s) in a value are clear.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_IS_CLR (val, mask)

Arguments#

val

Value to check for specified bit(s) clear.

mask

Mask of bits to check if clear (see Note #2).

Returned Value#

DEF_YES, if ALL specified bit(s) are clear in value.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
NULL 'mask' allowed; returns 'DEF_NO' since NO mask bits specified.

DEF_BIT_IS_SET_ANY()#

Description#

Determine if any specified bit(s) in a value are set.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_IS_SET_ANY (val, mask)

Arguments#

val

Value to check for specified bit(s) set.

mask

Mask of bits to check if set (see Note #2).

Returned Value#

DEF_YES, if ANY specified bit(s) are set in value.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
NULL 'mask' allowed; returns 'DEF_NO' since NO mask bits specified.

DEF_BIT_IS_CLR_ANY()#

Description#

Determine if any specified bit(s) in a value are clear.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_BIT_IS_CLR_ANY (val, mask)

Arguments#

val

Value to check for specified bit(s) clear.

mask

Mask of bits to check if clear (see Note #2).

Returned Value#

DEF_YES, if ANY specified bit(s) are clear in value.

Notes / Warnings#

'val' & 'mask' SHOULD be unsigned integers.
NULL 'mask' allowed; returns 'DEF_NO' since NO mask bits specified.

DEF_GET_U_MAX_VAL()#

Description#

Get the maximum unsigned value that can be represented in an unsigned integer variable of the same data type size as an object.

Files#

lib_mem.h/lib_mem.c

Prototype#

    DEF_GET_U_MAX_VAL (obj)

Arguments#

obj

Object or data type to return maximum unsigned value (see Note #1).

Returned Value#

Maximum unsigned integer value that can be represented by the object, if NO error(s).

Notes / Warnings#

'obj' SHOULD be an integer object or data type but COULD also be a character or pointer object or data type.

CONTAINER_OF()#

Description#

Find pointer to structure type 'parent_type', containing 'p_member'.

Files#

lib_utils.h

Prototype#

    CONTAINER_OF(p_member, parent_type, member)

Arguments#

p_member

Pointer to member of structure of which the pointer to container structure is found.

parent_type

Name of the parent structure data type.

member

Name of the member field, in the parent structure data type.

Returned Value#

Pointer to structure containing 'p_member'.

Notes / Warnings#

'p_member' SHOULD NOT be DEF_NULL.