bglibs: fmt: Formatting Functions

bglibs

Macros | Functions | Variables
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]

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

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

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

Referenced by fmt_sllnumw(), fmt_snumw(), fmt_ullnumw(), and fmt_unumw().

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

Format a single character

References fmt_char(), obuf_endl(), obuf_putu(), obuf_write(), and outbuf.

Referenced by fmt_char(), and fmt_multiv().

## ◆ fmt_multi()

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 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_ullnumw(), and fmt_unumw().

## ◆ fmt_multiv()

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.

References fmt_char(), fmt_lcase_digits, fmt_sllnumw(), fmt_snumw(), fmt_ucase_digits, fmt_ullnumw(), and fmt_unumw().

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

## ◆ fmt_pad()

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

Format a pad character.

## ◆ fmt_sdec()

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

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

Format a signed integer as decimal with padding.

References fmt_lcase_digits, and fmt_snumw().

Referenced by fmt_sllnumw(), and fmt_snumw().

## ◆ fmt_sign_pad()

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

Format padding for a signed number.

References fmt_sign_pad(), obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_sign_pad(), fmt_sllnumw(), and fmt_snumw().

## ◆ fmt_slldec()

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

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

Format a signed long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_sllnumw().

Referenced by fmt_sllnumw().

## ◆ fmt_sllnumw()

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.

References fmt_sdecw(), fmt_sign_pad(), fmt_slldecw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

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

Format a signed integer of arbitrary base with optional padding.

References fmt_sdecw(), fmt_sign_pad(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

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

## ◆ fmt_udec()

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

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

Format an unsigned integer as decimal with padding.

References fmt_lcase_digits, and fmt_unumw().

Referenced by fmt_unumw().

## ◆ fmt_uhex()

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

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

References fmt_lcase_digits, and fmt_unumw().

## ◆ fmt_uHex()

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

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

References fmt_ucase_digits, and fmt_unumw().

## ◆ fmt_uhexw()

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

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

References fmt_lcase_digits, and fmt_unumw().

Referenced by fmt_unumw().

## ◆ fmt_uHexw()

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

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

References fmt_ucase_digits, and fmt_unumw().

Referenced by fmt_unumw().

## ◆ fmt_ulldec()

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

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

Format an unsigned long long integer as decimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

## ◆ fmt_ullhex()

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

Format an unsigned long long integer as hexadecimal.

References fmt_lcase_digits, and fmt_ullnumw().

## ◆ fmt_ullHex()

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

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

References fmt_ucase_digits, and fmt_ullnumw().

## ◆ fmt_ullhexw()

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

Format an unsigned long long integer as hexadecimal with padding.

References fmt_lcase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

## ◆ fmt_ullHexw()

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.

References fmt_ucase_digits, and fmt_ullnumw().

Referenced by fmt_ullnumw().

## ◆ fmt_ullnumw()

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.

References fmt_ulldecw(), fmt_ullhexw(), fmt_ullHexw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multi(), 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
| ) |  |

Format an unsigned integer of arbitrary base with optional padding.

References fmt_udecw(), fmt_uHexw(), fmt_uhexw(), FMT_ULONG_LEN, obuf_putc(), obuf_puts, obuf_putu(), and outbuf.

Referenced by fmt_multi(), 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]

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]

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