The read-number Reference Manual

This is the read-number Reference Manual, version 20230105.1030, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Nov 06 14:45:15 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 read-number

Reading numbers from an input stream.

Author

Ralph Schleicher <>

License

Modified BSD License

Version

20230105.1030

Dependencies
  • alexandria (system).
  • lisp-unit (system).
Source

read-number.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 read-number/read-number.asd

Source

read-number.asd.

Parent Component

read-number (system).

ASDF Systems

read-number.


3.1.2 read-number/package.lisp

Source

read-number.asd.

Parent Component

read-number (system).

Packages

read-number.


3.1.3 read-number/common.lisp

Dependency

package.lisp (file).

Source

read-number.asd.

Parent Component

read-number (system).

Public Interface
Internals

3.1.4 read-number/read-integer.lisp

Dependency

common.lisp (file).

Source

read-number.asd.

Parent Component

read-number (system).

Public Interface

read-integer (function).


3.1.5 read-number/read-float.lisp

Dependency

read-integer.lisp (file).

Source

read-number.asd.

Parent Component

read-number (system).

Public Interface

read-float (function).


4 Packages

Packages are listed by definition order.


4.1 read-number

Reading numbers from an input stream without using the Lisp reader.

The ‘read-integer’ and ‘read-float’ functions are designed to read external number representations. The ‘read-number’ function (to be defined) is reserved for reading any Lisp number representation.

Source

package.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 Special variables

Special Variable: *default-decimal-point*

Controls the set of valid decimal point (or better radix point) characters when reading an external number representation and no explicit decimal point keyword argument is specified. Value has to be a sequence of characters. The default is ‘.’ (Unicode U+002E, full stop).

Another candidate for this character set is ‘,’ (Unicode U+002C, comma). ISO 31 uses the decimal point in the international English version of the standard and the decimal comma in the original French version. Interactive applications should accept both variants to improve usability.

Package

read-number.

Source

common.lisp.

Special Variable: *default-exponent-marker*

Controls the set of valid exponent marker characters when reading an external number representation and no explicit exponent marker keyword argument is specified. Value has to be a sequence of characters. The default is ‘E’, ‘e’, ‘D’, and ‘d’.

Another candidate for this character set is ‘⏨’ (Unicode U+23E8, decimal exponent symbol).

Package

read-number.

Source

common.lisp.

Special Variable: *default-group-separator*

Controls the set of valid group separator characters when reading an external number representation and no explicit group separator keyword argument is specified. Value has to be a sequence of characters. The default is the empty set.

Candidates for this character set are ‘’’ (Unicode U+0027, apostrophe), ‘_’ (Unicode U+005F, low line), ‘ ’ (Unicode U+00A0, no-break space), and ‘ ’ (Unicode U+202F, narrow no-break space). The preferred group separator according to ISO 31 is the narrow no-break space character.

Package

read-number.

Source

common.lisp.

Special Variable: *default-minus-sign*

Controls the set of valid minus sign characters when reading an external number representation and no explicit minus sign keyword argument is specified. Value has to be a sequence of characters. The default is ‘-’ (Unicode U+002D, hyphen-minus).

Another candidate for this character set is ‘−’ (Unicode U+2212, minus sign).

Package

read-number.

Source

common.lisp.

Special Variable: *default-plus-sign*

Controls the set of valid plus sign characters when reading an external number representation and no explicit plus sign keyword argument is specified. Value has to be a sequence of characters. The default is ‘+’ (Unicode U+002B, plus sign).

Package

read-number.

Source

common.lisp.


5.1.2 Ordinary functions

Function: read-float (&optional input-stream eof-error-p eof-value recursivep &key unsigned-number plus-sign minus-sign group-separator decimal-point exponent-marker float-format significand-radix exponent-radix exponent-base)

Read a floating-point number from an input stream.

Optional first argument INPUT-STREAM is an input stream designator. The default is standard input.
Optional second argument EOF-ERROR-P is a generalized boolean.
If an end of file error occurs and EOF-ERROR-P is false, EOF-VALUE is returned. Otherwise, signal an ‘end-of-file’ error. The default is true.
Optional third argument EOF-VALUE is an object. See above for more details. The default is nil.
Optional fourth argument RECURSIVEP is a generalized boolean. True means that this call is expected to be embedded in a higher-level call to ‘read’ or a similar function used by the Lisp reader. The default is false.
Keyword argument UNSIGNED-NUMBER is a generalized boolean. True means to read an unsigned positive number. If UNSIGNED-NUMBER is ‘:plus’, an explicit plus sign character signals a ‘parse-error’ but negative numbers are permitted. The default is false.
Keyword argument PLUS-SIGN is a sequence of valid plus sign characters. The plus sign is used to denote a positive number. The default is the value of the ‘*default-plus-sign*’ special variable.
Keyword argument MINUS-SIGN is a sequence of valid minus sign characters. The minus sign is used to denote a negative number. The default is the value of the ‘*default-minus-sign*’ special variable.
Keyword argument GROUP-SEPARATOR is a sequence of valid group separator characters. The group separator is used to separate the digits of a number into groups. The default is the value of the ‘*default-group-separator*’ special variable. The group separator of a number can not change, i.e. the first matching group separator fixes the group separator for the rest of the number.
Keyword argument DECIMAL-POINT is a sequence of valid decimal point characters. The decimal point is used to separate the integer part of the significand from its fractional part. The default is the value of the ‘*default-decimal-point*’ special variable.
Keyword argument EXPONENT-MARKER is a sequence of valid exponent marker characters. The exponent marker is used to separate the significand from the exponent. It does not specify the data type of the return value. The default is the value of the ‘*default-exponent-marker*’ special variable.
Keyword argument FLOAT-FORMAT specifies the data type of the return value. Value is either ‘short-float’, ‘single-float’, ‘double-float’, or ‘long-float’. The default is the value of the ‘*read-default-float-format*’ special variable. A value of ‘nil’ means that the return value is a rational number.
Keyword argument SIGNIFICAND-RADIX and EXPONENT-RADIX is the radix for the digits of the significand and exponent respectively. Value has to be an integer between 2 and 36, inclusive. The default is 10. Case is not significant for the digit characters ‘A’ to ‘Z’ when parsing numbers with a radix greater than 10.
Keyword argument EXPONENT-BASE is the base of the power term. Value has to be an integer greater than or equal to 2. The default is 10.

Return value is a floating-point number of type FLOAT-FORMAT iff a decimal point or exponent part is present and FLOAT-FORMAT is not null. Otherwise, value is a rational number. Secondary value is the number of characters read.

The ‘read-float’ function expects an optional sign followed by a non-empty sequence of digits. It does recognize a decimal point and an exponent part. Leading or trailing whitespace is not ignored.

If the file ends in the middle of a floating-point number representation, ‘read-float’ signals an ‘end-of-file’ error regardless of the value of the EOF-ERROR-P argument.

Converting a floating-point number to the specified FLOAT-FORMAT type may signal an ‘arithmetic-error’ condition, for example, a ‘floating-point-overflow’ or ‘floating-point-underflow’ error.

The result if undefined if the sequences of valid plus and minus sign characters intersect.

Package

read-number.

Source

read-float.lisp.

Function: read-integer (&optional input-stream eof-error-p eof-value recursivep &key unsigned-number plus-sign minus-sign group-separator radix)

Read an integer from an input stream.

Optional first argument INPUT-STREAM is an input stream designator. The default is standard input.
Optional second argument EOF-ERROR-P is a generalized boolean.
If an end of file error occurs and EOF-ERROR-P is false, EOF-VALUE is returned. Otherwise, signal an ‘end-of-file’ error. The default is true.
Optional third argument EOF-VALUE is an object. See above for more details. The default is nil.
Optional fourth argument RECURSIVEP is a generalized boolean. True means that this call is expected to be embedded in a higher-level call to ‘read’ or a similar function used by the Lisp reader. The default is false.
Keyword argument UNSIGNED-NUMBER is a generalized boolean. True means to read an unsigned positive number. If UNSIGNED-NUMBER is ‘:plus’, an explicit plus sign character signals a ‘parse-error’ but negative numbers are permitted. The default is false.
Keyword argument PLUS-SIGN is a sequence of valid plus sign characters. The plus sign is used to denote a positive number. The default is the value of the ‘*default-plus-sign*’ special variable.
Keyword argument MINUS-SIGN is a sequence of valid minus sign characters. The minus sign is used to denote a negative number. The default is the value of the ‘*default-minus-sign*’ special variable.
Keyword argument GROUP-SEPARATOR is a sequence of valid group separator characters. The group separator is used to separate the digits of a number into groups. The default is the value of the ‘*default-group-separator*’ special variable. The group separator of a number can not change, i.e. the first matching group separator fixes the group separator for the rest of the number.
Keyword argument RADIX is a radix. Value has to be an integer between 2 and 36, inclusive. The default is 10. Case is not significant for the digit characters ‘A’ to ‘Z’ when parsing numbers with a radix greater than 10.

Return value is an integer. Secondary value is the number of characters read.

The ‘read-integer’ function expects an optional sign followed by a non-empty sequence of digits in the specified radix. It does not recognize a decimal point or exponent marker. Leading or trailing whitespace is not ignored.

If the file ends in the middle of an integer representation, ‘read-integer’ signals an ‘end-of-file’ error regardless of
the value of the EOF-ERROR-P argument.

The result if undefined if the sequences of valid plus and minus sign characters intersect.

Package

read-number.

Source

read-integer.lisp.


5.2 Internals


5.2.1 Macros

Macro: with-input-from ((input-stream eof-error-p eof-value recursivep) (bindings result) &body body)

Framework for reading numbers. The local bindings available in BODY are documented below.

– next-char (&optional (EOF-QUIT-P t)) [Function] Read the next character from INPUT-STREAM. If optional argument EOF-QUIT-P is true, call ‘quit’ if no character
can be read. Modifies ‘next-char’ and maybe ‘length’.

– next-char [Variable] The last character read by the ‘next-char’ function.

– quit () [Function] Undo the effects of the ‘next-char’ function. Return RESULT
if a valid number could be read. Otherwise, signal an error.

– length [Variable] The total number of characters read so far. This is the secondary value returned by the ‘quit’ function. This
variable shall be considered read-only.

– digits [Variable] The total number of digits consumed so far. This variable
can be modified by the user. A value of zero indicates for
the ‘quit’ function that no valid number could be read.

– read-int (RADIX GROUP-SEPARATOR) [Function] Read a sequence of digits and return its numerical value.
May call ‘next-char’ and ‘quit’. Maybe modifies ‘digits’.

Package

read-number.

Source

common.lisp.


5.2.2 Ordinary functions

Function: sequence-of-characters-p (object)

Return true if OBJECT is a sequence of characters. If OBJECT is an empty sequence, value is true, too.

Package

read-number.

Source

common.lisp.

Function: standard-digit-char-p (char &optional radix)

Return true if CHAR is a standard digit character.

First argument CHAR has to be a character object.
Optional second argument RADIX is an integer between 2 and 36, inclusive. The default is 10.

Return value is the weight of CHAR as an integer, or nil.

Package

read-number.

Source

common.lisp.


5.2.3 Types

Type: sequence-of-characters ()

Type specifier for a sequence of characters.

Package

read-number.

Source

common.lisp.


Appendix A Indexes


A.1 Concepts