You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
418 lines
14 KiB
418 lines
14 KiB
<HTML>
|
|
<HEAD>
|
|
<!-- Created by texi2html 1.56k from cln.texi on 14 January 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="SEC43" HREF="cln_toc.html#TOC43">5. Input/Output</A></H1>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC44" HREF="cln_toc.html#TOC44">5.1 Internal and printed representation</A></H2>
|
|
|
|
<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",
|
|
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: <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 >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="SEC45" HREF="cln_toc.html#TOC45">5.2 Input functions</A></H2>
|
|
|
|
<P>
|
|
Including <CODE><cl_io.h></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&</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><cl_<VAR>type</VAR>_io.h></CODE>, the following input function:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_istream operator>> (cl_istream stream, <VAR>type</VAR>& 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><cl_<VAR>type</VAR>_io.h></CODE>,
|
|
are the following:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags& flags)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags& flags)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags& flags)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags& 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& 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& 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& 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& 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& 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="SEC46" HREF="cln_toc.html#TOC46">5.3 Output functions</A></H2>
|
|
|
|
<P>
|
|
Including <CODE><cl_io.h></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&</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& 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& 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& 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& 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><cl_<VAR>type</VAR>_io.h></CODE>, the following output functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_ostream operator<< (cl_ostream stream, const <VAR>type</VAR>& 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><cl_<VAR>type</VAR>_io.h></CODE>,
|
|
are the following:
|
|
|
|
<PRE>
|
|
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);
|
|
</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>
|