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 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.

Topics
	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)
int	fmt_time_tm_iso8601 (char out[20], const struct tm *tm, char separator)
	Format a time structure to an ISO 8601 string.
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.
ssize_t	scn_buf_hex (void *dest, size_t dest_len, const char *hex, size_t hex_len)
	Convert a hex to binary.
int	scn_time_tm_iso8601 (struct tm *tm, const char *str, char separator)
	Convert an ISO 8601 string to time structure.
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 54 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 64 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 76 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_time_tm_iso8601()

int fmt_time_tm_iso8601	(	char	out[20],
		const struct tm *	tm,
		char	separator )

Format a time structure to an ISO 8601 string.

This function does only take care of format validity and not of date/time validity.

Parameters

[out]	out	Pointer to output buffer
[in]	tm	Pointer to time structure
[in]	separator	Date and time separator. Must be 'T' for ISO 8601 or may be ' '

Returns

nr of characters written to (or needed in) out

Return values

-EINVAL

if tm is specifying a number for year, month, day, hour, minute which would yield to an invalid date/time format

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_buf_hex()

ssize_t scn_buf_hex	(	void *	dest,
		size_t	dest_len,
		const char *	hex,
		size_t	hex_len )

Convert a hex to binary.

Parameters

[out]	dest	Destination buffer to write to
[in]	dest_len	Size of dest in bytes
[in]	hex	Hex string to convert
[in]	hex_len	Length of hex in bytes

Returns

Number of bytes written

Return values

-EINVAL	hex_len is odd or hex contains non-hex chars
-EOVERFLOW	Destination to small

Precondition

If dest_len is > 0, dest is not a null pointer

If hex_len is > 0, hex is not a null pointer

Examples

const char *hex = "deadbeef";
uint8_t binary[sizeof(hex) / 2];
ssize_t len = scn_buf_hex(binary, sizeof(binary), hex, strlen(hex));
if (len >= 0) {
    make_use_of(binary, len);
}

scn_time_tm_iso8601()

int scn_time_tm_iso8601	(	struct tm *	tm,
		const char *	str,
		char	separator )

Convert an ISO 8601 string to time structure.

This function parses a string in the format YYYY-MM-DD<separator>HH:MM:SS or YYYY-MM-DD.

A terminating '\0' is not required.

This function does only take care of format validity and not of date/time validity.

Parameters

[out]	tm	Pointer to time structure
[in]	str	Pointer to string to read from
[in]	separator	Date and time separator

Returns

Number of characters read from str on success (19 or 10)

Return values

-EINVAL	if str has an invalid format
-EBADF	if the expected separator does not match

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