cln_mirror/doc/cln_5.html

<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from cln.texi on 19 May 2000 -->

<TITLE>CLN, a Class Library for Numbers - 5. Input/Output</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_4.html">previous</A>, <A HREF="cln_6.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC44" HREF="cln_toc.html#TOC44">5. Input/Output</A></H1>
<P>
<A NAME="IDX236"></A>


<H2><A NAME="SEC45" HREF="cln_toc.html#TOC45">5.1 Internal and printed representation</A></H2>
<P>
<A NAME="IDX237"></A>


<P>
All computations deal with the internal representations of the numbers.


<P>
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".


<P>
Converting an internal to an external representation is called "printing",
<A NAME="IDX238"></A>
converting an external to an internal representation is called "reading".
<A NAME="IDX239"></A>
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: <CODE>read(print(x)) == x</CODE>.
This is called "print-read consistency". 


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


<DL COMPACT>

<DT>Integers
<DD>
External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+. The reader also accepts the
Common Lisp syntaxes <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>.</CODE> with a trailing dot
for decimal integers
and the <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes.

<DT>Rational numbers
<DD>
External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>/</CODE>{<VAR>digit</VAR>}+.
The <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes are allowed
here as well.

<DT>Floating-point numbers
<DD>
External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
<VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
<VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}+. A precision specifier
of the form _<VAR>prec</VAR> may be appended. There must be at least
one digit in the non-exponent part. The exponent has the syntax
<VAR>expmarker</VAR> <VAR>expsign</VAR> {<VAR>digit</VAR>}+.
The exponent marker is


<UL>
<LI>

<SAMP>`s'</SAMP> for short-floats,
<LI>

<SAMP>`f'</SAMP> for single-floats,
<LI>

<SAMP>`d'</SAMP> for double-floats,
<LI>

<SAMP>`L'</SAMP> for long-floats,
</UL>

or <SAMP>`e'</SAMP>, which denotes a default float format. The precision specifying
suffix has the syntax _<VAR>prec</VAR> where <VAR>prec</VAR> denotes the number of
valid mantissa digits (in decimal, excluding leading zeroes), cf. also
function <SAMP>`cl_float_format'</SAMP>.

<DT>Complex numbers
<DD>
External representation:

<UL>
<LI>

In algebraic notation: <CODE><VAR>realpart</VAR>+<VAR>imagpart</VAR>i</CODE>. Of course,
if <VAR>imagpart</VAR> is negative, its printed representation begins with
a <SAMP>`-'</SAMP>, and the <SAMP>`+'</SAMP> between <VAR>realpart</VAR> and <VAR>imagpart</VAR>
may be omitted. Note that this notation cannot be used when the <VAR>imagpart</VAR>
is rational and the rational number's base is &#62;18, because the <SAMP>`i'</SAMP>
is then read as a digit.
<LI>

In Common Lisp notation: <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>.
</UL>

</DL>


<H2><A NAME="SEC46" HREF="cln_toc.html#TOC46">5.2 Input functions</A></H2>

<P>
Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_istream</CODE>, which is
the type of the first argument to all input functions. Unless you build
and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_istream</CODE>
is the same as <CODE>istream&#38;</CODE>.


<P>
The variable

<UL>
<LI>

<CODE>cl_istream cl_stdin</CODE>
</UL>

<P>
contains the standard input stream.


<P>
These are the simple input functions:


<DL COMPACT>

<DT><CODE>int freadchar (cl_istream stream)</CODE>
<DD>
Reads a character from <CODE>stream</CODE>. Returns <CODE>cl_EOF</CODE> (not a <SAMP>`char'</SAMP>!)
if the end of stream was encountered or an error occurred.

<DT><CODE>int funreadchar (cl_istream stream, int c)</CODE>
<DD>
Puts back <CODE>c</CODE> onto <CODE>stream</CODE>. <CODE>c</CODE> must be the result of the
last <CODE>freadchar</CODE> operation on <CODE>stream</CODE>.
</DL>

<P>
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following input function:


<DL COMPACT>

<DT><CODE>cl_istream operator&#62;&#62; (cl_istream stream, <VAR>type</VAR>&#38; result)</CODE>
<DD>
Reads a number from <CODE>stream</CODE> and stores it in the <CODE>result</CODE>.
</DL>

<P>
The most flexible input functions, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
are the following:


<DL COMPACT>

<DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
<DD>
<DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
<DD>
<DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
<DD>
<DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
<DD>
<DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
<DD>
Reads a number from <CODE>stream</CODE>. The <CODE>flags</CODE> are parameters which
affect the input syntax. Whitespace before the number is silently skipped.

<DT><CODE>cl_N read_complex (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
<DD>
<DT><CODE>cl_R read_real (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
<DD>
<DT><CODE>cl_F read_float (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
<DD>
<DT><CODE>cl_RA read_rational (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
<DD>
<DT><CODE>cl_I read_integer (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
<DD>
Reads a number from a string in memory. The <CODE>flags</CODE> are parameters which
affect the input syntax. The string starts at <CODE>string</CODE> and ends at
<CODE>string_limit</CODE> (exclusive limit). <CODE>string_limit</CODE> may also be
<CODE>NULL</CODE>, denoting the entire string, i.e. equivalent to
<CODE>string_limit = string + strlen(string)</CODE>. If <CODE>end_of_parse</CODE> is
<CODE>NULL</CODE>, the string in memory must contain exactly one number and nothing
more, else a fatal error will be signalled. If <CODE>end_of_parse</CODE>
is not <CODE>NULL</CODE>, <CODE>*end_of_parse</CODE> will be assigned a pointer past
the last parsed character (i.e. <CODE>string_limit</CODE> if nothing came after
the number). Whitespace is not allowed.
</DL>

<P>
The structure <CODE>cl_read_flags</CODE> contains the following fields:


<DL COMPACT>

<DT><CODE>cl_read_syntax_t syntax</CODE>
<DD>
The possible results of the read operation. Possible values are
<CODE>syntax_number</CODE>, <CODE>syntax_real</CODE>, <CODE>syntax_rational</CODE>,
<CODE>syntax_integer</CODE>, <CODE>syntax_float</CODE>, <CODE>syntax_sfloat</CODE>,
<CODE>syntax_ffloat</CODE>, <CODE>syntax_dfloat</CODE>, <CODE>syntax_lfloat</CODE>.

<DT><CODE>cl_read_lsyntax_t lsyntax</CODE>
<DD>
Specifies the language-dependent syntax variant for the read operation.
Possible values are

<DL COMPACT>

<DT><CODE>lsyntax_standard</CODE>
<DD>
accept standard algebraic notation only, no complex numbers,
<DT><CODE>lsyntax_algebraic</CODE>
<DD>
accept the algebraic notation <CODE><VAR>x</VAR>+<VAR>y</VAR>i</CODE> for complex numbers,
<DT><CODE>lsyntax_commonlisp</CODE>
<DD>
accept the <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> syntaxes for binary, octal,
hexadecimal numbers,
<CODE>#<VAR>base</VAR>R</CODE> for rational numbers in a given base,
<CODE>#c(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE> for complex numbers,
<DT><CODE>lsyntax_all</CODE>
<DD>
accept all of these extensions.
</DL>

<DT><CODE>unsigned int rational_base</CODE>
<DD>
The base in which rational numbers are read.

<DT><CODE>cl_float_format_t float_flags.default_float_format</CODE>
<DD>
The float format used when reading floats with exponent marker <SAMP>`e'</SAMP>.

<DT><CODE>cl_float_format_t float_flags.default_lfloat_format</CODE>
<DD>
The float format used when reading floats with exponent marker <SAMP>`l'</SAMP>.

<DT><CODE>cl_boolean float_flags.mantissa_dependent_float_format</CODE>
<DD>
When this flag is true, floats specified with more digits than corresponding
to the exponent marker they contain, but without <VAR>_nnn</VAR> suffix, will get a
precision corresponding to their number of significant digits.
</DL>


<H2><A NAME="SEC47" HREF="cln_toc.html#TOC47">5.3 Output functions</A></H2>

<P>
Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_ostream</CODE>, which is
the type of the first argument to all output functions. Unless you build
and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_ostream</CODE>
is the same as <CODE>ostream&#38;</CODE>.


<P>
The variable

<UL>
<LI>

<CODE>cl_ostream cl_stdout</CODE>
</UL>

<P>
contains the standard output stream.


<P>
The variable

<UL>
<LI>

<CODE>cl_ostream cl_stderr</CODE>
</UL>

<P>
contains the standard error output stream.


<P>
These are the simple output functions:


<DL COMPACT>

<DT><CODE>void fprintchar (cl_ostream stream, char c)</CODE>
<DD>
Prints the character <CODE>x</CODE> literally on the <CODE>stream</CODE>.

<DT><CODE>void fprint (cl_ostream stream, const char * string)</CODE>
<DD>
Prints the <CODE>string</CODE> literally on the <CODE>stream</CODE>.

<DT><CODE>void fprintdecimal (cl_ostream stream, int x)</CODE>
<DD>
<DT><CODE>void fprintdecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
<DD>
Prints the integer <CODE>x</CODE> in decimal on the <CODE>stream</CODE>.

<DT><CODE>void fprintbinary (cl_ostream stream, const cl_I&#38; x)</CODE>
<DD>
Prints the integer <CODE>x</CODE> in binary (base 2, without prefix)
on the <CODE>stream</CODE>.

<DT><CODE>void fprintoctal (cl_ostream stream, const cl_I&#38; x)</CODE>
<DD>
Prints the integer <CODE>x</CODE> in octal (base 8, without prefix)
on the <CODE>stream</CODE>.

<DT><CODE>void fprinthexadecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
<DD>
Prints the integer <CODE>x</CODE> in hexadecimal (base 16, without prefix)
on the <CODE>stream</CODE>.
</DL>

<P>
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following output functions:


<DL COMPACT>

<DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
<DD>
<DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
<DD>
Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
The <CODE>ostream</CODE> flags and settings (flags, width and locale) are
ignored.
</DL>

<P>
The most flexible output function, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
are the following:

<PRE>
void print_complex  (cl_ostream stream, const cl_print_flags&#38; flags,
                     const cl_N&#38; z);
void print_real     (cl_ostream stream, const cl_print_flags&#38; flags,
                     const cl_R&#38; z);
void print_float    (cl_ostream stream, const cl_print_flags&#38; flags,
                     const cl_F&#38; z);
void print_rational (cl_ostream stream, const cl_print_flags&#38; flags,
                     const cl_RA&#38; z);
void print_integer  (cl_ostream stream, const cl_print_flags&#38; flags,
                     const cl_I&#38; z);
</PRE>

<P>
Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The <CODE>flags</CODE> are
parameters which affect the output.


<P>
The structure type <CODE>cl_print_flags</CODE> contains the following fields:


<DL COMPACT>

<DT><CODE>unsigned int rational_base</CODE>
<DD>
The base in which rational numbers are printed. Default is <CODE>10</CODE>.

<DT><CODE>cl_boolean rational_readably</CODE>
<DD>
If this flag is true, rational numbers are printed with radix specifiers in
Common Lisp syntax (<CODE>#<VAR>n</VAR>R</CODE> or <CODE>#b</CODE> or <CODE>#o</CODE> or <CODE>#x</CODE>
prefixes, trailing dot). Default is false.

<DT><CODE>cl_boolean float_readably</CODE>
<DD>
If this flag is true, type specific exponent markers have precedence over 'E'.
Default is false.

<DT><CODE>cl_float_format_t default_float_format</CODE>
<DD>
Floating point numbers of this format will be printed using the 'E' exponent
marker. Default is <CODE>cl_float_format_ffloat</CODE>.

<DT><CODE>cl_boolean complex_readably</CODE>
<DD>
If this flag is true, complex numbers will be printed using the Common Lisp
syntax <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>. Default is false.

<DT><CODE>cl_string univpoly_varname</CODE>
<DD>
Univariate polynomials with no explicit indeterminate name will be printed
using this variable name. Default is <CODE>"x"</CODE>.
</DL>

<P>
The global variable <CODE>cl_default_print_flags</CODE> contains the default values,
used by the function <CODE>fprint</CODE>.


<P><HR><P>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_4.html">previous</A>, <A HREF="cln_6.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
</BODY>
</HTML>