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, it is 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 ``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 `<cln/io.h>` defines a number of simple input functions that read from `std::istream&`:

`int freadchar (std::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 (std::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, in `<cln/type_io.h>`, the following input function:

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

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

`cl_N read_complex (std::istream& stream, const cl_read_flags& flags)`
`cl_R read_real (std::istream& stream, const cl_read_flags& flags)`
`cl_F read_float (std::istream& stream, const cl_read_flags& flags)`
`cl_RA read_rational (std::istream& stream, const cl_read_flags& flags)`
`cl_I read_integer (std::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_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)`
`cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)`
`cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)`
`cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)`
`cl_I read_integer (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.
`float_format_t float_flags.default_float_format`
  The float format used when reading floats with exponent marker ``e'`.
`float_format_t float_flags.default_lfloat_format`
  The float format used when reading floats with exponent marker ``l'`.
`cl_boolean float_flags.mantissa_dependent_float_format`
  When this flag is true, floats specified with more digits than corresponding to the exponent marker they contain, but without _nnn suffix, will get a precision corresponding to their number of significant digits.

## 5.3 Output functions

Including `<cln/io.h>` defines a number of simple output functions that write to `std::ostream&`:

`void fprintchar (std::ostream& stream, char c)`
  Prints the character `x` literally on the `stream`.
`void fprint (std::ostream& stream, const char * string)`
  Prints the `string` literally on the `stream`.
`void fprintdecimal (std::ostream& stream, int x)`
`void fprintdecimal (std::ostream& stream, const cl_I& x)`
  Prints the integer `x` in decimal on the `stream`.
`void fprintbinary (std::ostream& stream, const cl_I& x)`
  Prints the integer `x` in binary (base 2, without prefix) on the `stream`.
`void fprintoctal (std::ostream& stream, const cl_I& x)`
  Prints the integer `x` in octal (base 8, without prefix) on the `stream`.
`void fprinthexadecimal (std::ostream& stream, const cl_I& x)`
  Prints the integer `x` in hexadecimal (base 16, without prefix) on the `stream`.

Each of the classes `cl_N`, `cl_R`, `cl_RA`, `cl_I`, `cl_F`, `cl_SF`, `cl_FF`, `cl_DF`, `cl_LF` defines, in `<cln/type_io.h>`, the following output functions:

`void fprint (std::ostream& stream, const type& x)`
`std::ostream& operator<< (std::ostream& stream, const type& x)`
  Prints the number `x` on the `stream`. The output may depend on the global printer settings in the variable `default_print_flags`. The `ostream` flags and settings (flags, width and locale) are ignored.

The most flexible output function, defined in `<cln/type_io.h>`, are the following:

    void print_complex  (std::ostream& stream, const cl_print_flags& flags,
                         const cl_N& z);
    void print_real     (std::ostream& stream, const cl_print_flags& flags,
                         const cl_R& z);
    void print_float    (std::ostream& stream, const cl_print_flags& flags,
                         const cl_F& z);
    void print_rational (std::ostream& stream, const cl_print_flags& flags,
                         const cl_RA& z);
    void print_integer  (std::ostream& stream, const cl_print_flags& flags,
                         const cl_I& 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.
`float_format_t default_float_format`
  Floating point numbers of this format will be printed using the 'E' exponent marker. Default is `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 `default_print_flags` contains the default values, used by the function `fprint`.

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