fmt: Formatting Functions

## Macros

#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]

## Multiple item formatting

typedef unsigned(* | fmt_function) (char *buffer, const void *data, unsigned width, char pad)
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)

## 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)

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

## Macro Definition Documentation

## FMT_ULONG_LEN

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

## Typedef Documentation

## fmt_function

typedef unsigned(* fmt_function) (char *buffer, const void *data, unsigned width, char pad)

Format function prototype, used by the "@" conversion in fmt_multi()

## Function Documentation

## fmt_char()

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

extern

Format a single character

Referenced by fmt_multiv().

## fmt_multi()

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

extern

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 integer conversion uses a `long` type.

`ll`

  The following integer conversion uses a `long` `long` 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.

`@`

  Formats an arbitrary object using two arguments: The first fmt_function argument is used to format the following `void*` argument. The fmt_function is passed the output buffer, the data pointer, width, and pad character, and is expected to return the number of bytes formatted.

References fmt_multiv().

## fmt_multiv()

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

extern

Format multiple items, using a va_list.

This is the core function used to format multiple items.

References fmt_char(), fmt_lcase_digits, fmt_sllnumw(), fmt_snumw(), fmt_ucase_digits, fmt_ullnumw(), fmt_unumw(), str::len, and str::s.

Referenced by fmt_multi(), obuf_putfv(), str_catfv(), and str_copyfv().

## fmt_pad()

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

extern

Format a pad character.

## fmt_sdec()

unsigned fmt_sdec | ( | char * | buffer,
|  | long | num )

extern

Format a signed integer as decimal.

References fmt_lcase_digits, and fmt_snumw().

## fmt_sdecw()

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

extern

Format a signed integer as decimal with padding.

References fmt_lcase_digits, and fmt_snumw().

## fmt_sign_pad()

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

extern

Format padding for a signed number.

Referenced by fmt_sllnumw(), and fmt_snumw().

## fmt_slldec()

unsigned fmt_slldec | ( | char * | buffer,
|  | long long | num )

extern

Format a signed long long integer as decimal.

References fmt_lcase_digits, and fmt_sllnumw().

## fmt_slldecw()

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

extern

Format a signed long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_sllnumw().

## fmt_sllnumw()

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

extern

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

References fmt_sign_pad().

Referenced by fmt_multiv(), fmt_slldec(), fmt_slldecw(), obuf_putsllnumw(), and str_catsllnumw().

## fmt_snumw()

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

extern

Format a signed integer of arbitrary base with optional padding.

References fmt_sign_pad().

Referenced by fmt_multiv(), fmt_sdec(), fmt_sdecw(), obuf_putsnumw(), and str_catsnumw().

## fmt_udec()

unsigned fmt_udec | ( | char * | buffer,
|  | unsigned long | num )

extern

Format an unsigned integer as decimal.

References fmt_lcase_digits, and fmt_unumw().

Referenced by dns_name4_domain().

## fmt_udecw()

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

extern

Format an unsigned integer as decimal with padding.

References fmt_lcase_digits, and fmt_unumw().

## fmt_uHex()

unsigned fmt_uHex | ( | char * | buffer,
|  | unsigned long | num )

extern

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

References fmt_ucase_digits, and fmt_unumw().

## fmt_uhex()

unsigned fmt_uhex | ( | char * | buffer,
|  | unsigned long | num )

extern

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

References fmt_lcase_digits, and fmt_unumw().

## fmt_uHexw()

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

extern

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

References fmt_ucase_digits, and fmt_unumw().

## fmt_uhexw()

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

extern

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

References fmt_lcase_digits, and fmt_unumw().

## fmt_ulldec()

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

extern

Format an unsigned long long integer as decimal.

References fmt_lcase_digits, and fmt_ullnumw().

## fmt_ulldecw()

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

extern

Format an unsigned long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

## fmt_ullHex()

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

extern

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

References fmt_ucase_digits, and fmt_ullnumw().

## fmt_ullhex()

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

extern

Format an unsigned long long integer as hexadecimal.

References fmt_lcase_digits, and fmt_ullnumw().

## fmt_ullHexw()

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

extern

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

References fmt_ucase_digits, and fmt_ullnumw().

## fmt_ullhexw()

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

extern

Format an unsigned long long integer as hexadecimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

## fmt_ullnumw()

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

extern

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

Referenced by fmt_multiv(), fmt_ulldec(), fmt_ulldecw(), fmt_ullHex(), fmt_ullhex(), fmt_ullHexw(), fmt_ullhexw(), obuf_putullnumw(), and str_catullnumw().

## fmt_unumw()

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

extern

Format an unsigned integer of arbitrary base with optional padding.

Referenced by fmt_multiv(), fmt_udec(), fmt_udecw(), fmt_uHex(), fmt_uhex(), fmt_uHexw(), fmt_uhexw(), obuf_putunumw(), and str_catunumw().

## Variable Documentation

## fmt_lcase_digits

const char fmt_lcase_digits[36]

extern

Array of digits for lower-case conversions

Referenced by dns_name6_domain(), fmt_multiv(), fmt_sdec(), fmt_sdecw(), fmt_slldec(), fmt_slldecw(), fmt_udec(), fmt_udecw(), fmt_uhex(), fmt_uhexw(), fmt_ulldec(), fmt_ulldecw(), fmt_ullhex(), fmt_ullhexw(), obuf_puti(), obuf_putill(), obuf_putiw(), obuf_putiwll(), obuf_putu(), obuf_putull(), obuf_putuw(), obuf_putuwll(), obuf_putx(), obuf_putxll(), obuf_putxw(), obuf_putxwll(), str_cati(), str_catill(), str_catiw(), str_catiwll(), str_catu(), str_catull(), str_catuw(), str_catuwll(), str_catx(), str_catxll(), str_catxw(), and str_catxwll().

## fmt_ucase_digits

const char fmt_ucase_digits[36]

extern

Array of digits for upper-case conversions

Referenced by fmt_multiv(), fmt_uHex(), fmt_uHexw(), fmt_ullHex(), fmt_ullHexw(), obuf_putX(), obuf_putXll(), obuf_putXw(), and obuf_putXwll().