sprintf functions
| (require sprintf) |
This module provides a compact printf-style string formatting facility for Racket. It is inspired by C-style format strings, but implemented on top of racket/format.
The core functionality is provided by sprintf and sprintf*.
1 Overview
The module exports two formatting functions:
sprintf — formats using variadic arguments
sprintf* — formats using an explicit argument list
Both functions use the same format-string syntax and semantics.
2 Exports
Arguments are consumed sequentially from left to right. An error is raised if there are too many or too few arguments for the format string.
This form is useful when arguments are constructed dynamically or passed through higher-order functions.
3 Format String Syntax
A format specification has the general form:
%[flags][width][.precision][length]type |
Only a well-defined subset of the traditional printf syntax is supported.
4 Supported Conversion Types
The following conversion specifiers are recognized:
%d — decimal integer
%x — hexadecimal integer
%f — floating-point number
%s — string
%% — literal percent sign
5 Flags
The following flags are supported:
0 — pad numeric output with zeros instead of spaces
- — left-align the result within the field width
If no flag is specified, numeric values are right-aligned and padded with spaces.
6 Field Width
A minimum field width may be specified as a decimal number:
%8d |
%-10s |
If the formatted value is shorter than the field width, it is padded according to the alignment rules.
7 Dynamic Width and Precision
Both width and precision may be specified using *. In that case, the value is taken from the argument list.
Example:
(sprintf "%*.*f" 8 3 1.23456) |
the first argument specifies the field width
the second argument specifies the precision
the third argument is the value to be formatted
The arguments supplying width or precision must be numbers; otherwise an error is raised.
8 Precision
Precision has different meanings depending on the conversion type:
for numeric conversions, it controls the number of digits after the decimal point
for strings, it specifies the maximum output width
numeric values default to precision 0 for integers
strings are not truncated
9 Length Modifiers
The length modifier field (e.g. l) is parsed for syntactic compatibility but otherwise ignored. It has no semantic effect.
10 Type Checking and Errors
The formatter performs runtime type checking:
numeric conversion specifiers require numeric arguments
%s requires a string argument
Errors are raised in the following situations:
arguments remain but no format specifiers are left
format specifiers remain but no arguments are left
* is used but no corresponding numeric argument is available
argument types do not match the conversion specifier
Error messages are designed to be explicit and descriptive.
11 Implementation Notes
Internally, the formatter uses regular-expression driven parsing and delegates the actual formatting to ~r and ~a from racket/format.
The implementation is intentionally strict: mismatches between format strings and arguments are treated as programming errors and reported immediately.