Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the decimals Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:13:22 2020 GMT+0.
• Introduction | What decimals is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
A decimal number parser and formatting package for Common Lisp
This Common Lisp package offers functions for parsing and formatting
decimal numbers. Package's main interface are functions
parse-decimal-number
and format-decimal-number
. The former is for
parsing strings for decimal numbers and the latter for pretty-printing
them as strings. See section The Programming Interface for the full
documentation of the public programming interface. Here are some
examples.
DECIMALS> (parse-decimal-number "0.24")
6/25
DECIMALS> (parse-decimal-number "−12,345"
:decimal-separator #\,
:negative-sign #\−)
-2469/200
DECIMALS> (format-decimal-number -100/6 :round-magnitude -3)
"-16.667"
("-" "16" "." "667")
DECIMALS> (loop for e from -5 upto 5
do (print (format-decimal-number
(expt 10 e) :round-magnitude -5
:decimal-separator ","
:integer-minimum-width 7
:integer-group-separator " "
:fractional-minimum-width 7
:fractional-group-separator " ")))
" 0,000 01"
" 0,000 1 "
" 0,001 "
" 0,01 "
" 0,1 "
" 1 "
" 10 "
" 100 "
" 1 000 "
" 10 000 "
"100 000 "
NIL
DECIMALS> (loop for m from -3 upto 3
do (print (format-decimal-number
2000/3 :round-magnitude m
:integer-minimum-width 4
:fractional-minimum-width 4)))
" 666.667"
" 666.67 "
" 666.7 "
" 667 "
" 670 "
" 700 "
"1000 "
NIL
Author: Teemu Likonen <tlikonen@iki.fi>
OpenPGP key: 4E10 55DC 84E9 DFF6 13D7 8557 719D 69D3 2453 9450
License: Creative Commons CC0 (public domain dedication)
The source code repository: https://github.com/tlikonen/cl-decimals
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.
format-decimal-number
The lambda list:
(number &key (round-magnitude 0)
(rounder #'round-half-away-from-zero) (decimal-separator #\.)
(integer-group-separator nil) (integer-group-digits 3)
(integer-minimum-width 0) (integer-pad-char #\ )
(fractional-group-separator nil) (fractional-group-digits 3)
(fractional-minimum-width 0) (fractional-pad-char #\ )
(show-trailing-zeros nil) (positive-sign nil) (negative-sign #\-)
(zero-sign nil))
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.
parse-decimal-number
The lambda list:
(string &key (decimal-separator #\.) (positive-sign #\+)
(negative-sign #\-) (start 0) (end nil))
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
round-half-away-from-zero
The lambda list:
(number &optional (divisor 1))
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
define-decimal-formatter
The lambda list:
(name &body keyword-arguments)
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
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The decimals system |
Teemu Likonen <tlikonen@iki.fi>
Creative Commons CC0 (public domain dedication)
Decimal number parser and formatter
decimals.asd (file)
decimals.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The decimals.asd file | ||
• The decimals/decimals.lisp file |
Next: The decimals/decimals․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
decimals.asd
decimals (system)
Previous: The decimals․asd file, Up: Lisp files [Contents][Index]
decimals (system)
decimals.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The decimals package |
decimals.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
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 "
decimals.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
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.
decimals.lisp (file)
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
decimals.lisp (file)
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
decimals.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
decimals.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
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.
decimals.lisp (file)
parse-error (condition)
decimal-parse-error-string (method)
:string
decimal-parse-error-string (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal functions |
Previous: Internal definitions, Up: Internal definitions [Contents][Index]
decimals.lisp (file)
decimals.lisp (file)
decimals.lisp (file)
decimals.lisp (file)
decimals.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | D F L |
---|
Jump to: | D F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | D F G M N P R S |
---|
Jump to: | D F G M N P R S |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | S |
---|
Index Entry | Section | ||
---|---|---|---|
| |||
S | |||
Slot, string : | Exported conditions | ||
string : | Exported conditions | ||
|
Jump to: | S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | C D P S |
---|
Jump to: | C D P S |
---|