CLN, a Class Library for Numbers - 5 Input/Output

Go to the first, previous, next, last section, table of contents.

# 5 Input/Output

## 5.1 Internal and printed representation

All computations deal with the internal representations of the numbers.

Every number has an external representation as a sequence of ASCII characters. Several external representations may denote the same number, for example, "20.0" and "20.000".

Converting an internal to an external representation is called "printing", converting an external to an internal representation is called "reading". In CLN, is it always true that conversion of an internal to an external representation and then back to an internal representation will yield the same internal representation. Symbolically: `read(print(x)) == x`. This is called "print-read consistency".

Different types of numbers have different external representations (case is insignificant):

Integers
  External representation: sign{digit}+. The reader also accepts the Common Lisp syntaxes sign{digit}+`.` with a trailing dot for decimal integers and the `#nR`, `#b`, `#o`, `#x` prefixes.
Rational numbers
  External representation: sign{digit}+`/`{digit}+. The `#nR`, `#b`, `#o`, `#x` prefixes are allowed here as well.
Floating-point numbers
  External representation: sign{digit}*exponent or sign{digit}*`.`{digit}*exponent or sign{digit}*`.`{digit}+. A precision specifier of the form _prec may be appended. There must be at least one digit in the non-exponent part. The exponent has the syntax expmarker expsign {digit}+. The exponent marker is
  - ``s'` for short-floats,
  - ``f'` for single-floats,
  - ``d'` for double-floats,
  - ``L'` for long-floats,
  or ``e'`, which denotes a default float format. The precision specifying suffix has the syntax _prec where prec denotes the number of valid mantissa digits (in decimal, excluding leading zeroes), cf. also function ``cl_float_format'`.
Complex numbers
  External representation:
  - In algebraic notation: `realpart+imagparti`. Of course, if imagpart is negative, its printed representation begins with a ``-'`, and the ``+'` between realpart and imagpart may be omitted. Note that this notation cannot be used when the imagpart is rational and the rational number's base is >18, because the ``i'` is then read as a digit.
  - In Common Lisp notation: `#C(realpart imagpart)`.

## 5.2 Input functions

Including `<cl_io.h>` defines a type `cl_istream`, which is the type of the first argument to all input functions.

The variable

- `cl_istream cl_stdin`

contains the standard input stream.

These are the simple input functions:

`int freadchar (cl_istream stream)`
  Reads a character from `stream`. Returns `cl_EOF` (not a ``char'`!) if the end of stream was encountered or an error occurred.
`int funreadchar (cl_istream stream, int c)`
  Puts back `c` onto `stream`. `c` must be the result of the last `freadchar` operation on `stream`.

Each of the classes `cl_N`, `cl_R`, `cl_RA`, `cl_I`, `cl_F`, `cl_SF`, `cl_FF`, `cl_DF`, `cl_LF` defines the following input function:

`cl_istream operator>> (cl_istream stream, type& result)`
  Reads a number from `stream` and stores it in the `result`.

The most flexible input functions, defined in `<cl_input.h>`, are the following:

`cl_number read_number (cl_istream stream, const cl_read_flags& flags)`
  Reads a number from `stream`. The `flags` are parameters which affect the input syntax. Whitespace before the number is silently skipped.
`cl_number read_number (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)`
  Reads a number from a string in memory. The `flags` are parameters which affect the input syntax. The string starts at `string` and ends at `string_limit` (exclusive limit). `string_limit` may also be `NULL`, denoting the entire string, i.e. equivalent to `string_limit = string + strlen(string)`. If `end_of_parse` is `NULL`, the string in memory must contain exactly one number and nothing more, else a fatal error will be signalled. If `end_of_parse` is not `NULL`, `*end_of_parse` will be assigned a pointer past the last parsed character (i.e. `string_limit` if nothing came after the number). Whitespace is not allowed.

The structure `cl_read_flags` contains the following fields:

`cl_read_syntax_t syntax`
  The possible results of the read operation. Possible values are `syntax_number`, `syntax_real`, `syntax_rational`, `syntax_integer`, `syntax_float`, `syntax_sfloat`, `syntax_ffloat`, `syntax_dfloat`, `syntax_lfloat`.
`cl_read_lsyntax_t lsyntax`
  Specifies the language-dependent syntax variant for the read operation. Possible values are
  `lsyntax_standard`
    accept standard algebraic notation only, no complex numbers,
  `lsyntax_algebraic`
    accept the algebraic notation `x+yi` for complex numbers,
  `lsyntax_commonlisp`
    accept the `#b`, `#o`, `#x` syntaxes for binary, octal, hexadecimal numbers, `#baseR` for rational numbers in a given base, `#c(realpart imagpart)` for complex numbers,
  `lsyntax_all`
    accept all of these extensions.
`unsigned int rational_base`
  The base in which rational numbers are read.
`cl_float_format_t float_flags.default_float_format`
  The float format used when reading floats with exponent marker ``e'`.
`cl_float_format_t float_flags.default_lfloat_format`
  The float format used when reading floats with exponent marker ``l'`.

## 5.3 Output functions

Including `<cl_io.h>` defines a type `cl_ostream`, which is the type of the first argument to all output functions.

The variable

- `cl_ostream cl_stdout`

contains the standard output stream.

The variable

- `cl_ostream cl_stderr`

contains the standard error output stream.

These are the simple output functions:

`void fprintchar (cl_ostream stream, char c)`
  Prints the character `x` literally on the `stream`.
`void fprint (cl_ostream stream, const char * string)`
  Prints the `string` literally on the `stream`.
`void fprint (cl_ostream stream, const cl_number& x)`
`cl_ostream operator<< (cl_ostream stream, const cl_number& x)`
  Prints the number `x` on the `stream`. The output may depend on the global printer settings in the variable `cl_default_print_flags`.
`void fprintdecimal (cl_ostream stream, int x)`
`void fprintdecimal (cl_ostream stream, const cl_I& x)`
  Prints the integer `x` in decimal on the `stream`.
`void fprintbinary (cl_ostream stream, const cl_I& x)`
  Prints the integer `x` in binary (base 2, without prefix) on the `stream`.
`void fprintoctal (cl_ostream stream, const cl_I& x)`
  Prints the integer `x` in octal (base 8, without prefix) on the `stream`.
`void fprinthexadecimal (cl_ostream stream, const cl_I& x)`
  Prints the integer `x` in hexadecimal (base 16, without prefix) on the `stream`.

The most flexible output function, defined in `<cl_output.h>`, is the following:

    void print_number (cl_ostream stream, const cl_print_flags& flags,
                       const cl_number& z);

Prints the number `x` on the `stream`. The `flags` are parameters which affect the output.

The structure type `cl_print_flags` contains the following fields:

`unsigned int rational_base`
  The base in which rational numbers are printed. Default is `10`.
`cl_boolean rational_readably`
  If this flag is true, rational numbers are printed with radix specifiers in Common Lisp syntax (`#nR` or `#b` or `#o` or `#x` prefixes, trailing dot). Default is false.
`cl_boolean float_readably`
  If this flag is true, type specific exponent markers have precedence over 'E'. Default is false.
`cl_float_format_t default_float_format`
  Floating point numbers of this format will be printed using the 'E' exponent marker. Default is `cl_float_format_ffloat`.
`cl_boolean complex_readably`
  If this flag is true, complex numbers will be printed using the Common Lisp syntax `#C(realpart imagpart)`. Default is false.
`cl_string univpoly_varname`
  Univariate polynomials with no explicit indeterminate name will be printed using this variable name. Default is `"x"`.

The global variable `cl_default_print_flags` contains the default values, used by the function `fprint`,

Go to the first, previous, next, last section, table of contents.