This is the decimals Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 03:57:12 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
decimalsDecimal number parser and formatter
Teemu Likonen <tlikonen@iki.fi>
Creative Commons CC0 (public domain dedication)
decimals.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
decimals/decimals.lispdecimals (system).
decimal-parse-error (condition).
decimal-parse-error-string (reader method).
define-decimal-formatter (macro).
format-decimal-number (function).
parse-decimal-number (function).
round-half-away-from-zero (function).
decimal-round-split (function).
divide-into-groups (function).
number-string-to-fractional (function).
number-string-to-integer (function).
string-align (function).
Packages are listed by definition order.
decimalscommon-lisp.
decimal-parse-error (condition).
decimal-parse-error-string (generic reader).
define-decimal-formatter (macro).
format-decimal-number (function).
parse-decimal-number (function).
round-half-away-from-zero (function).
decimal-round-split (function).
divide-into-groups (function).
number-string-to-fractional (function).
number-string-to-integer (function).
string-align (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Define a decimal number formatter function to use with the ‘~/‘
directive of ‘cl:format‘. The valid format is this:
(define-decimal-formatter name
(:keyword form)
...)
_Name_ is the symbol that names the function. _Keyword_ must be a valid
keyword argument for the ‘format-decimal-number‘ function (see its
documentation for more information). _Form_ is evaluated and the value
is used with the _keyword_ argument. Macro’s side effect is that global
function _name_ is defined. It can be used with the ‘~/‘ directive of
‘cl:format‘ function.
Examples:
(define-decimal-formatter my-formatter
(:round-magnitude -6)
(:decimal-separator ",")
(:integer-group-separator " ")
(:integer-minimum-width 4)
(:fractional-group-separator " ")
(:fractional-minimum-width 10)
(:show-trailing-zeros t))
=> MY-FORMATTER
(format nil "~/my-formatter/" 10/6)
=> " 1,666 667 "
(format nil "~/my-formatter/" 100/8)
=> " 12,500 000 "
The ‘~/‘ directive function call can optionally take up to three
arguments to override the defaults:
~round-magnitude,integer-minimum-width,fractional-minimum-width/FUNCTION/
For example:
(format nil "~-2,3,4/my-formatter/" 10/6)
=> " 1,67 "
Apply specified decimal number formatting rules to _number_ and
return a formatted string.
The second return value is (almost) the same formatted string divided
into four strings. It’s a list of four strings: sign, integer part,
decimal separator and fractional part. Formatting arguments
_integer-minimum-width_ and _fractional-minimum-width_ do not apply to
the second return value. Everything else does.
_Number_ must be of type ‘real‘. This function uses ‘rational‘ types
internally. If the given _number_ is a ‘float‘ it is first turned into
‘rational‘ by calling ‘cl:rational‘.
Formatting rules are specified with keyword arguments, as described
below. The default value is in parentheses.
* ‘round-magnitude (0)‘
This is the order of magnitude used for rounding. The value must be
an integer and it is interpreted as a power of 10.
* ‘show-trailing-zeros (nil)‘
If the value is non-nil print all trailing zeros in fractional part.
Examples:
(format-decimal-number 1/5 :round-magnitude -3
:show-trailing-zeros nil)
=> "0.2"
(format-decimal-number 1/5 :round-magnitude -3
:show-trailing-zeros t)
=> "0.200"
* ‘rounder (#’round-half-away-from-zero)‘
The value must be a function (or a symbol naming a function). It is
used to round the number to the specified round magnitude. The
function must work like ‘cl:truncate‘, ‘cl:floor‘, ‘cl:ceiling‘ and
‘cl:round‘, that is, take two arguments, a number and a divisor, and
return the quotient as the first value.
This package introduces another rounding function,
‘round-half-away-from-zero‘, which is used by default. See its
documentation for more information.
* ‘decimal-separator (#\.)‘
If the value is non-nil the ‘princ‘ output of the value will be
added between integer and fractional parts. Probably the most useful
types are ‘character‘ and ‘string‘.
* ‘integer-group-separator (nil)‘
* ‘fractional-group-separator (nil)‘
If the value is non-nil the digits in integer or fractional parts
are put in groups. The ‘princ‘ output of the value will be added
between digit groups.
* ‘integer-group-digits (3)‘
* ‘fractional-group-digits (3)‘
The value is a positive integer defining the number of digits in
groups.
* ‘integer-minimum-width (0)‘
* ‘fractional-minimum-width (0)‘
Format integer or fractional part using minimum of this amount of
characters, possibly using some padding characters (see below).
_positive-sign_, _negative-sign_ or _zero-sign_ (see below) is
included when calculating the width of the integer part. Similarly
_decimal-separator_ is included when calculating the width of the
fractional part.
* ‘integer-pad-char (#\Space)‘
* ‘fractional-pad-char (#\Space)‘
The value is the padding character which is used to fill
_integer-minimum-width_ or _fractional-minimum-width_.
* ‘positive-sign (nil)‘
* ‘negative-sign (#\-)‘
* ‘zero-sign (nil)‘
If values are non-nil these are used as the leading sign for positive, negative and zero numbers. The ‘princ‘ output of the value is used.
Examine _string_ (or its substring from _start_ to _end_) for a
decimal number. Assume that the decimal number is exact and return it as
a rational number.
Rules for parsing: First all leading and trailing ‘#\Space‘ characters
are stripped. The resulting string may start with a _positive-sign_ or a
_negative-sign_ character. The latter causes this function to assume a
negative number. The following characters in the string must include one
or more digit characters and it may include one _decimal-separator_
character which separates integer and fractional parts. All other
characters are illegal.
If the parsing rules are not met a ‘decimal-parse-error‘ condition is
signaled. Function ‘decimal-parse-error-string‘ can be used to read the
string from the condition object.
Examples:
(parse-decimal-number "0.2") => 1/5
(parse-decimal-number ".2") => 1/5
(parse-decimal-number "+3.") => 3
(parse-decimal-number " -7 ") => -7
(parse-decimal-number "−12,345"
:decimal-separator #\,
:negative-sign #\−)
=> -2469/200
Divide _number_ by _divisor_ and round the result to the nearest integer.
If the result is half-way between two integers round away from zero. Two
values are returned: quotient and remainder.
This is similar to ‘cl:round‘ function except that ‘cl:round‘ rounds to an even integer when number is exactly between two integers. Examples:
(round-half-away-from-zero 3/2) => 2, -1/2
(round 3/2) => 2, -1/2
(round-half-away-from-zero 5/2) => 3, -1/2
(round 5/2) => 2, 1/2
decimal-parse-error)) ¶Function ‘parse-decimal-number‘ signals this condition when it couldn’t parse a decimal number from string. Function ‘decimal-parse-error-string‘ can be used to read the input string from the condition object.
parse-error.
common-lisp.
:string
This slot is read-only.
| Jump to: | D F G M N P R S |
|---|
| Jump to: | D F G M N P R S |
|---|
| Jump to: | C D F P S |
|---|
| Jump to: | C D F P S |
|---|