fmt: Formatting Functions

Miscelaneous formatting
unsigned	fmt_char (char *buffer, int ch, unsigned width, char pad)
unsigned	fmt_mem (char *buffer, const char *s, unsigned length, unsigned width, char pad)
unsigned	fmt_chars (char *buffer, const char *s, unsigned width, char pad)
unsigned	fmt_str (char *buffer, const struct str *s, unsigned width, char pad)
Multiple item formatting
unsigned	fmt_multi (char *buffer, const char *format,...)
unsigned	fmt_multiv (char *buffer, const char *format, va_list ap)
Signed integer conversions
unsigned	fmt_snumw (char *buffer, long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_sdec (char *buffer, long num)
unsigned	fmt_sdecw (char *buffer, long num, unsigned width, char pad)
Signed long long integer conversions
unsigned	fmt_sllnumw (char *buffer, long long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_slldec (char *buffer, long long num)
unsigned	fmt_slldecw (char *buffer, long long num, unsigned width, char pad)
Unsigned integer conversions
unsigned	fmt_unumw (char *buffer, unsigned long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_udec (char *buffer, unsigned long num)
unsigned	fmt_udecw (char *buffer, unsigned long num, unsigned width, char pad)
unsigned	fmt_uhex (char *buffer, unsigned long num)
unsigned	fmt_uhexw (char *buffer, unsigned long num, unsigned width, char pad)
unsigned	fmt_uHex (char *buffer, unsigned long num)
unsigned	fmt_uHexw (char *buffer, unsigned long num, unsigned width, char pad)
Unsigned long long integer conversions
unsigned	fmt_ullnumw (char *buffer, unsigned long long num, unsigned width, char pad, unsigned base, const char *digits)
unsigned	fmt_ulldec (char *buffer, unsigned long long num)
unsigned	fmt_ulldecw (char *buffer, unsigned long long num, unsigned width, char pad)
unsigned	fmt_ullhex (char *buffer, unsigned long long num)
unsigned	fmt_ullhexw (char *buffer, unsigned long long num, unsigned width, char pad)
unsigned	fmt_ullHex (char *buffer, unsigned long long num)
unsigned	fmt_ullHexw (char *buffer, unsigned long long num, unsigned width, char pad)
Defines
#define	FMT_ULONG_LEN   40
Functions
unsigned	fmt_pad (char *buffer, unsigned width, char pad)
unsigned	fmt_sign_pad (char *buffer, int sign, unsigned width, char pad)
Variables
const char	fmt_lcase_digits [36]
const char	fmt_ucase_digits [36]

---

Detailed Description

Function Naming

1. Prefix
   • fmt_ : Always present
2. Data type
   • s : Signed integer (long)
   • u : Unsigned integer (long)
   • sll : Signed long long integer
   • ull : Unsigned long long integer
3. Conversion type
   • num : Generic number
   • dec : Decimal
   • hex : Hexadecimal (lower case)
   • Hex : Hexadecimal (upper case)
4. Width / Padding
   • w : (optional) Pad out the result to a minimum width

For example, fmt_sdecw formats a signed integer using decimal with width padding.

Calling Convention

Parameters to the fmt functions are passed in the following order. The presence of all parameters, except for buffer, is dependant on which function is being used.

1. buffer : The character string into which to put the data result. If this is NULL, no data is written, and only the length is calculated. This is useful for determining how long a formatted string might be.
2. number or data : The input data item to convert.
3. width : The minimum output width.
4. pad : The character with which to pad the output.
5. base : The numerical base to use.
6. digits : The array of digits to use.

Return Value

All fmt functions return the number of bytes written to the buffer space.

---

Define Documentation

#define FMT_ULONG_LEN   40

The maximum space used by a formatted number. This value is long enough for 2^128 plus a trailing NUL byte.

---

Function Documentation

unsigned fmt_char	(	char *	buffer,
		int	ch,
		unsigned	width,
		char	pad
	)

Format a single character

unsigned fmt_multi	(	char *	buffer,
		const char *	format,
			...
	)

Format multiple items.

The format string used to describe the multiple items is related to what is used with printf and related functions, but has one critical difference: instead of formatted items being escaped, literal text must be escaped. This solves the largest security issue with using printf-style format strings, which is the possibility of accidentally treating untrusted text as the format string.

The format string is composed of zero or more format items. Each item is composed of the following parts:

Zero or more flag characters:

#

Use an "alternate form" to convert the value. For octal conversion, the result is prefixed with a 0 . For hexadecimal conversion, the result is prefixed with either 0x or 0X depending on the conversion type.

-

(not implemented) Pad on the right (left justified) instead of on the left (default right justified).

0

Pad the result with zeros instead of spaces.

Field width.

The option field width is a decimal digit string specifying the minimum field width. If the converted value has fewer characters than the field width, it will be padded out to the field width.

Length modifier:

l

The following conversion uses a long integer type.

ll

The following conversion uses a long long integer type.

Conversion specifier.

d

i

The int argument is converted to a signed decimal string.

o

u

x

X

The unsigned int argument is converted to a unsigned octal, unsigned decimal, lowercase unsigned hexadecimal, or uppercase unsigned hexadecimal string respectively.

c

The int argument is converted to an unsigned char.

s

The const char* argument is converted.

S

The const str* argument is converted.

p

The void* argument is converted to a hexadecimal string.

m

The result of strerror(errno) is formatted.

\

The next character literal from the format string is converted as with c conversion.

{string}

The literal string enclosed by the parenthesis is converted as with s conversion.

unsigned fmt_multiv	(	char *	buffer,
		const char *	format,
		va_list	ap
	)

Format multiple items, using a va_list.

This is the core function used to format multiple items.

unsigned fmt_pad	(	char *	buffer,
		unsigned	width,
		char	pad
	)

Format a pad character.

unsigned fmt_sdec	(	char *	buffer,
		long	num
	)

Format a signed integer as decimal.

unsigned fmt_sdecw	(	char *	buffer,
		long	num,
		unsigned	width,
		char	pad
	)

Format a signed integer as decimal with padding.

unsigned fmt_sign_pad	(	char *	buffer,
		int	sign,
		unsigned	width,
		char	pad
	)

Format padding for a signed number.

unsigned fmt_slldec	(	char *	buffer,
		long long	num
	)

Format a signed long long integer as decimal.

unsigned fmt_slldecw	(	char *	buffer,
		long long	num,
		unsigned	width,
		char	pad
	)

Format a signed long long integer as decimal with padding.

unsigned fmt_sllnumw	(	char *	buffer,
		long long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format a signed long long integer of arbitrary base with optional padding.

unsigned fmt_snumw	(	char *	buffer,
		long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format a signed integer of arbitrary base with optional padding.

unsigned fmt_udec	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as decimal.

unsigned fmt_udecw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as decimal with padding.

unsigned fmt_uHex	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as (upper-case) hexadecimal.

unsigned fmt_uhex	(	char *	buffer,
		unsigned long	num
	)

Format an unsigned integer as (lower-case) hexadecimal.

unsigned fmt_uHexw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as (upper-case) hexadecimal with padding.

unsigned fmt_uhexw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned integer as (lower-case) hexadecimal with padding.

unsigned fmt_ulldec	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as decimal.

unsigned fmt_ulldecw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as decimal with padding.

unsigned fmt_ullHex	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as (upper-case) hexadecimal.

unsigned fmt_ullhex	(	char *	buffer,
		unsigned long long	num
	)

Format an unsigned long long integer as hexadecimal.

unsigned fmt_ullHexw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as (upper-case) hexadecimal with padding.

unsigned fmt_ullhexw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad
	)

Format an unsigned long long integer as hexadecimal with padding.

unsigned fmt_ullnumw	(	char *	buffer,
		unsigned long long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format an unsigned long long integer of arbitrary base with optional padding.

unsigned fmt_unumw	(	char *	buffer,
		unsigned long	num,
		unsigned	width,
		char	pad,
		unsigned	base,
		const char *	digits
	)

Format an unsigned integer of arbitrary base with optional padding.

---

Variable Documentation

const char fmt_lcase_digits[36]

Array of digits for lower-case conversions

const char fmt_ucase_digits[36]

Array of digits for upper-case conversions

---