skalibs: the fmtscan header
Keywords: skalibs header fmtscan format scan printf scanf

libstddjb
libskarnet
skalibs
Software
skarnet.org

# Formatting and scanning functions

The preferred skalibs way of converting objects to string for output is to use the various `*_fmt` functions available in `skalibs/fmtscan.h` and other object-specific headers. These functions take at least two parameters:

- The target buffer into which the formatted object will be written. This buffer must be large enough to hold the formatted object.
- The object that should be formatted into the buffer.

They return the number of bytes written into the buffer.

To ensure that the buffer is large enough, `skalibs` provides several `x_FMT` macros corresponding to the minimum buffer size necessary for formatting an object of type x to a string, including the terminating nul byte.

Conversely, to scan objects from a string, skalibs provides several `*_scan` functions. They take the same parameters as the `*_fmt` ones, with meaning reversed. They return the number of bytes read from the input buffer

## Examples

     uint32_t u = ... ;
     char buf[UINT32_FMT] ;
     buf[uint32_fmt(buf, u)] = 0 ;

     char *buf = "123a" ;
     uint32_t u ;
     size_t p ;
     p = uint32_scan(buf, &u) ;
     // p is 3, u is 123

## Functions

Formatting and scanning functions for the integer types can be found in `skalibs/uint16h`, `skalibs/uint32.h` and `skalibs/uint64.h`, those for standard unix types (such as `pid_t` or `uid_t`) can be found in `skalibs/types.h`. Other formatting functions can be found in `skalibs/fmtscan.h`.

`size_t uint64_fmt_generic (char *s, uint64_t i, uint8_t b)`
Write the representation in base b of integer i into the buffer pointed to by s. Returns the number of bytes written.

`size_t uint640_fmt_generic (char *s, uint64_t i, size_t pad, uint8_t b)`
Write the representation in base b of integer i into the buffer pointed to by s, padding if necessary with zeros to ensure the written string is at least pad bytes long. Returns the number of bytes written.

`size_t uint64_scan_base (char const *s, uint64_t *i, uint8_t b)`
Scan the first bytes of the buffer pointed to by s for an `uint64_t` exrpessed in base b and write it into i. Returns the number of bytes read.

The above are the most fundamental functions. Other functions are usually expressed in terms of these, or have self-explanatory prototypes.