bglibs: fmt: Formatting Functions

- Main Page
- Modules
- Data Structures
- Files
- Directories
- Related Pages
- Examples

# 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