Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v2 source pure

Package ufmt is a preview of gno.land/p/nt/ufmt/v2, published here before that path exists.

Readme View source

p/moul/vendor/nt/ufmt (v2 preview)

This is ufmt v2, published here before its real path exists. The expected home is gno.land/p/nt/ufmt/v2, which is not published yet. Until it is, import:

1import "gno.land/p/moul/vendor/nt/ufmt/v2"

When gno.land/p/nt/ufmt/v2 goes live, change the import and nothing else. This path is then frozen: it keeps working, it never gets another fix.

Why

p/nt/ufmt/v0 knows a handful of verbs and no flags, and it fails quietly. Sprintf("0x%08X", pc) prints 0x(unhandled verb: %X), Sprintf("%08x", w) prints (unhandled), and Sprintf("%03d", 7) prints 7. r/moul/x/vm/riscvdemo shipped a register dump that was nothing but those.

v2 is Go's fmt, as far as gno can follow it:
flags + - # 0
width, precision %8d, %.2f, %*d, %.*f, %.3s in runes
argument indexes %[2]d %[1]s, %[1]*[2]d
integers %b %c %d %o %O %q %x %X %U, every int and uint type
floats %b %e %E %f %F %g %G %x %X, float32 and float64
strings, []byte %s %q %x %X, % x, %#q
methods Formatter, GoStringer, error, Stringer, in Go's order
errors Errorf with %w, one or several, seen by errors.Is
composites slices of the basic types, []any, map[string]T sorted by key

A mistake is printed, never panicked, with Go's strings: %!d(string=hi), %!d(MISSING), %!(EXTRA int=1), %!(NOVERB). A Render cannot be taken down by a format string.

How it is tested

gofmt_test.gno is 210 cases whose expected output was produced by running each one through Go's fmt.Sprintf (go1.27.1), so a failure there is, by construction, a place v2 and Go disagree. It also costs less gas than v0 on the calls realms make most: about 211k against 254k per Sprintf("id %d is %s (%t)", ...), measured with gno test.

What it cannot do

gno has no reflect. A struct, a pointer, or a named type without a String method prints (unhandled), and %T names only the types it knows. Give the type a String method. %p is not supported.

Migrating from v0

Mostly a change of import, with these differences, all of them toward Go:

  • Sprint adds a space only between two operands that are both non-strings.
  • a float prints in its shortest form from %v and Sprint (3.14, not 3.140000), and %e defaults to 6 digits.
  • %v of a []byte is [104 105]; use %s for the text.
  • a missing or extra argument is written into the output instead of panicking.
  • error wins over String when a value has both.

Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

⚠️ Disclaimer: provided as-is, without warranty; not security-audited. Full disclaimer: DISCLAIMER.

Overview

Package ufmt is a preview of gno.land/p/nt/ufmt/v2, published here before that path exists.

This is v2 of ufmt. It is not yet published at its expected path, gno.land/p/nt/ufmt/v2. Until it is, import it from gno.land/p/moul/vendor/nt/ufmt/v2; once gno.land/p/nt/ufmt/v2 is live, switch the import and nothing else, because the API is meant to be the same. This path is then frozen and never updated again.

v0 (gno.land/p/nt/ufmt/v0) supports a handful of verbs and no flags, so "%08x", "%X" and "%-10s" print "(unhandled)" or drop their padding without a word. v2 follows Go's fmt instead: the same flags, widths, precisions and verbs, and the same error strings in place of panics. Where it cannot follow Go, because gno has no reflect, it says so below.

Supported, as in Go's fmt:

Example
 1flags      '+' '-' '#' ' ' '0'
 2width      %8d, %*d, and a negative * width left-justifies
 3precision  %.2f, %.*f, %.3s (in runes)
 4indexes    %[2]d %[1]s, %[1]*[2]d
 5general    %v %+v %#v %T %%
 6bool       %t
 7integer    %b %c %d %o %O %q %x %X %U, every int and uint type
 8float      %b %e %E %f %F %g %G %x %X, float32 and float64
 9string     %s %q %x %X, and []byte the same way
10errors     %w in Errorf, unwrapped by errors.Unwrap and errors.Is
11methods    Formatter, GoStringer, error, Stringer, in Go's order
12composite  []T of the basic types, []any, []error, and map[string]T
13           with its keys sorted, as Go prints them

Errors are written into the output, never panicked: "%!d(string=hi)" for a wrong type, "%!d(MISSING)" for a missing argument, "%!(EXTRA int=1)" for an unused one, "%!(NOVERB)" for a trailing '%'.

What gno cannot do, and what v2 prints instead:

  • no reflect, so a struct, a pointer, a named type without a String method, or a slice or map of anything other than the types listed above prints "(unhandled)", and %T names only the types it knows ("unknown" otherwise). Give the type a String method.
  • %p is not supported.

What changed from v0, so a migration is a review and not a find-and-replace:

  • Sprint adds a space only between two operands when neither is a string, as Go does; v0 put a space between every pair.
  • %v of a float, and Sprint of one, is the shortest representation ("3.14"), as Go does; v0 printed "%f" ("3.140000") from Sprint.
  • %e defaults to 6 digits after the point, as Go does; v0 used 2.
  • %v of a []byte prints "[104 105]", as Go does; v0 wrote the raw bytes. Use %s for the string.
  • a missing or extra argument, or a trailing '%', is written into the output instead of panicking.
  • an error is preferred to a String method when a value has both.

Functions 13

func Append 

1func Append(b []byte, a ...any) []byte
source

Append formats its operands as Sprint does and appends the result to b.

func Appendf 

1func Appendf(b []byte, format string, a ...any) []byte
source

Appendf formats according to a format specifier and appends the result to b.

func Appendln 

1func Appendln(b []byte, a ...any) []byte
source

Appendln formats its operands as Sprintln does and appends the result to b.

func Errorf 

1func Errorf(format string, a ...any) error
source

Errorf formats according to a format specifier and returns the string as an error. Each %w operand must be an error; it is printed as %v and returned by the error's Unwrap method, so errors.Is and errors.Unwrap can find it. One %w gives an Unwrap() error, several give an Unwrap() []error, as in Go.

func Fprint 

1func Fprint(w io.Writer, a ...any) (n int, err error)
source

Fprint formats its operands as Sprint does and writes to w.

func Fprintf 

1func Fprintf(w io.Writer, format string, a ...any) (n int, err error)
source

Fprintf formats according to a format specifier and writes to w.

func Fprintln 

1func Fprintln(w io.Writer, a ...any) (n int, err error)
source

Fprintln formats its operands as Sprintln does and writes to w.

func Print 

1func Print(a ...any) (n int, err error)
source

Print formats its operands as Sprint does and prints the result.

func Printf 

1func Printf(format string, a ...any) (n int, err error)
source

Printf formats according to a format specifier and prints the result with the print builtin, which is what a test or a filetest captures.

func Println 

1func Println(a ...any) (n int, err error)
source

Println formats its operands as Sprintln does and prints the result.

func Sprint 

1func Sprint(a ...any) string
source

Sprint formats its operands with %v and returns the string. A space is added between two operands when neither is a string.

func Sprintf 

1func Sprintf(format string, a ...any) string
source

Sprintf formats according to a format specifier and returns the string.

func Sprintln 

1func Sprintln(a ...any) string
source

Sprintln formats its operands with %v, always separated by a space, and appends a newline.

Types 4

type Formatter

interface 
1type Formatter interface {
2	Format(f State, verb rune)
3}
source

Formatter is implemented by a value that formats itself. Format is called for every verb, and its output replaces what ufmt would have printed.

type GoStringer

interface 
1type GoStringer interface {
2	GoString() string
3}
source

GoStringer is implemented by a value that has a Go-syntax form, used for %#v.

type State

interface 
 1type State interface {
 2	// Write emits formatted output.
 3	Write(b []byte) (n int, err error)
 4	// Width returns the width and whether one was set.
 5	Width() (wid int, ok bool)
 6	// Precision returns the precision and whether one was set.
 7	Precision() (prec int, ok bool)
 8	// Flag reports whether the flag c, a character, was set.
 9	Flag(c int) bool
10}
source

State is what a Formatter's Format method is handed: the flags, width and precision of the verb being printed, and somewhere to write.

type Stringer

interface 
1type Stringer interface {
2	String() string
3}
source

Stringer is implemented by a value that has a natural string form. It is used for %v, %s, %q, %x and %X, and by Print.

Imports 5

  • io stdlib
  • sort stdlib
  • strconv stdlib
  • strings stdlib
  • unicode/utf8 stdlib

Source Files 8