package core:fmt

Overview

package fmt implemented formatted I/O with procedures similar to C's printf and Python's format. The format 'verbs' are derived from C's but simpler.

Printing

The verbs:

General:

%v     the value in a default format
%#v    an expanded format of %v with newlines and indentation
%T     an Odin-syntax representation of the type of the value
%%     a literal percent sign; consumes no value
{{     a literal open brace; consumes no value
}}     a literal close brace; consumes no value
{:v}   equivalent to %v (Python-like formatting syntax)

Boolean:

%t    the word "true" or "false"

Integer:

%b    base 2
%c    the character represented by the corresponding Unicode code point
%r    synonym for %c
%o    base 8
%d    base 10
%i    base 10
%z    base 12
%x    base 16, with lower-case letters for a-f
%X    base 16, with upper-case letters for A-F
%U    Unicode format: U+1234; same as "U+%04X"

Floating-point, complex numbers, and quaternions:

%e    scientific notation, e.g. -1.23456e+78
%E    scientific notation, e.g. -1.23456E+78
%f    decimal point but no exponent, e.g. 123.456
%F    synonym for %f
%h    hexadecimal (lower-case) representation with 0h prefix (0h01234abcd)
%H    hexadecimal (upper-case) representation with 0H prefix (0h01234ABCD)

String and slice of bytes

%s    the uninterpreted bytes of the string or slice
%q    a double-quoted string safely escaped with Odin syntax
%x    base 16, lower-case, two characters per byte
%X    base 16, upper-case, two characters per byte

Slice and dynamic array:

%p    address of the 0th element in base 16 notation (upper-case), with leading 0x

Pointer:

%p    base 16 notation (upper-case), with leading 0x
The %b, %d, %o, %z, %x, %X verbs also work with pointers,
treating it as if it was an integer

Enums:

%s    prints the name of the enum field
The %i, %d, %f verbs also work with enums,
treating it as if it was a number

For compound values, the elements are printed using these rules recursively; laid out like the following:

struct:            {name0 = field0, name1 = field1, ...}
array              [elem0, elem1, elem2, ...]
enumerated array   [key0 = elem0, key1 = elem1, key2 = elem2, ...]
maps:              map[key0 = value0, key1 = value1, ...]
bit sets           {key0 = elem0, key1 = elem1, ...}
pointer to above:  &{}, &[], &map[]

Width is specified by an optional decimal number immediately preceding the verb. If not present, the width is whatever is necessary to represent the value. Precision is specified after the (optional) width followed by a period followed by a decimal number. If no period is present, a default precision is used. A period with no following number specifies a precision of 0.

Examples:

%f     default width, default precision
%8f    width 8, default precision
%.3f   default width, precision 2
%8.3f  width 8, precision 3
%8.f   width 8, precision 0

Width and precision are measured in units of Unicode code points (runes). n.b. C's printf uses units of bytes

Other flags:

+      always print a sign for numeric values
-      pad with spaces on the right rather the left (left-justify the field)
#      alternate format:
               add leading 0b for binary (%#b)
               add leading 0o for octal (%#o)
               add leading 0z for dozenal (%#z)
               add leading 0x or 0X for hexadecimal (%#x or %#X)
               remove leading 0x for %p (%#p)
' '    (space) leave a space for elided sign in numbers (% d)
0      pad with leading zeros rather than spaces


Flags are ignored by verbs that don't expect them

For each printf-like procedure, there is a print function that takes no format, and is equivalent to doing %v for every value and inserts a separator between each value (default is a single space). Another procedure println which has the same functionality as print but appends a newline.

Explicit argument indices:

In printf-like procedures, the default behaviour is for each formatting verb to format successive arguments passed in the call. However, the notation [n] immediately before the verb indicates that the nth zero-index argument is to be formatted instead. The same notation before an '*' for a width or precision selecting the argument index holding the value. Python-like syntax with argument indices differs for the selecting the argument index: {N:v}

Examples:

fmt.printf("%[1]d %[0]d\n", 13, 37); // C-like syntax
fmt.printf("{1:d} {0:d}\n", 13, 37); // Python-like syntax

prints "37 13", whilst:

fmt.printf("%[2]*.[1]*[0]f\n",  17.0, 2, 6); // C-like syntax
fmt.printf("%{0:[2]*.[1]*f}\n", 17.0, 2, 6); // Python-like syntax

equivalent to:

fmt.printf("%6.2f\n",   17.0, 2, 6); // C-like syntax
fmt.printf("{:6.2f}\n", 17.0, 2, 6); // Python-like syntax

prints "17.00"

Format errors:

If an invalid argument is given for a verb, such as providing a string to %d, the generated string will contain a description of the problem. For example:

Bad enum value:
	%!(BAD ENUM VALUE)
Too many arguments:
	%!(EXTRA , , ...)
Too few arguments:
	%!(MISSING ARGUMENT)
Invalid width or precision
	%!(BAD WIDTH)
	%!(BAD PRECISION)
Missing verb:
	%!(NO VERB)
Invalid or invalid use of argument index:
	%!(BAD ARGUMENT NUMBER)
Missing close brace when using Python-like formatting syntax:
	%!(MISSING CLOSE BRACE)

Types

Info ¶

Info :: struct {
	minus:                  bool,
	plus:                   bool,
	space:                  bool,
	zero:                   bool,
	hash:                   bool,
	width_set:              bool,
	prec_set:               bool,
	width:                  int,
	prec:                   int,
	indent:                 int,
	reordered:              bool,
	good_arg_index:         bool,
	ignore_user_formatters: bool,
	in_bad:                 bool,
	writer:                 io.Writer,
	arg:                    any,
	// Temporary
	indirection_level:      int,
	record_level:           int,
	optional_len:           runtime.Maybe(int),
	use_nul_termination:    bool,
	n:                      int,
}
 

Internal data structure that stores the required information for formatted printing

Register_User_Formatter_Error ¶

Register_User_Formatter_Error :: enum int {
	None, 
	No_User_Formatter, 
	Formatter_Previously_Found, 
}

User_Formatter ¶

User_Formatter :: proc "odin" (fi: ^Info, arg: any, verb: rune) -> bool
 

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

Constants

This section is empty.

Variables

This section is empty.

Procedures

aprint ¶

aprint :: proc "odin" (args: ..any, sep: string = " ") -> string {…}
 

aprint procedure return a string that was allocated with the current context They must be freed accordingly

aprintf ¶

aprintf :: proc "odin" (fmt: string, args: ..any) -> string {…}
 

aprintf procedure return a string that was allocated with the current context They must be freed accordingly

aprintln ¶

aprintln :: proc "odin" (args: ..any, sep: string = " ") -> string {…}
 

aprintln procedure return a string that was allocated with the current context They must be freed accordingly

assertf ¶

assertf :: proc "odin" (condition: bool, fmt: string, args: ..any, loc := #caller_location) -> bool {…}
 

formatted assert

bprint ¶

bprint :: proc "odin" (buf: []u8, args: ..any, sep: string = " ") -> string {…}
 

bprint procedures return a string using a buffer from an array

bprintf ¶

bprintf :: proc "odin" (buf: []u8, fmt: string, args: ..any) -> string {…}
 

bprintf procedures return a string using a buffer from an array

bprintln ¶

bprintln :: proc "odin" (buf: []u8, args: ..any, sep: string = " ") -> string {…}
 

bprintln procedures return a string using a buffer from an array

enum_value_to_string ¶

enum_value_to_string :: proc "odin" (val: any) -> (string, bool) {…}

eprint ¶

eprint :: proc "odin" (args: ..any, sep: string = " ") -> int {…}
 

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

eprintf ¶

eprintf :: proc "odin" (fmt: string, args: ..any) -> int {…}
 

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

eprintln ¶

eprintln :: proc "odin" (args: ..any, sep: string = " ") -> int {…}
 

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

fmt_arg ¶

fmt_arg :: proc "odin" (fi: ^Info, v: any, verb: rune) {…}

fmt_array ¶

fmt_array :: proc "odin" (
	fi:        ^Info, 
	data:      rawptr, 
	max_n:     int, 
	elem_size: int, 
	elem:      ^runtime.Type_Info, 
) {…}

fmt_array_nul_terminated ¶

fmt_array_nul_terminated :: proc "odin" (
	fi:        ^Info, 
	data:      rawptr, 
	max_n:     int, 
	elem_size: int, 
	elem:      ^runtime.Type_Info, 
) {…}

fmt_bad_verb ¶

fmt_bad_verb :: proc "odin" (using fi: ^Info, verb: rune) {…}

fmt_bit_set ¶

fmt_bit_set :: proc "odin" (fi: ^Info, v: any, name: string = "") {…}

fmt_bool ¶

fmt_bool :: proc "odin" (using fi: ^Info, b: bool, verb: rune) {…}

fmt_complex ¶

fmt_complex :: proc "odin" (fi: ^Info, c: complex128, bits: int, verb: rune) {…}

fmt_cstring ¶

fmt_cstring :: proc "odin" (fi: ^Info, s: cstring, verb: rune) {…}

fmt_enum ¶

fmt_enum :: proc "odin" (fi: ^Info, v: any, verb: rune) {…}

fmt_float ¶

fmt_float :: proc "odin" (fi: ^Info, v: f64, bit_size: int, verb: rune) {…}

fmt_int ¶

fmt_int :: proc "odin" (fi: ^Info, u: u64, is_signed: bool, bit_size: int, verb: rune) {…}

fmt_int_128 ¶

fmt_int_128 :: proc "odin" (fi: ^Info, u: u128, is_signed: bool, bit_size: int, verb: rune) {…}

fmt_matrix ¶

fmt_matrix :: proc "odin" (fi: ^Info, v: any, verb: rune, info: runtime.Type_Info_Matrix) {…}

fmt_named ¶

fmt_named :: proc "odin" (fi: ^Info, v: any, verb: rune, info: runtime.Type_Info_Named) {…}

fmt_pointer ¶

fmt_pointer :: proc "odin" (fi: ^Info, p: rawptr, verb: rune) {…}

fmt_quaternion ¶

fmt_quaternion :: proc "odin" (fi: ^Info, q: quaternion256, bits: int, verb: rune) {…}

fmt_rune ¶

fmt_rune :: proc "odin" (fi: ^Info, r: rune, verb: rune) {…}

fmt_soa_pointer ¶

fmt_soa_pointer :: proc "odin" (fi: ^Info, p: runtime.Raw_Soa_Pointer, verb: rune) {…}

fmt_string ¶

fmt_string :: proc "odin" (fi: ^Info, s: string, verb: rune) {…}

fmt_struct ¶

fmt_struct :: proc "odin" (fi: ^Info, v: any, the_verb: rune, info: runtime.Type_Info_Struct, type_name: string) {…}

fmt_union ¶

fmt_union :: proc "odin" (fi: ^Info, v: any, verb: rune, info: runtime.Type_Info_Union, type_size: int) {…}

fmt_value ¶

fmt_value :: proc "odin" (fi: ^Info, v: any, verb: rune) {…}

fmt_write_array ¶

fmt_write_array :: proc "odin" (
	fi:         ^Info, 
	array_data: rawptr, 
	count:      int, 
	elem_size:  int, 
	elem_id:    typeid, 
) {…}

fmt_write_indent ¶

fmt_write_indent :: proc "odin" (fi: ^Info) {…}

fmt_write_padding ¶

fmt_write_padding :: proc "odin" (fi: ^Info, width: int) {…}

fprint ¶

fprint :: proc "odin" (fd: os.Handle, args: ..any, sep: string = " ") -> int {…}
 

fprint formats using the default print settings and writes to fd

fprint_type ¶

fprint_type :: proc "odin" (fd: os.Handle, info: ^runtime.Type_Info) -> (n: int, err: io.Error) {…}

fprint_typeid ¶

fprint_typeid :: proc "odin" (fd: os.Handle, id: typeid) -> (n: int, err: io.Error) {…}

fprintf ¶

fprintf :: proc "odin" (fd: os.Handle, fmt: string, args: ..any) -> int {…}
 

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

fprintln ¶

fprintln :: proc "odin" (fd: os.Handle, args: ..any, sep: string = " ") -> int {…}
 

fprintln formats using the default print settings and writes to fd

int_from_arg ¶

int_from_arg :: proc "odin" (args: []any, arg_index: int) -> (int, int, bool) {…}

panicf ¶

panicf :: proc "odin" (fmt: string, args: ..any, loc := #caller_location) -> ! {…}
 

formatted panic

print ¶

print :: proc "odin" (args: ..any, sep: string = " ") -> int {…}
 

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

printf ¶

printf :: proc "odin" (fmt: string, args: ..any) -> int {…}
 

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

println ¶

println :: proc "odin" (args: ..any, sep: string = " ") -> int {…}
 

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

register_user_formatter ¶

register_user_formatter :: proc "odin" (id: typeid, formatter: User_Formatter) -> Register_User_Formatter_Error {…}
 

register_user_formatter assigns a formatter to a specific typeid. set_user_formatters must be called before any use of this procedure.

sbprint ¶

sbprint :: proc "odin" (buf: ^strings.Builder, args: ..any, sep: string = " ") -> string {…}
 

sbprint formats using the default print settings and writes to buf

sbprintf ¶

sbprintf :: proc "odin" (buf: ^strings.Builder, fmt: string, args: ..any) -> string {…}
 

sbprintf formats according to the specififed format string and writes to buf

sbprintln ¶

sbprintln :: proc "odin" (buf: ^strings.Builder, args: ..any, sep: string = " ") -> string {…}
 

sbprintln formats using the default print settings and writes to buf

set_user_formatters ¶

set_user_formatters :: proc "odin" (m: ^map[typeid]User_Formatter) {…}
 

set_user_formatters assigns m to a global value allowing the user have custom print formatting for specific types

stored_enum_value_to_string ¶

stored_enum_value_to_string :: proc "odin" (enum_type: ^runtime.Type_Info, ev: runtime.Type_Info_Enum_Value, offset: int = 0) -> (string, bool) {…}

string_to_enum_value ¶

string_to_enum_value :: proc "odin" ($T: typeid, s: string) -> (typeid, bool) {…}

tprint ¶

tprint :: proc "odin" (args: ..any, sep: string = " ") -> string {…}
 

tprint procedure return a string that was allocated with the current context's temporary allocator

tprintf ¶

tprintf :: proc "odin" (fmt: string, args: ..any) -> string {…}
 

tprintf procedure return a string that was allocated with the current context's temporary allocator

tprintln ¶

tprintln :: proc "odin" (args: ..any, sep: string = " ") -> string {…}
 

tprintln procedure return a string that was allocated with the current context's temporary allocator

wprint ¶

wprint :: proc "odin" (w: io.Writer, args: ..any, sep: string = " ") -> int {…}
 

wprint formats using the default print settings and writes to w

wprint_type ¶

wprint_type :: proc "odin" (w: io.Writer, info: ^runtime.Type_Info) -> (int, io.Error) {…}
 

wprint_type is a utility procedure to write a ^runtime.Type_Info value to w

wprint_typeid ¶

wprint_typeid :: proc "odin" (w: io.Writer, id: typeid) -> (int, io.Error) {…}
 

wprint_typeid is a utility procedure to write a typeid value to w

wprintf ¶

wprintf :: proc "odin" (w: io.Writer, fmt: string, args: ..any) -> int {…}
 

wprintf formats according to the specififed format string and writes to w

wprintln ¶

wprintln :: proc "odin" (w: io.Writer, args: ..any, sep: string = " ") -> int {…}
 

wprintln formats using the default print settings and writes to w

Procedure Groups

This section is empty.

Source Files

Generation Information

Generated with odin version dev-2022-10 (vendor "odin") Windows_amd64 @ 2022-10-05 21:11:47.320548600 +0000 UTC