Numeric Conversion

Modules
	Internal conversion functions

Enumerations
enum	STRNUM_FLAGS { STRNUM_NoTrailing = 0x01 , STRNUM_NoWS = 0x02 , STRNUM_NoPrefix = 0x04 , STRNUM_NoSign = 0x08 }

Functions
bool	strToInt32 (int32 *out, strref s, int base, flags_t flags)
bool	strToUInt32 (uint32 *out, strref s, int base, flags_t flags)
bool	strToInt64 (int64 *out, strref s, int base, flags_t flags)
bool	strToUInt64 (uint64 *out, strref s, int base, flags_t flags)
bool	strFromInt32 (strhandle out, int32 i, uint16 base)
bool	strFromUInt32 (strhandle out, uint32 i, uint16 base)
bool	strFromInt64 (strhandle out, int64 i, uint16 base)
bool	strFromUInt64 (strhandle out, uint64 i, uint16 base)
bool	strToFloat32 (float32 *out, strref s, flags_t flags)
bool	strToFloat64 (float64 *out, strref s, flags_t flags)
bool	strFromFloat32 (strhandle out, float32 f)
bool	strFromFloat64 (strhandle out, float64 f)

Detailed Description

Functions for converting between strings and numeric values. Both integer and floating-point conversions are supported.

Integer parsing

Integer parsing supports bases 2-36. Unlike standard C library functions, a leading '0' does NOT imply octal (base 8) - base 10 is always the default unless explicitly specified or the string begins with "0x" for hexadecimal.

Parsing flags

Every string-to-number function takes a flags parameter built from STRNUM_FLAGS. Passing 0 is the most permissive setting: leading whitespace is skipped, a sign is accepted, a "0x" prefix is honored, and anything after the number is ignored. Each flag only ever tightens that, so a call site reads as a list of what is not allowed:

uint64 len;
// no trailing junk, no leading spaces, no "0x" - exactly the digits and nothing else
strToUInt64(&len, s, 10, STRNUM_NoTrailing | STRNUM_NoWS | STRNUM_NoPrefix);

Floating-point conversion

Float-to-string conversion uses the Grisu2 algorithm for efficient and accurate representation. The output format is chosen automatically (plain, decimal, or scientific notation) based on the magnitude of the value.

Error handling

Conversion functions return false on error and set cxerr:

• CX_InvalidArgument - Invalid input format or base
• CX_Range - Value exceeds the range of the target type

Enumeration Type Documentation

STRNUM_FLAGS

enum STRNUM_FLAGS

Flags controlling how strictly a string is parsed as a number.

All of these are restrictions, so 0 is the most permissive setting and every flag only ever tightens what is accepted.

Enumerator
STRNUM_NoTrailing	Reject anything following the number.
STRNUM_NoWS	Do not skip leading whitespace.
STRNUM_NoPrefix	Do not accept a "0x" base prefix.
STRNUM_NoSign	Reject a leading '+' or '-'.

Definition at line 52 of file strnum.h.

Function Documentation

strFromFloat32()

bool strFromFloat32	(	strhandle	out,
		float32	f
	)

Converts a 32-bit floating-point value to a string

Formats the float using the Grisu2 algorithm for efficient and accurate conversion. The output format (plain decimal, scientific notation) is chosen automatically based on the magnitude. Special values are rendered as "inf", "-inf", or "nan".

Parameters

out	Output string (existing content destroyed)
f	Float value to convert

Returns

true on success, false on error

Example:

string s = 0;
strFromFloat32(&s, 3.14f);     // "3.14"
strFromFloat32(&s, 1.5e10f);   // "1.5e+10"
strFromFloat32(&s, 0.0f);      // "0"
strDestroy(&s);

strFromFloat64()

bool strFromFloat64	(	strhandle	out,
		float64	f
	)

Converts a 64-bit floating-point value to a string

Like strFromFloat32(), but for double-precision values. Uses Grisu2 algorithm for accurate conversion with automatic format selection.

Parameters

out	Output string (existing content destroyed)
f	Double value to convert

Returns

true on success, false on error

Example:

string s = 0;
strFromFloat64(&s, 3.141592653589793);  // "3.141592653589793"
strFromFloat64(&s, 2.5e-10);            // "2.5e-10"
strDestroy(&s);

strFromInt32()

bool strFromInt32	(	strhandle	out,
		int32	i,
		uint16	base
	)

Converts a 32-bit signed integer to a string

Formats the integer in the specified base. Negative values are prefixed with '-'. For bases > 10, lowercase letters are used (a-z).

Parameters

out	Output string (existing content destroyed)
i	Integer value to convert
base	Numeric base (2-36), typically 10 or 16

Returns

true on success, false on error

Example:

string s = 0;
strFromInt32(&s, 123, 10);    // "123"
strFromInt32(&s, -42, 10);    // "-42"
strFromInt32(&s, 255, 16);    // "ff"
strDestroy(&s);

strFromInt64()

bool strFromInt64	(	strhandle	out,
		int64	i,
		uint16	base
	)

Converts a 64-bit signed integer to a string

Like strFromInt32(), but for 64-bit values.

Parameters

out	Output string (existing content destroyed)
i	Integer value to convert
base	Numeric base (2-36), typically 10 or 16

Returns

true on success, false on error

strFromUInt32()

bool strFromUInt32	(	strhandle	out,
		uint32	i,
		uint16	base
	)

Converts a 32-bit unsigned integer to a string

Formats the integer in the specified base. For bases > 10, lowercase letters are used (a-z).

Parameters

out	Output string (existing content destroyed)
i	Integer value to convert
base	Numeric base (2-36), typically 10 or 16

Returns

true on success, false on error

Example:

string s = 0;
strFromUInt32(&s, 255, 10);   // "255"
strFromUInt32(&s, 255, 16);   // "ff"
strDestroy(&s);

strFromUInt64()

bool strFromUInt64	(	strhandle	out,
		uint64	i,
		uint16	base
	)

Converts a 64-bit unsigned integer to a string

Like strFromUInt32(), but for 64-bit values.

Parameters

out	Output string (existing content destroyed)
i	Integer value to convert
base	Numeric base (2-36), typically 10 or 16

Returns

true on success, false on error

strToFloat32()

bool strToFloat32	(	float32 *	out,
		strref	s,
		flags_t	flags
	)

Converts a string to a 32-bit floating-point value

Parses a string as a single-precision float. Supports standard decimal notation, scientific notation (e.g., "1.23e-4"), and special values ("inf", "nan"). Leading whitespace is skipped unless STRNUM_NoWS is set.

STRNUM_NoPrefix rejects a hexadecimal float such as "0x1p3".

Parameters

out	Pointer to receive the parsed value
s	String to parse
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format)

Example:

float32 value;
strToFloat32(&value, _SL("3.14"), STRNUM_NoTrailing);       // value = 3.14
strToFloat32(&value, _SL("-1.5e2"), STRNUM_NoTrailing);     // value = -150.0
strToFloat32(&value, _SL("inf"), STRNUM_NoTrailing);        // value = infinity

strToFloat64()

bool strToFloat64	(	float64 *	out,
		strref	s,
		flags_t	flags
	)

Converts a string to a 64-bit floating-point value

Like strToFloat32(), but parses as double-precision. Supports decimal notation, scientific notation, and special values.

Parameters

out	Pointer to receive the parsed value
s	String to parse
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format)

Example:

float64 value;
strToFloat64(&value, _SL("3.141592653589793"), STRNUM_NoTrailing);
strToFloat64(&value, _SL("2.5e-10"), STRNUM_NoTrailing);

strToInt32()

bool strToInt32	(	int32 *	out,
		strref	s,
		int	base,
		flags_t	flags
	)

Converts a string to a 32-bit signed integer

Parses a string as a signed integer in the specified base. By default leading whitespace is skipped, an optional '+' or '-' sign is recognized, a "0x" or "0X" prefix selects hexadecimal, and trailing characters are ignored. Pass STRNUM_FLAGS values to disallow any of those.

Unlike strtol(), a leading '0' does NOT imply octal - base 10 is the default.

Parameters

out	Pointer to receive the parsed value
s	String to parse
base	Numeric base (2-36), or 0 for auto-detect (10 or 16)
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format or out of range)

Example:

int32 value;
strToInt32(&value, _SL("123"), 10, STRNUM_NoTrailing);       // value = 123
strToInt32(&value, _SL("-42"), 10, STRNUM_NoTrailing);       // value = -42
strToInt32(&value, _SL("0xFF"), 0, STRNUM_NoTrailing);       // value = 255
strToInt32(&value, _SL("123abc"), 10, 0);                    // value = 123, ok
strToInt32(&value, _SL("123abc"), 10, STRNUM_NoTrailing);    // false

strToInt64()

bool strToInt64	(	int64 *	out,
		strref	s,
		int	base,
		flags_t	flags
	)

Converts a string to a 64-bit signed integer

Like strToInt32(), but for 64-bit values.

Parameters

out	Pointer to receive the parsed value
s	String to parse
base	Numeric base (2-36), or 0 for auto-detect (10 or 16)
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format or out of range)

strToUInt32()

bool strToUInt32	(	uint32 *	out,
		strref	s,
		int	base,
		flags_t	flags
	)

Converts a string to a 32-bit unsigned integer

Like strToInt32(), but parses as an unsigned value. A leading '-' sign is allowed (unless STRNUM_NoSign is set) and results in two's complement representation of the negative value.

Parameters

out	Pointer to receive the parsed value
s	String to parse
base	Numeric base (2-36), or 0 for auto-detect (10 or 16)
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format or out of range)

Example:

uint32 value;
strToUInt32(&value, _SL("255"), 10, STRNUM_NoTrailing);      // value = 255
strToUInt32(&value, _SL("0xFF"), 0, STRNUM_NoTrailing);      // value = 255

strToUInt64()

bool strToUInt64	(	uint64 *	out,
		strref	s,
		int	base,
		flags_t	flags
	)

Converts a string to a 64-bit unsigned integer

Like strToUInt32(), but for 64-bit values.

Parameters

out	Pointer to receive the parsed value
s	String to parse
base	Numeric base (2-36), or 0 for auto-detect (10 or 16)
flags	Combination of STRNUM_FLAGS, or 0 to accept everything

Returns

true on success, false on error (invalid format or out of range)