The decimals Reference Manual

This is the decimals Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 03:53:27 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 decimals

Decimal number parser and formatter

Author

Teemu Likonen <>

License

Creative Commons CC0 (public domain dedication)

Source

decimals.asd.

Child Component

decimals.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 decimals/decimals.asd

Source

decimals.asd.

Parent Component

decimals (system).

ASDF Systems

decimals.


3.1.2 decimals/decimals.lisp

Source

decimals.asd.

Parent Component

decimals (system).

Packages

decimals.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 decimals

Source

decimals.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: define-decimal-formatter (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,67 "

Package

decimals.

Source

decimals.lisp.


5.1.2 Ordinary functions

Function: format-decimal-number (number &key round-magnitude rounder decimal-separator integer-group-separator integer-group-digits integer-minimum-width integer-pad-char fractional-group-separator fractional-group-digits fractional-minimum-width fractional-pad-char show-trailing-zeros positive-sign negative-sign zero-sign)

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.

Package

decimals.

Source

decimals.lisp.

Function: parse-decimal-number (string &key decimal-separator positive-sign negative-sign start end)

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

Package

decimals.

Source

decimals.lisp.

Function: round-half-away-from-zero (number &optional divisor)

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

Package

decimals.

Source

decimals.lisp.


5.1.3 Generic functions

Generic Reader: decimal-parse-error-string (condition)
Package

decimals.

Methods
Reader Method: decimal-parse-error-string ((condition decimal-parse-error))
Source

decimals.lisp.

Target Slot

string.


5.1.4 Conditions

Condition: 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.

Package

decimals.

Source

decimals.lisp.

Direct superclasses

parse-error.

Direct methods

decimal-parse-error-string.

Direct slots
Slot: string
Package

common-lisp.

Initargs

:string

Readers

decimal-parse-error-string.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Ordinary functions

Function: decimal-round-split (number &key round-magnitude rounder positive-sign negative-sign zero-sign)
Package

decimals.

Source

decimals.lisp.

Function: divide-into-groups (string &key separator from-end group-digits)
Package

decimals.

Source

decimals.lisp.

Function: number-string-to-fractional (string)
Package

decimals.

Source

decimals.lisp.

Function: number-string-to-integer (string)
Package

decimals.

Source

decimals.lisp.

Function: string-align (string width &key side char)
Package

decimals.

Source

decimals.lisp.


Appendix A Indexes


A.1 Concepts


A.3 Variables