#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.