106 lines
3.5 KiB
Racket
106 lines
3.5 KiB
Racket
#lang scribble/manual
|
|
|
|
@(require (for-label racket/base
|
|
racket/contract/base
|
|
racket/format
|
|
racket-sprintf))
|
|
|
|
@title{racket-sprintf}
|
|
@author["Hans Dijkema / hans@dijkewijk.nl"]
|
|
|
|
@defmodule[racket-sprintf]
|
|
|
|
The @tt{racket-sprintf} package provides @racket[sprintf] and
|
|
@racket[sprintf*], two small C-style string formatting procedures. The
|
|
format language deliberately supports only a useful subset of C
|
|
@tt{printf}. The result is always a string; output is not written to a port.
|
|
|
|
@section{Procedures}
|
|
|
|
@defproc[(sprintf [fmt string?] [arg any/c] ...) string?]{
|
|
Formats the arguments according to @racket[fmt] and returns the resulting
|
|
string. Arguments are consumed from left to right. An exception is raised
|
|
when a conversion is missing an argument, when arguments remain after all
|
|
conversions have been processed, or when an argument has the wrong type for
|
|
its conversion.
|
|
}
|
|
|
|
@defproc[(sprintf* [fmt string?] [args list?]) string?]{
|
|
Like @racket[sprintf], but takes the values to format in the list
|
|
@racket[args]. This is useful when the arguments have already been collected
|
|
in a list.
|
|
}
|
|
|
|
@section{Format syntax}
|
|
|
|
A conversion has this form:
|
|
|
|
@verbatim{%[flag][width][.precision][length]conversion}
|
|
|
|
The supported conversion characters are @tt{s}, @tt{d}, @tt{f}, @tt{x}, and
|
|
@tt{%}. @tt{%s} formats a string. @tt{%d} formats a decimal number.
|
|
@tt{%f} formats a number using the requested precision. @tt{%x} formats a
|
|
number in base 16. @tt{%%} represents a literal percent sign.
|
|
|
|
The optional @tt{-} flag left-aligns a value within its field. Without
|
|
@tt{-}, a value with a field width is right-aligned. For numeric conversions,
|
|
the optional @tt{0} flag pads on the left with zeroes.
|
|
|
|
A width specifies the minimum field width. For example:
|
|
|
|
@verbatim{
|
|
(sprintf "%10s" "Abc") ; => " Abc"
|
|
(sprintf "%-10s" "Abc") ; => "Abc "
|
|
(sprintf "%05d" 42) ; => "00042"
|
|
(sprintf "%-5d" 42) ; => "42 "
|
|
}
|
|
|
|
For @tt{%s}, precision specifies the maximum number of characters taken from
|
|
the string. Truncation happens before field-width padding. Consequently:
|
|
|
|
@verbatim{
|
|
(sprintf "%.5s" "abcdefgh") ; => "abcde"
|
|
(sprintf "%10.5s" "abcdefgh") ; => " abcde"
|
|
(sprintf "%-10.5s" "abcdefgh") ; => "abcde "
|
|
}
|
|
|
|
For numeric conversions other than @tt{%d}, precision is passed to
|
|
@racket[~r] as the number of digits after the decimal point. Decimal integer
|
|
conversion @tt{%d} always uses integer-style precision zero.
|
|
|
|
@section{Dynamic width and precision}
|
|
|
|
A width or precision can be written as @tt{*}. Its value is then consumed
|
|
from the argument list before the value being formatted. For example:
|
|
|
|
@verbatim{
|
|
(sprintf "%*.*f" 8 3 1.23456)
|
|
}
|
|
|
|
Here @tt{8} supplies the field width, @tt{3} supplies the precision, and
|
|
@tt{1.23456} is the value. A dynamic width or precision must be numeric.
|
|
|
|
@section{Length modifier}
|
|
|
|
One or more @tt{l} characters are accepted before the conversion character
|
|
for compatibility with existing format strings, but currently have no effect
|
|
on the result.
|
|
|
|
@section{Type rules}
|
|
|
|
The @tt{%s} conversion requires a string. The numeric conversions require a
|
|
number. The implementation intentionally reports a type mismatch instead of
|
|
silently coercing the value.
|
|
|
|
@section{Examples}
|
|
|
|
@racketblock[
|
|
(sprintf "%-12s %5d" "items" 42)
|
|
(sprintf "%08x" 255)
|
|
(sprintf "%-10.4s" "abcdefgh")
|
|
(sprintf* "%s = %d" (list "answer" 42))
|
|
]
|
|
|
|
The implementation uses @racket[~a] and @racket[~r] from
|
|
@racketmodname[racket/format] for the final field formatting.
|