Printing Values¶

All Idio values can be printed although not all have a valid reader input form. Those without valid reader forms are subject to change. The output generally takes the form #<TYPE ...>.

If you are unsure, use %s (“as a string”) as a generic catch-all format specifier. This “as a string” is used as default behaviour for unexpected format specifiers (and which may result in a warning). See below.

There is a subtle distinction between a value being printed – commonly at the REPL as generally suitable to be read back in – and being displayed as general output of the program.

This only affects unicode and string types where any escaping is removed and full UTF-8 encoding is used when displayed.

Warning

Very deep data structures are truncated.

Fixnums¶

Fixnums support the usual integer formats %[Xbdox] where %b is a binary format.

Any other format specifier is treated as %d.

Bignums¶

Bignums have limited printing support.

Integer bignums are printed as, effectively, %d.

Floating point bignums are printed as one of:

%s a normalized form
%e or %f in the style of printf(3)

Any other format specifier is treated as %e.

The output may be preceded by #i (or #e) indicating the underlying bignum is inexact (or exact).

Unicode¶

In general, unicode is printed as #U+HHHH although if the code point is below 128 and satisfies isgraph(3) it will be printed as #\c.

If unicode is being displayed Idio generates the UTF-8 encoding for the value.

Strings¶

Strings are printed double-quoted and with the usual C escape sequences escaped: a newline will be represented by \n, for example. Otherwise Unicode code points are encoded as UTF-8.

String are displayed unquoted and with all Unicode code points UTF-8 encoded.

Symbols¶

Symbols are displayed as just their name, without a leading '.

This creates some anomalies.

Pairs¶

Pairs are printed as expected.

If the list represents a template any original change to interpolation characters is lost and standard Idio symbols are used.

Arrays¶

Arrays are printed in the nominal reader form: #[ ... ].

If the array is less than 40 elements long it is printed in full.

Warning

If it is more than 40 elements long then the first 20 and the last 20 are printed with in ellipsis and missing index marker displayed.

Hash Tables¶

Hash tables are printed in the nominal reader form: #{ ... }.

Bitsets¶

Bitsets are printed in the nominal reader form: #B{ ... }.

C Types¶

C types are printed as:

%c for char
%d for signed integral types

Any other format specifier is treated as %d.

Any format specifier other than %s may elicit a warning.
%[Xboux] for unsigned integral types including the %b binary format

Any other format specifier is treated as %u.

Any other format specifier other than %s may elicit a warning.
%[efg] for floating point types

Any other format specifier is treated as %g.

Any other format specifier other than %s may elicit a warning.

C/pointer types have the option to be printed by a bespoke printer. See add-as-string.

Struct Instances¶

Struct instances have the option to be printed by a bespoke printer. See add-as-string.

Printing Functions¶

The printing functions revolve around %format which takes a printf(3)-style format string and constructs a formatted string from the arguments.

function printf fmt [args]¶

Invoke the hprintf function on the current output handle with fmt and args

Param fmt:: the format string for printf
Type fmt:: string
Param args:: any args for the format string
Type args:: list, optional
Return:: #<unspec>

function eprintf fmt [args]¶

Invoke the hprintf function on the current error handle with fmt and args

Param fmt:: the format string for printf
Type fmt:: string
Param args:: any args for the format string
Type args:: list, optional
Return:: #<unspec>

function sprintf fmt [args]¶

Invoke the hprintf function on an output string handle with fmt and args and return the resultant string

Param fmt:: the format string for printf
Type fmt:: string
Param args:: any args for the format string
Type args:: list, optional
Return:: string

function hprintf handle fmt [args]¶

Invoke the display function on handle with the result of applying format to fmt and args.

Param handle:: the handle to load from
Type handle:: handle
Param fmt:: the format string for printf
Type fmt:: string
Param args:: any args for the format string
Type args:: list, optional
Return:: #<unspec>

function format fmt [args]¶

Call %format:

%format 'args fmt args

function %format type fmt [args]¶

Return a string from the format string fmt expanded by any escape sequences.

If type is 'args then a % character in the format string starts an escape sequence which has the general form %[flags][width][.prec]K where K is a printf(3)-ish conversion specifier character with arguments in args.

If K is an @ character then the list argument is spliced into the string converting all elements of the list to string form separated by a U+0022 (SPACE) character.

If type is 'keyed then a % character in the format string starts an escape sequence which has the general form %[flags][width][.prec]K where K is a single Unicode code point (satisfying Alphabetic?) which is expected to be a key in the optional hash table – unless it is another % character. The value associated with the key will be printed according to the specification.

In both cases if K is a % character then a % is printed according to the specification

If type is 'timeformat then it works similarly to 'keyed except we avoid a double application of any precision. TIMEFORMAT describes a %f-like precision to the struct-timeval strings.

The flags are:

flag	effect	code point
`-`	left align the output within `width`	U+002D (HYPHEN-MINUS)
	use `#\{space}` as the left padding character	U+0020 (SPACE)
`0`	use `#\0` (zero) as the left padding character	U+0030 (DIGIT ZERO)

The default padding character is #\{space}