Format Specification Mini-Language
Specification
Instead of explicitly constructing Formatter
instances, users
can construct SciNum
instances and format them using string
formatting with format specification strings from the sciform
format specification mini-language (FSML).
This is analogous to how python int
, float
, and
Decimal
instances can be formatted using the built-in
format specification mini-language.
The sciform
format specification mini-language is given by:
format_spec ::= [left_pad_char "="][sign]["#"][left_pad_dec_place][round_mode ndigits][exp_mode]["x" exp_val]["p"]["()"]
left_pad_char ::= "0" | " "
sign ::= "+" | "-" | " "
left_pad_dec_place ::= digit+
round_mode ::= "!" | "."
ndigits ::= [+-]?digit+
exp_mode ::= "f" | "F" | "%" | "e" | "E" | "r" | "R" | "b" | "B" |
exp_val ::= [+-]?digit+
Below is are two simple FSML usage examples. See FSML examples for more complicated FSML usage examples.
>>> from sciform import SciNum
>>> print(f"{SciNum(123456):!4f}")
123500
In this example !4
indicates the number should be formatted with
four significant figures and f
indicates the number should be
formatted in fixed point mode.
>>> print(f"{SciNum(12345, 789):!1r}")
(12.3 ± 0.8)e+03
In this example !1
indicates the number will be formatted so that
the uncertainty has one significant digit (and the value will be rounded
and displayed accordingly).
The r
indicates that the number will be formatted using engineering
notation.
See below for details about how the terms in the FSML correspond to formatting options. Further details about the options can be found at Formatting Options.
Format Specification |
Description |
---|---|
left_pad_char
(
'0=' , ' =' ) |
Configure |
sign
(
'-' , '+' , ' ' ) |
Configure |
alternate mode
(
'#' ) |
The alternate mode flag indicates to use
Shifted Engineering Notation mode when the exponent mode flag is
|
left_pad_dec_place
(
\d+ ) |
Sets |
round_mode
(
'!' , '.' ) |
Sets |
ndigits
(
[+-]?\d+ ) |
Sets |
exp_mode
(
'f' , 'F' , '%' , 'e' , 'E' , 'r' , 'R' ,
'b' , 'B' ) |
Sets
|
exp_val
(
x[+-]\d+ ) |
Sets |
prefix mode
(
'p' ) |
Sets |
parentheses uncertainty
(
'()' ) |
Sets |
Incompatibilities With Built-in Format Specification Mini-Language
The sciform
FSML extends the functionality of the
built-in FSML.
However, sciform
FSML is not entirely backwards compatible with
the built-in FSML.
Certain allowed built-in format specifications are illegal in the
sciform
FSML and certain allowed built-in format specifications
give different results when used with SciNum
rather than
float
or Decimal
objects.
These incompatibilities were intentionally introduced to simplify the
sciform
FSML by cutting out features less likely to be required
for scientific formatting.
The built-in FSML accepts
g
,G
andn
precision types (exponent modes). These precision types are not supported bysciform
. These precision types offer automated formatting decisions which are not compatible with the explicit formatting options preferred bysciform
. The built-in automation features includeAutomated selection of fixed-point or scientific notation. For
sciform
, the exponent mode is either explicitly indicated by the user or resolved from the global options.Truncation of trailing zeros without the
#
option. Forsciform
, trailing zeros are never truncated if they fall within the user-selected decimal place or significant figures rounding.Inclusion of a hanging decimal point, e.g.
123.
.sciform
never includes a hanging decimal point.
For
float
instances, Python formatting uses a default precision of 6 forf
,F
,%
,e
, andE
modes if no explicit precision (ndigits
) is supplied.sciform
, instead, convertsfloat
instances intostr
and thenDecimal
so that they are displayed with as many digits as necessary to “round-trip” when nondigits
is supplied. E.g.f'{float(0.3):f}'
yields0.300000
whilef'{SciNum(0.3):f}
yields0.3
.The built-in FSML supports left-aligned, right-aligned, center-aligned, and sign-aware string padding by any character. In the built-in FSML, the width field indicates the minimum length to which the resulting string (including all punctuation such as
+
,-
,.
,e
, etc.) should be filled.sciform
takes the stance that these padding features are tasks better suited for string, as opposed to number, formatters. Forsciform
, the user specifies the digits place to which the number should be padded. The pad character may only be' '
or'0'
and must always be followed by the sign aware = flag. There is no0
flag, as in the built-in FSML, that may be placed before the width field to indicate sign-aware zero padding. E.g.f'{float(12): =4}
yields' 12'
whilef{SciNum(12): =4}
yields' 12'
, fill characters are padded up to the 104 digits place.The built-in FSML supports configuring a thousands separator (what
sciform
calls theupper_separator
).sciform
has more numerous options for grouping separators such that it would be cumbersome to include all grouping separator options in thesciform
FSML and awkward to only include a subset. Therefore no grouping separators can be configured using thesciform
FSML, and these instead need to be configured as global options.The built-in FSML supports displaying negative zero, but also supports an option to coerce negative zero to be positive by including a
'z'
flag.sciform
always coerces negative zero to be positive and therefore has no corresponding option to coerce negative zero to be positive.