## quaviver

2024-10-12

A portable and extensible floating point string library

### Upstream URL

### Author

### License

# Quaviver

A portable and extensible floating point base conversion and string library.

## Introduction

Quaviver is a collection of Common Lisp systems that implement various algorithms for changing the base (or radix) of floating point numbers and for parsing and writing numbers. It includes many utility functions for reading and writing numerical digits, performing arithmetic on floating point significands and binary encoding of floating point numbers into formats like binary32. Quaviver also includes a high-level interface to reading, writing and parsing numbers in various formats.

## QUAVIVER/STREAM system and package

The QUAVIVER/STREAM package includes three different functions for parsing, reading and writing numbers. Each one of these functions take several keyword arguments which control the serialization method. All three functions include a keyword argument :STYLE which selects the overall number format as per the following table.

Value | Description |
---|---|

:BLUB | Generic integers and floating point |

:C89 | C89 Standard integers and floating point |

:C99 | C99 Standard integers and floating point |

:C11 | C11 Standard integers and floating point |

:C17 | C17 Standard integers and floating point |

:C23 | C23 Standard integers and floating point |

:C++98 | C++98 Standard integers and floating point |

:C++03 | C++03 Standard integers and floating point |

:C++11 | C++11 Standard integers and floating point |

:C++14 | C++14 Standard integers and floating point |

:C++17 | C++17 Standard integers and floating point |

:C++20 | C++20 Standard integers and floating point |

:C++23 | C++23 Standard integers and floating point |

:C++26 | C++26 Standard integers and floating point |

:COMMON-LISP | Common Lisp ratios, integers and floating point |

:COMMON-LISP/CCL | Common Lisp including CCL infinity and NaN extensions |

:FORTRAN | Fortran integers and floating point |

:JSON | JSON integers and floating point |

:PYTHON | Python integers and floating point |

### parse-number

`(parse-number string &key (start 0) (end (length string)) (base 10) junk-allowed (integer t) (ratio t) (float t) float-type (style :common-lisp) (whitespace '(#\space #\tab #\page #\newline #\return))) ;; => number, position`

Parse a number from STRING. START and END specify a substring of STRING.

The initial number base is determined by BASE. Some values of STYLE
allow number prefixes that can change the default base. For example,
the C styles will parse hexadecimal numbers via the prefix `0x`

if
that is permitted by the specific standard.

JUNK-ALLOWED determines if trailing non-whitespace is permitted.

INTEGER, RATIO, and FLOAT are booleans that control whether to read integers, fractions or floating point numbers. By default all of these are non-NIL so if the specific style supports it than any one of these numbers will be parsed.

The default floating type is determined by FLOAT-TYPE. Some styles, for example Common Lisp, have the ability to specify the floating point type using the exponent marker or a type suffix.

WHITESPACE is a character bag or a predicate function that is used to skip over whitespace before the number. It is also used to determine if there is trailing junk after the number.

NUMBER is the result of parsing.

POSITION the index to the end of the number in STRING.

#### Examples

```
CL-USER> (asdf:load-system "quaviver/stream")
T
CL-USER> (quaviver/stream:parse-number " 3.1415926535897932384626433832795028841971d0")
3.141592653589793d0
46
CL-USER> (quaviver/stream:parse-number " 314")
314
5
CL-USER> (quaviver/stream:parse-number " 0xfa" :style :c99)
250
6
CL-USER> (quaviver/stream:parse-number " 0xfa.e10" :style :c99)
; Evaluation aborted on #<QUAVIVER.CONDITION:INVALID-CHARACTER-ERROR {1002EF2FA3}>.
CL-USER> (quaviver/stream:parse-number " 0xfa.e10" :style :c++20)
700.0d0
10
```

### read-number

`(read-number stream &key (base 10) junk-allowed (integer t) (ratio t) (float t) float-type (style :common-lisp) (whitespace '(#\space #\tab #\page #\newline #\return))) ;; => number`

READ-NUMBER is identical to PARSE-NUMBER, except that it reads the number from a stream versus a string.

### write-number

`(write-number value stream &key (base 10) (style :common-lisp))`

WRITE-NUMBER writes VALUE to STREAM. BASE and STYLE have the same meanings as in PARSE-NUMBER.