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 fmt functions expect their out parameter to hold the entire output. This MUST be ensured by the caller.; Each fmt function will not write anything to out if it is NULL, but still return the number of characters that would have been written. This can be used to ensure the out buffer is large enough.; 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]`)

static int	fmt_is_upper (char c)
	Test if the given character is an uppercase letter (regex `[A-Z]`)

int	fmt_is_number (const char *str)
	Test if the given string is a number (regex `[0-9]+`)

size_t	fmt_byte_hex (char *out, uint8_t byte)
	Format a byte value as hex.

size_t	fmt_bytes_hex (char out, const uint8_t ptr, size_t n)
	Formats a sequence of bytes as hex characters.

size_t	fmt_bytes_hex_reverse (char out, const uint8_t ptr, size_t n)
	Formats a sequence of bytes as hex characters, starting with the last byte.

uint8_t	fmt_hex_byte (const char *hex)
	Converts a sequence of two hex characters to a byte.

size_t	fmt_hex_bytes (uint8_t out, const char hex)
	Converts a sequence of hex characters to an array of bytes.

size_t	fmt_u16_hex (char *out, uint16_t val)
	Convert a uint16 value to hex string.

size_t	fmt_u32_hex (char *out, uint32_t val)
	Convert a uint32 value to hex string.

size_t	fmt_u64_hex (char *out, uint64_t val)
	Convert a uint64 value to hex string.

size_t	fmt_u16_dec (char *out, uint16_t val)
	Convert a uint16 value to decimal string.

size_t	fmt_u32_dec (char *out, uint32_t val)
	Convert a uint32 value to decimal string.

size_t	fmt_u64_dec (char *out, uint64_t val)
	Convert a uint64 value to decimal string.

size_t	fmt_s64_dec (char *out, int64_t val)
	Convert a int64 value to decimal string.

size_t	fmt_s32_dec (char *out, int32_t val)
	Convert a int32 value to decimal string.

size_t	fmt_s16_dec (char *out, int16_t val)
	Convert a int16 value to decimal string.

size_t	fmt_s16_dfp (char *out, int16_t val, int scale)
	Convert 16-bit fixed point number to a decimal string.

size_t	fmt_s32_dfp (char *out, int32_t val, int scale)
	Convert 32-bit fixed point number to a decimal string.

size_t	fmt_float (char *out, float f, unsigned precision)
	Format float to string.

size_t	fmt_char (char *out, char c)
	Copy `in` char to string (without terminating '\0')

size_t	fmt_strlen (const char *str)
	Count characters until '\0' (exclusive) in `str`.

size_t	fmt_strnlen (const char *str, size_t maxlen)
	Count at most `maxlen` characters until '\0' (exclusive) in `str`.

size_t	fmt_str (char out, const char str)
	Copy null-terminated string (excluding terminating \0)

size_t	fmt_to_lower (char out, const char str)
	Copy null-terminated string to a lowercase string (excluding terminating \0)

uint32_t	scn_u32_dec (const char *str, size_t n)
	Convert string of decimal digits to uint32.

uint32_t	scn_u32_hex (const char *str, size_t n)
	Convert string hexadecimal digits to uin32_t.

void	print (const char *s, size_t n)
	Print string to stdout.

void	print_u32_dec (uint32_t val)
	Print uint32 value to stdout.

void	print_s32_dec (int32_t val)
	Print int32 value to stdout.

void	print_byte_hex (uint8_t byte)
	Print byte value as hex to stdout.

void	print_bytes_hex (const void *bytes, size_t n)
	Print bytes as hex to stdout.

void	print_u32_hex (uint32_t val)
	Print uint32 value as hex to stdout.

void	print_u64_hex (uint64_t val)
	Print uint64 value as hex to stdout.

void	print_u64_dec (uint64_t val)
	Print uint64 value as decimal to stdout.

void	print_s64_dec (uint64_t val)
	Print int64 value as decimal to stdout.

void	print_float (float f, unsigned precision)
	Print float value.

void	print_str (const char *str)
	Print null-terminated string to stdout.

size_t	fmt_lpad (char *str, size_t in_len, size_t pad_len, char pad_char)
	Pad string to the left.

Macro Definition Documentation

◆ FMT_USE_MEMMOVE

#define FMT_USE_MEMMOVE (1)

use memmove() or internal implementation

Definition at line 52 of file fmt.h.

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 characters to out. If out is NULL, will only return the number of characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	byte	Byte 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 characters.

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

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	ptr	Pointer to bytes to convert
[in]	n	Number 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 characters, starting with the last byte.

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

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	ptr	Pointer to bytes to convert
[in]	n	Number 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 characters that would have been written.

Parameters

[out]	out	string to write to (or NULL)
[in]	c	char value to append

Returns: nr of characters 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 characters 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]	out	string to write to (or NULL)
[in]	f	float value to convert
[in]	precision	number of digits after decimal point

Returns: nr of characters 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] hex Pointer 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 characters 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 does not write to out.

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

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

Parameters

[out]	out	Pointer to converted bytes, or NULL
[in]	hex	Pointer 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] c Character to test

Returns: true if c is a digit, false otherwise

Definition at line 62 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] str String to test, must be \0 terminated

Returns: true if str solely contains decimal 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] c Character to test

Returns: true if c is an uppercase letter, false otherwise

Definition at line 74 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]	str	string to pad (or NULL)
[in]	in_len	length of str
[in]	pad_len	total length after padding
[in]	pad_char	char 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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value 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	scale
	)

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

See fmt_s32_dfp() for more details

Parameters

[out]	out	Pointer to the output buffer, or NULL
[in]	val	Fixed point value
[in]	scale	Scale value

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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value 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	scale
	)

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

This multiplies a 32bit signed number by 10^(scale) before formatting.

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

For example: if val is -35648 and scale is -2, the resulting string will be "-352.48"( -35648*10^-2). The same value for val with scale of 2 will result in "-3524800" (-35648*10^2).

Parameters

[out]	out	Pointer to the output buffer, or NULL
[in]	val	Fixed point value
[in]	scale	Scale value

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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value 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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	str	Pointer 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] str Pointer 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]	str	Pointer to string
[in]	maxlen	Maximum 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)

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

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	str	Pointer to null-terminated source string

Returns: nr of characters written to (or needed in) out

◆ 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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value to convert

Returns: nr of characters 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 characters to out. If out is NULL, will only return the number of characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value 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 characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value to convert

Returns: nr of characters 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 characters to out. If out is NULL, will only return the number of characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value 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 characters that would have been written.

Note: This adds ~400b of code when used.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value to convert

Returns: nr of characters 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 characters to out. If out is NULL, will only return the number of characters that would have been written.

Parameters

[out]	out	Pointer to output buffer, or NULL
[in]	val	Value to convert

Returns: 16

◆ print()

void print	(	const char *	s,
		size_t	n
	)

Print string to stdout.

Writes n characters from s to STDOUT_FILENO.

Parameters

[out]	s	Pointer to string to print
[in]	n	Number of characters to print

◆ print_byte_hex()

void print_byte_hex ( uint8_t byte )

Print byte value as hex to stdout.

Parameters

[in] byte Byte value to print

◆ print_bytes_hex()

void print_bytes_hex	(	const void *	bytes,
		size_t	n
	)

Print bytes as hex to stdout.

Parameters

[in]	bytes	Byte array to print
[in]	n	Number of bytes 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]	f	float value to print
[in]	precision	number of digits after decimal point

◆ print_s32_dec()

void print_s32_dec ( int32_t val )

Print int32 value to stdout.

Parameters

[in] val Value to print

◆ print_s64_dec()

void print_s64_dec ( uint64_t val )

Print int64 value as decimal to stdout.

Note: This uses fmt_s64_dec(), which uses ~400b of code.

Parameters

[in] val Value to print

◆ print_str()

void print_str ( const char * str )

Print null-terminated string to stdout.

Parameters

[in] str Pointer to string to print

◆ print_u32_dec()

void print_u32_dec ( uint32_t val )

Print uint32 value to stdout.

Parameters

[in] val Value to print

◆ print_u32_hex()

void print_u32_hex ( uint32_t val )

Print uint32 value as hex to stdout.

Parameters

[in] val Value 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] val Value to print

◆ print_u64_hex()

void print_u64_hex ( uint64_t val )

Print uint64 value as hex to stdout.

Parameters

[in] val Value to print

◆ scn_u32_dec()

uint32_t scn_u32_dec	(	const char *	str,
		size_t	n
	)

Convert string of decimal digits to uint32.

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

Parameters

[in]	str	Pointer to string to read from
[in]	n	Maximum 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 string hexadecimal digits to uin32_t.

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

Parameters

[in]	str	Pointer to string to read from
[in]	n	Maximum number of characters to consider

Returns: converted uint32_t value

Detailed Description

Modules

Files

Macros

Functions

Macro Definition Documentation

◆ FMT_USE_MEMMOVE

Function Documentation

◆ fmt_byte_hex()

◆ fmt_bytes_hex()

◆ fmt_bytes_hex_reverse()

◆ fmt_char()

◆ fmt_float()

◆ fmt_hex_byte()

◆ fmt_hex_bytes()

◆ fmt_is_digit()

◆ fmt_is_number()

◆ fmt_is_upper()

◆ fmt_lpad()

◆ fmt_s16_dec()

◆ fmt_s16_dfp()

◆ fmt_s32_dec()

◆ fmt_s32_dfp()

◆ fmt_s64_dec()

◆ fmt_str()

◆ fmt_strlen()

◆ fmt_strnlen()

◆ fmt_to_lower()

◆ fmt_u16_dec()

◆ fmt_u16_hex()

◆ fmt_u32_dec()

◆ fmt_u32_hex()

◆ fmt_u64_dec()

◆ fmt_u64_hex()

◆ print()

◆ print_byte_hex()

◆ print_bytes_hex()

◆ print_float()

◆ print_s32_dec()

◆ print_s64_dec()

◆ print_str()

◆ print_u32_dec()

◆ print_u32_hex()

◆ print_u64_dec()

◆ print_u64_hex()

◆ scn_u32_dec()

◆ scn_u32_hex()