parse-integer

parse-integer Function

Syntax:

parse-integer string &key start end radix junk-allowed → integer, pos

Arguments and Values:

string—a string.

start, end—bounding index designators of string. The defaults for start and end are 0 and nil, respectively.

radix—a radix . The default is 10.

junk-allowed—a generalized boolean. The default is false.

integer—an integer or false.

pos—a bounding index of string.

Description:

parse-integer parses an integer in the specified radix from the substring of string delimited by start and end.

parse-integer expects an optional sign (+ or -) followed by a a non-empty sequence of digits to be interpreted in the specified radix. Optional leading and trailing whitespace₁ is ignored.

parse-integer does not recognize the syntactic radix-specifier prefixes #O, #B, #X, and #nR, nor does it recognize a trailing decimal point.

If junk-allowed is false, an error of type parse-error is signaled if substring does not consist entirely of the representation of a signed integer , possibly surrounded on either side by whitespace₁ characters.

The first value returned is either the integer that was parsed, or else nil if no syntactically correct integer was seen but junk-allowed was true.

The second value is either the index into the string of the delimiter that terminated the parse, or the upper bounding index of the substring if the parse terminated at the end of the substring (as is always the case if junk-allowed is false).

Examples:

(parse-integer "123") → 123, 3 
(parse-integer "123" :start 1 :radix 5) → 13, 3 
(parse-integer "no-integer" :junk-allowed t) → NIL, 0 

Exceptional Situations:

If junk-allowed is false, an error is signaled if substring does not consist entirely of the representation of an integer , possibly surrounded on either side by whitespace₁ characters.

Expanded Reference: parse-integer

Basic integer parsing

parse-integer parses a string and returns two values: the integer and the position where parsing stopped.

(parse-integer "123")
=> 123
=> 3
(parse-integer "456")
=> 456
=> 3
(parse-integer "-42")
=> -42
=> 3
(parse-integer "+99")
=> 99
=> 3

Specifying start and end positions

The :start and :end keyword arguments select a substring to parse.

(parse-integer "hello123world" :start 5 :end 8)
=> 123
=> 8
(parse-integer "123" :start 1)
=> 23
=> 3
(parse-integer "00042" :start 3)
=> 42
=> 5

Parsing with a different radix

The :radix keyword specifies the base. The default is 10.

(parse-integer "FF" :radix 16)
=> 255
=> 2
(parse-integer "111" :radix 2)
=> 7
=> 3
(parse-integer "77" :radix 8)
=> 63
=> 2
(parse-integer "123" :start 1 :radix 5)
=> 13
=> 3

Allowing junk in the string

By default, non-numeric characters cause an error. Use :junk-allowed t to tolerate trailing junk.

(parse-integer "123abc" :junk-allowed t)
=> 123
=> 3
(parse-integer "no-integer" :junk-allowed t)
=> NIL
=> 0
(parse-integer "  42  " :junk-allowed t)
=> 42
=> 4

Whitespace handling

Leading and trailing whitespace is ignored (when no junk is present).

(parse-integer "  123  ")
=> 123
=> 7
(parse-integer "   -7   ")
=> -7
=> 8

Practical use: reading numbers from user input

parse-integer is commonly used to convert string input to integers.

(defun read-number (prompt default)
  (format t "~A [~A]: " prompt default)
  (let ((input (read-line)))
    (if (string= input "")
        default
        (or (parse-integer input :junk-allowed t)
            default))))