[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Input/Output

5.1 Internal and printed representation  
5.2 Input functions  
5.3 Output functions  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Richard B. Kreckel on May, 7 2006 using texi2html