fmt

Internal data structure that stores the required information for formatted printing

Example User Formatter: SomeType :: struct {

value: int,
}
// Custom Formatter for SomeType
User_Formatter :: proc(fi: ^fmt.Info, arg: any, verb: rune) -> bool {
	m := cast(^SomeType)arg.data
	switch verb {
	case 'v', 'd':
		fmt.fmt_int(fi, u64(m.value), true, 8 * size_of(SomeType), verb)
	case:
		return false
	}
	return true
}
main :: proc() {
	// Ensure the fmt._user_formatters map is initialized
	fmt.set_user_formatters(new(map[typeid]fmt.User_Formatter))
	err := fmt.register_user_formatter(type_info_of(SomeType).id, User_Formatter)
	assert(err == .None)
	// Use the custom formatter
	x := SomeType{42}
	fmt.println("Custom type value: ", x)
}

Custom formatter signature. It returns true if the formatting was successful and false when it could not be done

Hex Values:

Units of measurements:

NOTE(bill): This is a pointer to prevent accidental additions it is prefixed with _ rather than marked with a private attribute so that users can access it if necessary

Parses an argument number from a format string and determines if it's valid

Inputs:

• format: The format string to parse
• offset: A pointer to the current position in the format string
• arg_count: The total number of arguments

Returns:

• index: The parsed argument index
• parsed: A boolean indicating if an argument number was parsed
• ok: A boolean indicating if the parsed argument number is within arg_count

Formats a floating-point number with a specific format and precision.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• v: The floating-point number to format.
• bit_size: The size of the floating-point number in bits (16, 32, or 64).
• verb: The format specifier character.
• float_fmt: The byte format used for formatting the float (either 'f' or 'e').

NOTE: Can return "NaN", "+Inf", "-Inf", "+<value>", or "-<value>".

Formats an integer value with specified base, sign, bit size, and digits

Inputs:

• fi: A pointer to an Info structure
• u: The integer value to format
• base: The base for integer formatting
• is_signed: A boolean indicating if the integer is signed
• bit_size: The bit size of the integer
• digits: A string containing the digits for formatting

WARNING: May panic if the width and precision are too big, causing a buffer overrun

Formats an int128 value based on the provided formatting options.

Inputs:

• fi: A pointer to the Info struct containing formatting options.
• u: The int128 value to be formatted.
• base: The base to be used for formatting the integer (e.g. 2, 8, 10, 12, 16).
• is_signed: Whether the value should be treated as signed or unsigned.
• bit_size: The number of bits of the value (e.g. 64, 128).
• digits: A string containing the digit characters to use for the formatted integer.

WARNING: Panics if the formatting options result in a buffer overrun.

Formats an integer value as bytes with the best representation.

Inputs:

• fi: A pointer to an Info structure
• u: The integer value to format
• is_signed: A boolean indicating if the integer is signed
• bit_size: The bit size of the integer
• digits: A string containing the digits for formatting

Pads a formatted string with the appropriate padding, based on the provided formatting options.

Inputs:

• fi: A pointer to the Info struct containing formatting options.
• s: The string to be padded.

Parses an integer from a given string starting at a specified offset

Inputs:

• s: The string to parse the integer from
• offset: The position in the string to start parsing the integer

Returns:

• result: The parsed integer
• new_offset: The position in the string after parsing the integer
• ok: A boolean indicating if the parsing was successful

Creates a formatted string

Allocates Using Provided Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).
• allocator: (default: context.allocator)

Returns: A formatted string.

Creates a formatted string using a format string and arguments

Allocates Using Provided Allocator

Inputs:

• fmt: A format string with placeholders for the provided arguments.
• args: A variadic list of arguments to be formatted.
• allocator: (default: context.allocator)
• newline: Whether the string should end with a newline. (See aprintfln.)

Returns: A formatted string. The returned string must be freed accordingly.

Creates a formatted string using a format string and arguments, followed by a newline.

Allocates Using Provided Allocator

Inputs:

• fmt: A format string with placeholders for the provided arguments.
• args: A variadic list of arguments to be formatted.
• allocator: (default: context.allocator)

Returns: A formatted string. The returned string must be freed accordingly.

Creates a formatted string with a newline character at the end

Allocates Using Provided Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).
• allocator: (default: context.allocator)

Returns: A formatted string with a newline character at the end.

Runtime assertion with a formatted message

Inputs:

• condition: The boolean condition to be asserted
• fmt: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• loc: The location of the caller

Creates a formatted string using a supplied buffer as the backing array. Writes into the buffer.

Inputs:

• buf: The backing buffer
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: A formatted string

Creates a formatted string using a supplied buffer as the backing array. Writes into the buffer.

Inputs:

• buf: The backing buffer
• fmt: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• newline: Whether the string should end with a newline. (See bprintfln.)

Returns: A formatted string

Creates a formatted string using a supplied buffer as the backing array, followed by a newline. Writes into the buffer.

Inputs:

• buf: The backing buffer
• fmt: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted

Returns: A formatted string

Creates a formatted string using a supplied buffer as the backing array, appends newline. Writes into the buffer.

Inputs:

• buf: The backing buffer
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: A formatted string with a newline character at the end

Creates a formatted C string

Allocates Using Provided Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).
• allocator: (default: context.allocator)

Returns: A formatted C string.

Creates a formatted C string

Allocates Using Provided Allocator

Inputs:

• format: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• allocator: (default: context.allocator)
• newline: Whether the string should end with a newline. (See caprintfln.)

Returns: A formatted C string

Creates a formatted C string, followed by a newline.

Allocates Using Provided Allocator

Inputs:

• format: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• allocator: (default: context.allocator)

Returns: A formatted C string

Creates a formatted C string

Allocates Using Context's Temporary Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).

Returns: A formatted C string.

Creates a formatted C string

Allocates Using Context's Temporary Allocator

Inputs:

• format: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• newline: Whether the string should end with a newline. (See ctprintfln.)

Returns: A formatted C string

Creates a formatted C string, followed by a newline.

Allocates Using Context's Temporary Allocator

Inputs:

• format: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted

Returns: A formatted C string

Runtime ensure with a formatted message

Inputs:

• condition: The boolean condition to be asserted
• fmt: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• loc: The location of the caller

String representation of an enum value.

Inputs:

• val: The enum value.

Returns: The string representation of the enum value and a boolean indicating success.

eprint formats using the default print settings and writes to os.stderr

eprintf formats according to the specified format string and writes to os.stderr

eprintfln formats according to the specified format string and writes to os.stderr, followed by a newline.

eprintln formats using the default print settings and writes to os.stderr

Formats an argument based on its type and the given formatting verb

Inputs:

• fi: A pointer to an Info struct containing formatting information.
• arg: The value to be formatted.
• verb: The formatting verb rune (e.g. 'T').

NOTE: Uses user formatters if available and not ignored.

Formats an array into a string representation

Inputs:

• fi: Pointer to the formatting Info struct.
• data: The raw pointer to the array data.
• n: The number of elements in the array.
• elem_size: The size of each element in the array.
• elem: Pointer to the type information of the array element.
• verb: The formatting verb (e.g. 's','q','p','w').

Formats a NUL-terminated array into a string representation

Inputs:

• fi: Pointer to the formatting Info struct.
• data: The raw pointer to the array data.
• max_n: The maximum number of elements to process.
• elem_size: The size of each element in the array.
• elem: Pointer to the type information of the array element.
• verb: The formatting verb.

Writes a bad verb error message

Inputs:

• fi: A pointer to an Info structure
• verb: The invalid format verb

Formats a bit set and writes it to the provided Info structure

Inputs:

• fi: A pointer to the Info structure where the formatted bit set will be written.
• v: The bit set value to be formatted.
• name: An optional string for the name of the bit set (default is an empty string).
• verb: An optional verb to adjust format.

Formats a boolean value according to the specified format verb

Inputs:

• fi: A pointer to an Info structure
• b: The boolean value to format
• verb: The format verb

Formats a complex number based on the given formatting verb

Inputs:

• fi: A pointer to an Info struct containing formatting information.
• c: The complex128 value to be formatted.
• bits: The number of bits in the complex number (32 or 64).
• verb: The formatting verb rune ('f', 'F', 'v', 'h', 'H', 'w').

Formats a C-style string with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• s: The C-style string to format.
• verb: The format specifier character (Ref fmt_string).

Formats a C-style UTF-16 string with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• s: The C-style string to format.
• verb: The format specifier character (Ref fmt_string).

Formats an enum value with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• v: The enum value to format.
• verb: The format specifier character (e.g. 'i','d','f','s','v','q','w').

Formats a floating-point number with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• v: The floating-point number to format.
• bit_size: The size of the floating-point number in bits (16, 32, or 64).
• verb: The format specifier character.

Formats an integer value according to the specified formatting verb.

Inputs:

• fi: A pointer to the Info struct containing formatting options.
• u: The integer value to be formatted.
• is_signed: Whether the value should be treated as signed or unsigned.
• bit_size: The number of bits of the value (e.g. 32, 64).
• verb: The formatting verb to use (e.g. 'v', 'b', 'o', 'i', 'd', 'z', 'x', 'X', 'c', 'r', 'U').

Formats an int128 value according to the specified formatting verb.

Inputs:

• fi: A pointer to the Info struct containing formatting options.
• u: The int128 value to be formatted.
• is_signed: Whether the value should be treated as signed or unsigned.
• bit_size: The number of bits of the value (e.g. 64, 128).
• verb: The formatting verb to use (e.g. 'v', 'b', 'o', 'i', 'd', 'z', 'x', 'X', 'c', 'r', 'U').

Formats a matrix as a string

Inputs:

• fi: A pointer to an Info struct containing formatting information.
• v: The matrix value to be formatted.
• verb: The formatting verb rune.
• info: A runtime.Type_Info_Matrix struct containing matrix type information.

Formats a named type into a string representation

Inputs:

• fi: Pointer to the formatting Info struct.
• v: The value to format.
• verb: The formatting verb.
• info: The named type information.

NOTE: This procedure supports built-in custom formatters for core library types such as runtime.Source_Code_Location, time.Duration, and time.Time.

Formats a raw pointer with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• p: The raw pointer to format.
• verb: The format specifier character (e.g. 'p', 'v', 'b', 'o', 'i', 'd', 'z', 'x', 'X').

Formats a quaternion number based on the given formatting verb

Inputs:

• fi: A pointer to an Info struct containing formatting information.
• q: The quaternion256 value to be formatted.
• bits: The number of bits in the quaternion number (64, 128, or 256).
• verb: The formatting verb rune ('f', 'F', 'v', 'h', 'H', 'w').

Formats a rune value according to the specified formatting verb.

Inputs:

• fi: A pointer to the Info struct containing formatting options.
• r: The rune value to be formatted.
• verb: The formatting verb to use (e.g. 'c', 'r', 'v', 'q').

Formats a Structure of Arrays (SoA) pointer with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• p: The SoA pointer to format.
• verb: The format specifier character.

Formats a string with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• s: The string to format.
• verb: The format specifier character (e.g. 's', 'v', 'q', 'x', 'X').

Formats a string UTF-16 with a specific format.

Inputs:

• fi: Pointer to the Info struct containing format settings.
• s: The string to format.
• verb: The format specifier character (e.g. 's', 'v', 'q', 'x', 'X').

Formats a struct for output, handling various struct types (e.g., SOA, raw unions)

Inputs:

• fi: A mutable pointer to an Info struct containing formatting state
• v: The value to be formatted
• the_verb: The formatting verb to be used (e.g. 'v')
• info: Type information about the struct
• type_name: The name of the type being formatted

Formats a union type into a string representation

Inputs:

• fi: Pointer to the formatting Info struct.
• v: The value to format.
• verb: The formatting verb.
• info: The union type information.
• type_size: The size of the union type.

Formats a value based on its type and formatting verb

Inputs:

• fi: A pointer to an Info struct containing formatting information.
• v: The value to be formatted.
• verb: The formatting verb rune.

NOTE: Uses user formatters if available and not ignored.

Formats an array and writes it to the provided Info structure

Inputs:

• fi: A pointer to the Info structure where the formatted array will be written.
• array_data: A raw pointer to the array data.
• count: The number of elements in the array.
• elem_size: The size of each element in the array.
• elem_id: The typeid of the array elements.
• verb: The formatting verb to be used for the array elements.

Writes the specified number of indents to the provided Info structure

Inputs:

• fi: A pointer to the Info structure where the indents will be written.

Writes padding characters for formatting

Inputs:

• fi: A pointer to an Info structure
• width: The number of padding characters to write

NOTE(Jeroen): The other option is to deprecate fprint* and make it an alias for wprint*, using File.stream directly. fprint formats using the default print settings and writes to fd

fprintf formats according to the specified format string and writes to fd

fprintfln formats according to the specified format string and writes to fd, followed by a newline.

fprintln formats using the default print settings and writes to fd

Retrieves an integer from a list of any type at the specified index

Inputs:

• args: A list of values of any type
• arg_index: The index to retrieve the integer from

Returns:

• int: The integer value at the specified index
• new_arg_index: The new argument index
• ok: A boolean indicating if the conversion to integer was successful

Runtime panic with a formatted message

Inputs:

• fmt: A format string with placeholders for the provided arguments
• args: A variadic list of arguments to be formatted
• loc: The location of the caller

print formats using the default print settings and writes to os.stdout

printf formats according to the specified format string and writes to os.stdout

printfln formats according to the specified format string and writes to os.stdout, followed by a newline.

println formats using the default print settings and writes to os.stdout

Registers a user-defined formatter for a specific typeid

Inputs:

• id: The typeid of the custom type.
• formatter: The User_Formatter function for the custom type.

Returns: A Register_User_Formatter_Error value indicating the success or failure of the operation.

WARNING: set_user_formatters must be called before using this procedure.

Formats using the default print settings and writes to the given strings.Builder

Inputs:

• buf: A pointer to a strings.Builder to store the formatted string
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: A formatted string

Formats and writes to a strings.Builder buffer according to the specified format string

Inputs:

• buf: A pointer to a strings.Builder buffer
• fmt: The format string
• args: A variadic list of arguments to be formatted
• newline: Whether a trailing newline should be written. (See sbprintfln.)

Returns: The resulting formatted string

Formats and writes to a strings.Builder buffer according to the specified format string, followed by a newline.

Inputs:

• buf: A pointer to a strings.Builder to store the formatted string
• args: A variadic list of arguments to be formatted

Returns: A formatted string

Formats and writes to a strings.Builder buffer using the default print settings

Inputs:

• buf: A pointer to a strings.Builder buffer
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: The resulting formatted string

Sets user-defined formatters for custom print formatting of specific types

Inputs:

• m: A pointer to a map of typeids to User_Formatter structs.

NOTE: Must be called before using register_user_formatter.

Converts a stored enum value to a string representation

Inputs:

• enum_type: A pointer to the runtime.Type_Info of the enumeration.
• ev: The runtime.Type_Info_Enum_Value of the stored enum value.
• offset: An optional integer to adjust the enumeration value (default is 0).

Returns: A tuple containing the string representation of the enum value and a bool indicating success.

Returns the enum value of a string representation.

$T: The typeid of the enum type. Inputs:

• s: The string representation of the enum value.

Returns: The enum value and a boolean indicating success.

Creates a formatted string

Allocates Using Context's Temporary Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).

Returns: A formatted string.

Creates a formatted string using a format string and arguments

Allocates Using Context's Temporary Allocator

Inputs:

• fmt: A format string with placeholders for the provided arguments.
• args: A variadic list of arguments to be formatted.
• newline: Whether the string should end with a newline. (See tprintfln.)

Returns: A formatted string.

Creates a formatted string using a format string and arguments, followed by a newline.

Allocates Using Context's Temporary Allocator

Inputs:

• fmt: A format string with placeholders for the provided arguments.
• args: A variadic list of arguments to be formatted.

Returns: A formatted string.

Creates a formatted string with a newline character at the end

Allocates Using Context's Temporary Allocator

Inputs:

• args: A variadic list of arguments to be formatted.
• sep: An optional separator string (default is a single space).

Returns: A formatted string with a newline character at the end.

Formats and writes to an io.Writer using the default print settings

Inputs:

• w: An io.Writer to write to
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: The number of bytes written

Writes a ^runtime.Type_Info value to an io.Writer

Inputs:

• w: An io.Writer to write to
• info: A pointer to a runtime.Type_Info value

Returns: The number of bytes written and an io.Error if encountered

Writes a typeid value to an io.Writer

Inputs:

• w: An io.Writer to write to
• id: A typeid value

Returns: The number of bytes written and an io.Error if encountered

Formats and writes to an io.Writer according to the specified format string

Inputs:

• w: An io.Writer to write to
• fmt: The format string
• args: A variadic list of arguments to be formatted
• newline: Whether a trailing newline should be written. (See wprintfln.)

Returns: The number of bytes written

Formats and writes to an io.Writer according to the specified format string, followed by a newline.

Inputs:

• w: The io.Writer to write to.
• args: A variadic list of arguments to be formatted.

Returns: The number of bytes written.

Formats and writes to an io.Writer using the default print settings with a newline character at the end

Inputs:

• w: An io.Writer to write to
• args: A variadic list of arguments to be formatted
• sep: An optional separator string (default is a single space)

Returns: The number of bytes written