String formatting (fmt)

Provides simple string formatting functions. More...

Detailed Description

Provides simple string formatting functions.

The goal of this API is to provide a string formatting interface which has a reduced code size footprint compared to the libc provided stdio.h functionality.

This library provides a set of formatting and printing functions for 64 bit integers, even when the C library was built without support for 64 bit formatting (newlib-nano).

Note
The print functions in this library do not buffer any output. Mixing calls to standard printf from stdio.h with the print_xxx functions in fmt, especially on the same output line, may cause garbled output.

Modules

 Table extension of the string formatting API (fmt_table)
 Provides utilities to print tables.
 

Files

file  fmt.h
 String formatting API.
 

Macros

#define FMT_USE_MEMMOVE   (1)
 use memmove() or internal implementation
 

Functions

static int fmt_is_digit (char c)
 Test if the given character is a numerical digit (regex [0-9]) More...
 
static int fmt_is_upper (char c)
 Test if the given character is an uppercase letter (regex [A-Z]) More...
 
int fmt_is_number (const char *str)
 Test if the given string is a number (regex [0-9]+) More...
 
size_t fmt_byte_hex (char *out, uint8_t byte)
 Format a byte value as hex. More...
 
size_t fmt_bytes_hex (char *out, const uint8_t *ptr, size_t n)
 Formats a sequence of bytes as hex bytes. More...
 
size_t fmt_bytes_hex_reverse (char *out, const uint8_t *ptr, size_t n)
 Formats a sequence of bytes as hex bytes, starting with the last byte. More...
 
uint8_t fmt_hex_byte (const char *hex)
 Converts a sequence of two hex characters to a byte. More...
 
size_t fmt_hex_bytes (uint8_t *out, const char *hex)
 Converts a sequence of hex bytes to an array of bytes. More...
 
size_t fmt_u16_hex (char *out, uint16_t val)
 Convert a uint16 value to hex string. More...
 
size_t fmt_u32_hex (char *out, uint32_t val)
 Convert a uint32 value to hex string. More...
 
size_t fmt_u64_hex (char *out, uint64_t val)
 Convert a uint64 value to hex string. More...
 
size_t fmt_u32_dec (char *out, uint32_t val)
 Convert a uint32 value to decimal string. More...
 
size_t fmt_u64_dec (char *out, uint64_t val)
 Convert a uint64 value to decimal string. More...
 
size_t fmt_u16_dec (char *out, uint16_t val)
 Convert a uint16 value to decimal string. More...
 
size_t fmt_s64_dec (char *out, int64_t val)
 Convert a int64 value to decimal string. More...
 
size_t fmt_s32_dec (char *out, int32_t val)
 Convert a int32 value to decimal string. More...
 
size_t fmt_s16_dec (char *out, int16_t val)
 Convert a int16 value to decimal string. More...
 
size_t fmt_s16_dfp (char *out, int16_t val, int fp_digits)
 Convert 16-bit fixed point number to a decimal string. More...
 
size_t fmt_s32_dfp (char *out, int32_t val, int fp_digits)
 Convert 32-bit fixed point number to a decimal string. More...
 
size_t fmt_float (char *out, float f, unsigned precision)
 Format float to string. More...
 
size_t fmt_char (char *out, char c)
 Copy in char to string (without terminating '\0') More...
 
size_t fmt_strlen (const char *str)
 Count characters until '\0' (exclusive) in str. More...
 
size_t fmt_strnlen (const char *str, size_t maxlen)
 Count at most maxlen characters until '\0' (exclusive) in str. More...
 
size_t fmt_str (char *out, const char *str)
 Copy null-terminated string (excluding terminating \0) More...
 
size_t fmt_to_lower (char *out, const char *str)
 Copy null-terminated string to a lowercase string (excluding terminating \0) More...
 
uint32_t scn_u32_dec (const char *str, size_t n)
 Convert digits to uint32. More...
 
uint32_t scn_u32_hex (const char *str, size_t n)
 Convert hexadecimal characters to uin32_t. More...
 
void print (const char *s, size_t n)
 Print string to stdout. More...
 
void print_u32_dec (uint32_t val)
 Print uint32 value to stdout. More...
 
void print_s32_dec (int32_t val)
 Print int32 value to stdout. More...
 
void print_byte_hex (uint8_t byte)
 Print byte value as hex to stdout. More...
 
void print_u32_hex (uint32_t val)
 Print uint32 value as hex to stdout. More...
 
void print_u64_hex (uint64_t val)
 Print uint64 value as hex to stdout. More...
 
void print_u64_dec (uint64_t val)
 Print uint64 value as decimal to stdout. More...
 
void print_float (float f, unsigned precision)
 Print float value. More...
 
void print_str (const char *str)
 Print null-terminated string to stdout. More...
 
size_t fmt_lpad (char *str, size_t in_len, size_t pad_len, char pad_char)
 Pad string to the left. More...
 

Function Documentation

◆ fmt_byte_hex()

size_t fmt_byte_hex ( char *  out,
uint8_t  byte 
)

Format a byte value as hex.

E.g., converts byte value 0 to the string 00, 255 to the string FF.

Will write two bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]byteByte value to convert
Returns
2

◆ fmt_bytes_hex()

size_t fmt_bytes_hex ( char *  out,
const uint8_t *  ptr,
size_t  n 
)

Formats a sequence of bytes as hex bytes.

Will write 2*n bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]ptrPointer to bytes to convert
[in]nNumber of bytes to convert
Returns
2*n

◆ fmt_bytes_hex_reverse()

size_t fmt_bytes_hex_reverse ( char *  out,
const uint8_t *  ptr,
size_t  n 
)

Formats a sequence of bytes as hex bytes, starting with the last byte.

Will write 2*n bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]ptrPointer to bytes to convert
[in]nNumber of bytes to convert
Returns
2*n

◆ fmt_char()

size_t fmt_char ( char *  out,
char  c 
)

Copy in char to string (without terminating '\0')

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outstring to write to (or NULL)
[in]cchar value to append
Returns
nr of bytes the function did or would write to out

◆ fmt_float()

size_t fmt_float ( char *  out,
float  f,
unsigned  precision 
)

Format float to string.

Converts float value f to string

If out is NULL, will only return the number of bytes that would have been written.

Attention
This function is using floating point math. It pulls in about 2.4k bytes of code on ARM Cortex-M platforms.
Precondition
-2^32 < f < 2^32
precision < 8 (TENMAP_SIZE)
Parameters
[out]outstring to write to (or NULL)
[in]ffloat value to convert
[in]precisionnumber of digits after decimal point
Returns
nr of bytes the function did or would write to out

◆ fmt_hex_byte()

uint8_t fmt_hex_byte ( const char *  hex)

Converts a sequence of two hex characters to a byte.

The hex characters sequence must contain valid hexadecimal characters otherwise the result is undefined.

Parameters
[in]hexPointer to input buffer
Returns
byte based on hex string

◆ fmt_hex_bytes()

size_t fmt_hex_bytes ( uint8_t *  out,
const char *  hex 
)

Converts a sequence of hex bytes to an array of bytes.

The sequence of hex characters must have an even length: 2 hex character => 1 byte. If the sequence of hex has an odd length, this function returns 0 and an empty out.

The hex characters sequence must contain valid hexadecimal characters otherwise the result in out is undefined.

Parameters
[out]outPointer to converted bytes, or NULL
[in]hexPointer to input buffer
Returns
strlen(hex) / 2 when length of hex was even
0 otherwise

◆ fmt_is_digit()

static int fmt_is_digit ( char  c)
inlinestatic

Test if the given character is a numerical digit (regex [0-9])

Parameters
[in]cCharacter to test
Returns
true if c is a digit, false otherwise

Definition at line 55 of file fmt.h.

◆ fmt_is_number()

int fmt_is_number ( const char *  str)

Test if the given string is a number (regex [0-9]+)

Parameters
[in]strString to test, must be \0 terminated
Returns
true if str solely contains digits, false otherwise

◆ fmt_is_upper()

static int fmt_is_upper ( char  c)
inlinestatic

Test if the given character is an uppercase letter (regex [A-Z])

Parameters
[in]cCharacter to test
Returns
true if c is an uppercase letter, false otherwise

Definition at line 67 of file fmt.h.

◆ fmt_lpad()

size_t fmt_lpad ( char *  str,
size_t  in_len,
size_t  pad_len,
char  pad_char 
)

Pad string to the left.

This function left-pads a given string str with pad_char.

For example, calling

fmt_lpad("abcd", 4, 7, ' ');

would result in " abcd".

The function only writes to str if str is non-NULL and pad_len is < in_len.

Note
Caller must ensure str can take pad_len characters!
Parameters
[in,out]strstring to pad (or NULL)
[in]in_lenlength of str
[in]pad_lentotal length after padding
[in]pad_charchar to use as pad char
Returns
max(in_len, pad_len)

◆ fmt_s16_dec()

size_t fmt_s16_dec ( char *  out,
int16_t  val 
)

Convert a int16 value to decimal string.

Will add a leading "-" if val is negative.

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of characters written to (or needed in) out

◆ fmt_s16_dfp()

size_t fmt_s16_dfp ( char *  out,
int16_t  val,
int  fp_digits 
)

Convert 16-bit fixed point number to a decimal string.

See fmt_s32_dfp() for more details

Parameters
[out]outPointer to the output buffer, or NULL
[in]valFixed point value
[in]fp_digitsNumber of digits after the decimal point, MUST be >= -7
Returns
Length of the resulting string

◆ fmt_s32_dec()

size_t fmt_s32_dec ( char *  out,
int32_t  val 
)

Convert a int32 value to decimal string.

Will add a leading "-" if val is negative.

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of characters written to (or needed in) out

◆ fmt_s32_dfp()

size_t fmt_s32_dfp ( char *  out,
int32_t  val,
int  fp_digits 
)

Convert 32-bit fixed point number to a decimal string.

The input for this function is a signed 32-bit integer holding the fixed point value as well as an integer defining the position of the decimal point. This value is used to shift the decimal point to the right (positive value of fp_digits) or to the left (negative value of fp_digits).

Will add a leading "-" if val is negative.

The resulting string will always be patted with zeros after the decimal point.

For example: if val is -3548 and fp_digits is -2, the resulting string will be "-35.48". The same value for val with fp_digits of 2 will result in "-354800".

Precondition
fp_digits > -8 (TENMAP_SIZE)
Parameters
[out]outPointer to the output buffer, or NULL
[in]valFixed point value
[in]fp_digitsNumber of digits after the decimal point, MUST be >= -7
Returns
Length of the resulting string

◆ fmt_s64_dec()

size_t fmt_s64_dec ( char *  out,
int64_t  val 
)

Convert a int64 value to decimal string.

Will add a leading "-" if val is negative.

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of characters written to (or needed in) out

◆ fmt_str()

size_t fmt_str ( char *  out,
const char *  str 
)

Copy null-terminated string (excluding terminating \0)

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]strPointer to null-terminated source string
Returns
nr of characters written to (or needed in) out

◆ fmt_strlen()

size_t fmt_strlen ( const char *  str)

Count characters until '\0' (exclusive) in str.

Parameters
[in]strPointer to string
Returns
nr of characters in string str points to

◆ fmt_strnlen()

size_t fmt_strnlen ( const char *  str,
size_t  maxlen 
)

Count at most maxlen characters until '\0' (exclusive) in str.

Parameters
[in]strPointer to string
[in]maxlenMaximum number of chars to count
Returns
nr of characters in string str points to, or maxlen if no null terminator is found within maxlen chars

◆ fmt_to_lower()

size_t fmt_to_lower ( char *  out,
const char *  str 
)

Copy null-terminated string to a lowercase string (excluding terminating \0)

Parameters
[out]outPointer to output buffer, or NULL
[in]strPointer to null-terminated source string

◆ fmt_u16_dec()

size_t fmt_u16_dec ( char *  out,
uint16_t  val 
)

Convert a uint16 value to decimal string.

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of digits written to (or needed in) out

◆ fmt_u16_hex()

size_t fmt_u16_hex ( char *  out,
uint16_t  val 
)

Convert a uint16 value to hex string.

Will write 4 bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
4

◆ fmt_u32_dec()

size_t fmt_u32_dec ( char *  out,
uint32_t  val 
)

Convert a uint32 value to decimal string.

If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of digits written to (or needed in) out

◆ fmt_u32_hex()

size_t fmt_u32_hex ( char *  out,
uint32_t  val 
)

Convert a uint32 value to hex string.

Will write 8 bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
8

◆ fmt_u64_dec()

size_t fmt_u64_dec ( char *  out,
uint64_t  val 
)

Convert a uint64 value to decimal string.

If out is NULL, will only return the number of bytes that would have been written.

Note
This adds ~400b of code when used.
Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
nr of digits written to (or needed in) out

◆ fmt_u64_hex()

size_t fmt_u64_hex ( char *  out,
uint64_t  val 
)

Convert a uint64 value to hex string.

Will write 16 bytes to out. If out is NULL, will only return the number of bytes that would have been written.

Parameters
[out]outPointer to output buffer, or NULL
[in]valValue to convert
Returns
16

◆ print()

void print ( const char *  s,
size_t  n 
)

Print string to stdout.

Writes n bytes from s to STDOUT_FILENO.

Parameters
[out]sPointer to string to print
[in]nNumber of bytes to print

◆ print_byte_hex()

void print_byte_hex ( uint8_t  byte)

Print byte value as hex to stdout.

Parameters
[in]byteByte value to print

◆ print_float()

void print_float ( float  f,
unsigned  precision 
)

Print float value.

Note
See fmt_float for code size warning!
Precondition
-2^32 < f < 2^32
precision < TENMAP_SIZE (== 8)
Parameters
[in]ffloat value to print
[in]precisionnumber of digits after decimal point

◆ print_s32_dec()

void print_s32_dec ( int32_t  val)

Print int32 value to stdout.

Parameters
[in]valValue to print

◆ print_str()

void print_str ( const char *  str)

Print null-terminated string to stdout.

Parameters
[in]strPointer to string to print

◆ print_u32_dec()

void print_u32_dec ( uint32_t  val)

Print uint32 value to stdout.

Parameters
[in]valValue to print

◆ print_u32_hex()

void print_u32_hex ( uint32_t  val)

Print uint32 value as hex to stdout.

Parameters
[in]valValue to print

◆ print_u64_dec()

void print_u64_dec ( uint64_t  val)

Print uint64 value as decimal to stdout.

Note
This uses fmt_u64_dec(), which uses ~400b of code.
Parameters
[in]valValue to print

◆ print_u64_hex()

void print_u64_hex ( uint64_t  val)

Print uint64 value as hex to stdout.

Parameters
[in]valValue to print

◆ scn_u32_dec()

uint32_t scn_u32_dec ( const char *  str,
size_t  n 
)

Convert digits to uint32.

Will convert up to n digits. Stops at any non-digit or '\0' character.

Parameters
[in]strPointer to string to read from
[in]nMaximum nr of characters to consider
Returns
converted uint32_t value

◆ scn_u32_hex()

uint32_t scn_u32_hex ( const char *  str,
size_t  n 
)

Convert hexadecimal characters to uin32_t.

Will convert up to n char. Stop at any non-hexadecimal or '\0' character

Parameters
[in]strPointer to string to read from
[in]nMaximum number of characters to consider
Returns
converted uint32_t value