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 `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 <cln/io.h> defines a type cl_istream, which is the type of the first argument to all input functions. cl_istream is the same as std::istream&.

The variable

cl_istream 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, in <cln/type_io.h>, 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 <cln/type_io.h>, are the following:

cl_N read_complex (cl_istream stream, const cl_read_flags& flags)
cl_R read_real (cl_istream stream, const cl_read_flags& flags)
cl_F read_float (cl_istream stream, const cl_read_flags& flags)
cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)
cl_I read_integer (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_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.

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'.

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 type cl_ostream, which is the type of the first argument to all output functions. cl_ostream is the same as std::ostream&.

The variable

cl_ostream stdout

contains the standard output stream.

The variable

cl_ostream 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 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.

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 (cl_ostream stream, const type& x)
cl_ostream operator<< (cl_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  (cl_ostream stream, const cl_print_flags& flags,
                     const cl_N& z);
void print_real     (cl_ostream stream, const cl_print_flags& flags,
                     const cl_R& z);
void print_float    (cl_ostream stream, const cl_print_flags& flags,
                     const cl_F& z);
void print_rational (cl_ostream stream, const cl_print_flags& flags,
                     const cl_RA& z);
void print_integer  (cl_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.
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 default_print_flags contains the default values, used by the function fprint.

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