facil.io
Utilities & Parsers

#String / Number Conversion

c
#define FIO_ATOL
#include "fio-stl.h"

String-to-number and number-to-string helpers. These are the grunts that parse integers, floats, hex, binary, and arbitrary bases, then turn them back into text. Fast, greedy, and mostly guard-less — give them a valid buffer and a terminating character.

Note: functions that write to a buffer also write a NUL terminator. fio_atol* functions assume the buffer ends with an invalid character (such as NUL) and that allocations are aligned enough for multi-byte reads.

Guard-byte contract: parsing may read up to - and including - the first non-numeric byte following a number. Callers MUST keep the buffer readable through that byte: pass a NUL-terminated string or append a non-numeric guard byte. fio_bstr strings always satisfy this contract. Exact-size buffers with no readable byte past the number (e.g., a 1-byte allocation holding "1") violate it and will trigger AddressSanitizer (sanitize with FIO_MEMORY_DISABLE for visibility).

#Configuration Macros

#FIO_ATOL_ALLOW_UNDERSCORE_DIVIDER

c
#define FIO_ATOL_ALLOW_UNDERSCORE_DIVIDER 1

When 1 (default), underscores act as digit separators: 1_000_000 parses as 1000000. Set to 0 to disable.

#Types

#fio_aton_s

c
typedef struct {
  union {
    int64_t i;
    double f;
    uint64_t u;
  };
  int is_float;
  int err;
} fio_aton_s;

Result container for fio_aton. Read the union member that matches is_float, and check err for overflow or parse failures.

#Universal Parsing

#fio_aton

c
FIO_SFUNC fio_aton_s fio_aton(char **pstr);

Auto-detects integers and floats. Skips leading whitespace, recognizes 0x / 0b / octal prefixes, and accepts inf, infinity, and nan. Updates *pstr to the first unconverted character. Sets .err on overflow or bad format.

Note: not an exact strtod replacement; rounding differences are possible.

#Strict, Bounded Parsing (wire-safe)

The fio_stol* family parses within an explicit [pos, end) window and accepts only the wire format: no whitespace, no underscores, no 0x/0b prefixes, no inf/nan. Use these for network protocols and any length/size field - the lenient fio_atol* semantics (e.g., 1_0 parsing as 10) are a differential-parsing hazard when a peer or intermediary parses the same field strictly.

All three advance *pos past the digits consumed (detect trailing junk or empty input by comparing *pos against expectations) and set errno == E2BIG on overflow, stopping at the last valid digit. Since the window is explicit, the guard-byte contract of the lenient family does not apply.

#fio_stol10u

c
SFUNC uint64_t fio_stol10u(char **pos, const char *end);

Parses an unsigned uint64_t, decimal digits only. No sign, no whitespace skip.

#fio_stol10

c
SFUNC int64_t fio_stol10(char **pos, const char *end);

Parses a signed int64_t: one optional leading - / +, then decimal digits only. E2BIG is set when the magnitude overflows uint64_t or exceeds the int64_t range (note: -9223372036854775808 is exactly INT64_MIN and is not an overflow).

#fio_stol16u

c
SFUNC uint64_t fio_stol16u(char **pos, const char *end);

Parses an unsigned uint64_t, hex digits only - unlike fio_atol16u, a 0x prefix is not consumed.

#Signed Conversion

#fio_atol

c
SFUNC int64_t fio_atol(char **pstr);

Parses a signed int64_t. Accepts base 10, octal (0...), hex (0x... or x...), and binary (0b... or b...). Updates *pstr past the number.

#fio_atof

c
SFUNC double fio_atof(char **pstr);

Parses a double. Wraps strtod for most inputs. The source also attempts to accept a raw 0b... binary bit-pattern, but the detection condition looks fragile.

#fio_ftoa

c
SFUNC size_t fio_ftoa(char *dest, double num, uint8_t base);

Writes num to dest in base (2, 10, or 16; unsupported bases silently fall back to 10). No prefixes are added. Returns bytes written excluding NUL.

Note: provide at least 130 bytes for base 2. Special values inf and nan produce "Infinity" / "NaN".

#fio_ltoa

c
SFUNC size_t fio_ltoa(char *dest, int64_t num, uint8_t base);

Writes num to dest in base (2, 8, 10, 16, or any base up to 36). Adds 0x, 0b, or 0 prefixes for the built-in bases. Returns bytes written excluding NUL. If dest is NULL, writes to an internal scratch buffer and still returns the length. Logs an error and returns 0 for unsupported bases.

Note: provide at least 68 bytes for base 2.

#fio_ltoa10

c
FIO_IFUNC void fio_ltoa10(char *dest, int64_t i, size_t digits);

Writes a signed base-10 number using exactly digits bytes plus NUL. Use fio_digits10() to compute digits.

#fio_atol10

c
SFUNC int64_t fio_atol10(char **pstr);

Reads a signed base-10 number.

#Unsigned Conversion

#fio_atol8u

c
SFUNC uint64_t fio_atol8u(char **pstr);

Reads an unsigned octal number. May overflow the buffer if no terminator is present.

#fio_atol10u

c
SFUNC uint64_t fio_atol10u(char **pstr);

Reads an unsigned base-10 number.

#fio_atol16u

c
SFUNC uint64_t fio_atol16u(char **pstr);

Reads an unsigned hex number, with optional 0x prefix.

#fio_atol_bin

c
SFUNC uint64_t fio_atol_bin(char **pstr);

Reads an unsigned binary number, with optional 0b prefix.

#fio_atol_xbase

c
SFUNC uint64_t fio_atol_xbase(char **pstr, size_t base);

Reads an unsigned number in any base up to 36.

#fio_ltoa8u

c
FIO_IFUNC void fio_ltoa8u(char *dest, uint64_t i, size_t digits);

Writes an unsigned octal number using digits bytes plus NUL.

#fio_ltoa10u

c
FIO_IFUNC void fio_ltoa10u(char *dest, uint64_t i, size_t digits);

Writes an unsigned base-10 number using digits bytes plus NUL.

#fio_ltoa16u

c
FIO_IFUNC void fio_ltoa16u(char *dest, uint64_t i, size_t digits);

Writes an unsigned hex number using digits bytes plus NUL. digits is rounded up to an even number.

#fio_ltoa_bin

c
FIO_IFUNC void fio_ltoa_bin(char *dest, uint64_t i, size_t digits);

Writes an unsigned binary number using digits bytes plus NUL.

#fio_ltoa_xbase

c
FIO_IFUNC void fio_ltoa_xbase(char *dest,
                              uint64_t i,
                              size_t digits,
                              size_t base);

Writes an unsigned number in base (up to 36) using digits bytes plus NUL.

#Helpers

#fio_c2i

c
IFUNC uint8_t fio_c2i(unsigned char c);

Maps a character to its numeric value (0-9 → 0-9, A-Z/a-z → 10-35). Returns 255 for out-of-range characters.

#fio_i2c

c
IFUNC uint8_t fio_i2c(unsigned char i);

Maps a numeric value 0-35 to a character (0-9, A-Z). Out-of-range values above 35 produce undefined behavior; accepts values up to 63 by masking.

#fio_digits10

c
FIO_IFUNC size_t fio_digits10(int64_t i);

Returns the number of base-10 digits needed for i, including the sign.

#fio_digits10u

c
FIO_SFUNC size_t fio_digits10u(uint64_t i);

Returns the number of base-10 digits needed for an unsigned number.

#fio_digits8u

c
FIO_SFUNC size_t fio_digits8u(uint64_t i);

Returns the number of base-8 digits needed for an unsigned number.

#fio_digits16u

c
FIO_SFUNC size_t fio_digits16u(uint64_t i);

Returns the number of base-16 digits needed for an unsigned number, always an even count (2, 4, 6, ... 16).

#fio_digits_bin

c
FIO_SFUNC size_t fio_digits_bin(uint64_t i);

Returns the number of base-2 digits needed for an unsigned number, rounded up to an even count.

#fio_digits_xbase

c
FIO_SFUNC size_t fio_digits_xbase(uint64_t i, size_t base);

Returns the number of digits needed for an unsigned number in base (must be < 65).

#fio_u2i_limit

c
FIO_IFUNC int64_t fio_u2i_limit(uint64_t val, size_t invert);

Converts unsigned val to signed with overflow protection. If invert is zero, clamps to INT64_MAX and sets errno = E2BIG on overflow. If invert is non-zero, produces the negative value and clamps to INT64_MIN.

#IEEE 754 Helpers

#fio_i2d

c
FIO_IFUNC double fio_i2d(int64_t mant, int64_t exponent_in_base_2);

Converts a signed 64-bit mantissa and base-2 exponent to a double.

#fio_u2d

c
FIO_IFUNC double fio_u2d(uint64_t mant, int64_t exponent_in_base_2);

Converts an unsigned 64-bit mantissa and base-2 exponent to a double.

#Big Number Hex Conversion

#fio_u128_hex_read / fio_u256_hex_read / fio_u512_hex_read

c
SFUNC fio_u128 fio_u128_hex_read(char **pstr);
SFUNC fio_u256 fio_u256_hex_read(char **pstr);
SFUNC fio_u512 fio_u512_hex_read(char **pstr);

Reads a hex string and initializes the corresponding wide integer. Updates *pstr past the consumed input.

#fio_u1024_hex_read / fio_u2048_hex_read / fio_u4096_hex_read

c
SFUNC fio_u1024 fio_u1024_hex_read(char **pstr);
SFUNC fio_u2048 fio_u2048_hex_read(char **pstr);
SFUNC fio_u4096 fio_u4096_hex_read(char **pstr);

Same as above for 1024-, 2048-, and 4096-bit integers.

#fio_u128_hex_write / fio_u256_hex_write / fio_u512_hex_write

c
SFUNC size_t fio_u128_hex_write(char *dest, const fio_u128 *u);
SFUNC size_t fio_u256_hex_write(char *dest, const fio_u256 *u);
SFUNC size_t fio_u512_hex_write(char *dest, const fio_u512 *u);

Writes a wide integer as a hex string to dest. Returns bytes written excluding NUL.

#fio_u1024_hex_write / fio_u2048_hex_write / fio_u4096_hex_write

c
SFUNC size_t fio_u1024_hex_write(char *dest, const fio_u1024 *u);
SFUNC size_t fio_u2048_hex_write(char *dest, const fio_u2048 *u);
SFUNC size_t fio_u4096_hex_write(char *dest, const fio_u4096 *u);

Same as above for 1024-, 2048-, and 4096-bit integers.

#Example

c
#define FIO_ATOL
#include "fio-stl.h"

int main(void) {
  char *p = "0x1F 0b1010 42";
  char buf[80];

  printf("hex: %lld\n", (long long)fio_atol(&p));
  ++p; /* skip space */
  printf("bin: %lld\n", (long long)fio_atol(&p));
  ++p;
  printf("dec: %lld\n", (long long)fio_atol(&p));

  fio_ltoa(buf, -255, 16);
  printf("back to hex: %s\n", buf);
  return 0;
}