doc.gno

 1// Package ufmt is a preview of gno.land/p/nt/ufmt/v2, published here before
 2// that path exists.
 3//
 4// This is v2 of ufmt. It is not yet published at its expected path,
 5// gno.land/p/nt/ufmt/v2. Until it is, import it from
 6// gno.land/p/moul/vendor/nt/ufmt/v2; once gno.land/p/nt/ufmt/v2 is live,
 7// switch the import and nothing else, because the API is meant to be the same.
 8// This path is then frozen and never updated again.
 9//
10// v0 (gno.land/p/nt/ufmt/v0) supports a handful of verbs and no flags, so
11// "%08x", "%X" and "%-10s" print "(unhandled)" or drop their padding without a
12// word. v2 follows Go's fmt instead: the same flags, widths, precisions and
13// verbs, and the same error strings in place of panics. Where it cannot follow
14// Go, because gno has no reflect, it says so below.
15//
16// Supported, as in Go's fmt:
17//
18//	flags      '+' '-' '#' ' ' '0'
19//	width      %8d, %*d, and a negative * width left-justifies
20//	precision  %.2f, %.*f, %.3s (in runes)
21//	indexes    %[2]d %[1]s, %[1]*[2]d
22//	general    %v %+v %#v %T %%
23//	bool       %t
24//	integer    %b %c %d %o %O %q %x %X %U, every int and uint type
25//	float      %b %e %E %f %F %g %G %x %X, float32 and float64
26//	string     %s %q %x %X, and []byte the same way
27//	errors     %w in Errorf, unwrapped by errors.Unwrap and errors.Is
28//	methods    Formatter, GoStringer, error, Stringer, in Go's order
29//	composite  []T of the basic types, []any, []error, and map[string]T
30//	           with its keys sorted, as Go prints them
31//
32// Errors are written into the output, never panicked: "%!d(string=hi)" for a
33// wrong type, "%!d(MISSING)" for a missing argument, "%!(EXTRA int=1)" for an
34// unused one, "%!(NOVERB)" for a trailing '%'.
35//
36// What gno cannot do, and what v2 prints instead:
37//
38//   - no reflect, so a struct, a pointer, a named type without a String
39//     method, or a slice or map of anything other than the types listed above
40//     prints "(unhandled)", and %T names only the types it knows ("unknown"
41//     otherwise). Give the type a String method.
42//   - %p is not supported.
43//
44// What changed from v0, so a migration is a review and not a find-and-replace:
45//
46//   - Sprint adds a space only between two operands when neither is a string,
47//     as Go does; v0 put a space between every pair.
48//   - %v of a float, and Sprint of one, is the shortest representation ("3.14"),
49//     as Go does; v0 printed "%f" ("3.140000") from Sprint.
50//   - %e defaults to 6 digits after the point, as Go does; v0 used 2.
51//   - %v of a []byte prints "[104 105]", as Go does; v0 wrote the raw bytes.
52//     Use %s for the string.
53//   - a missing or extra argument, or a trailing '%', is written into the
54//     output instead of panicking.
55//   - an error is preferred to a String method when a value has both.
56package ufmt