doc/cln_5.html

   1 <HTML>
   2 <HEAD>
   3 <!-- Created by texi2html 1.56k from cln.texi on 5 May 2000 -->
   4
   5 <TITLE>CLN, a Class Library for Numbers - 5. Input/Output</TITLE>
   6 </HEAD>
   7 <BODY>
   8 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>.
   9 <P><HR><P>
  10
  11
  12 <H1><A NAME="SEC44" HREF="cln_toc.html#TOC44">5. Input/Output</A></H1>
  13 <P>
  14 <A NAME="IDX236"></A>
  15
  16
  17
  18
  19 <H2><A NAME="SEC45" HREF="cln_toc.html#TOC45">5.1 Internal and printed representation</A></H2>
  20 <P>
  21 <A NAME="IDX237"></A>
  22
  23
  24 <P>
  25 All computations deal with the internal representations of the numbers.
  26
  27
  28 <P>
  29 Every number has an external representation as a sequence of ASCII characters.
  30 Several external representations may denote the same number, for example,
  31 "20.0" and "20.000".
  32
  33
  34 <P>
  35 Converting an internal to an external representation is called "printing",
  36 <A NAME="IDX238"></A>
  37 converting an external to an internal representation is called "reading".
  38 <A NAME="IDX239"></A>
  39 In CLN, it is always true that conversion of an internal to an external
  40 representation and then back to an internal representation will yield the
  41 same internal representation. Symbolically: <CODE>read(print(x)) == x</CODE>.
  42 This is called "print-read consistency".
  43
  44
  45 <P>
  46 Different types of numbers have different external representations (case
  47 is insignificant):
  48
  49
  50 <DL COMPACT>
  51
  52 <DT>Integers
  53 <DD>
  54 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+. The reader also accepts the
  55 Common Lisp syntaxes <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>.</CODE> with a trailing dot
  56 for decimal integers
  57 and the <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes.
  58
  59 <DT>Rational numbers
  60 <DD>
  61 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>/</CODE>{<VAR>digit</VAR>}+.
  62 The <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes are allowed
  63 here as well.
  64
  65 <DT>Floating-point numbers
  66 <DD>
  67 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
  68 <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
  69 <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}+. A precision specifier
  70 of the form _<VAR>prec</VAR> may be appended. There must be at least
  71 one digit in the non-exponent part. The exponent has the syntax
  72 <VAR>expmarker</VAR> <VAR>expsign</VAR> {<VAR>digit</VAR>}+.
  73 The exponent marker is
  74
  75
  76 <UL>
  77 <LI>
  78
  79 <SAMP>`s'</SAMP> for short-floats,
  80 <LI>
  81
  82 <SAMP>`f'</SAMP> for single-floats,
  83 <LI>
  84
  85 <SAMP>`d'</SAMP> for double-floats,
  86 <LI>
  87
  88 <SAMP>`L'</SAMP> for long-floats,
  89 </UL>
  90
  91 or <SAMP>`e'</SAMP>, which denotes a default float format. The precision specifying
  92 suffix has the syntax _<VAR>prec</VAR> where <VAR>prec</VAR> denotes the number of
  93 valid mantissa digits (in decimal, excluding leading zeroes), cf. also
  94 function <SAMP>`cl_float_format'</SAMP>.
  95
  96 <DT>Complex numbers
  97 <DD>
  98 External representation:
  99
 100 <UL>
 101 <LI>
 102
 103 In algebraic notation: <CODE><VAR>realpart</VAR>+<VAR>imagpart</VAR>i</CODE>. Of course,
 104 if <VAR>imagpart</VAR> is negative, its printed representation begins with
 105 a <SAMP>`-'</SAMP>, and the <SAMP>`+'</SAMP> between <VAR>realpart</VAR> and <VAR>imagpart</VAR>
 106 may be omitted. Note that this notation cannot be used when the <VAR>imagpart</VAR>
 107 is rational and the rational number's base is &#62;18, because the <SAMP>`i'</SAMP>
 108 is then read as a digit.
 109 <LI>
 110
 111 In Common Lisp notation: <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>.
 112 </UL>
 113
 114 </DL>
 115
 116
 117
 118 <H2><A NAME="SEC46" HREF="cln_toc.html#TOC46">5.2 Input functions</A></H2>
 119
 120 <P>
 121 Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_istream</CODE>, which is
 122 the type of the first argument to all input functions. Unless you build
 123 and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_istream</CODE>
 124 is the same as <CODE>istream&#38;</CODE>.
 125
 126
 127 <P>
 128 The variable
 129
 130 <UL>
 131 <LI>
 132
 133 <CODE>cl_istream cl_stdin</CODE>
 134 </UL>
 135
 136 <P>
 137 contains the standard input stream.
 138
 139
 140 <P>
 141 These are the simple input functions:
 142
 143
 144 <DL COMPACT>
 145
 146 <DT><CODE>int freadchar (cl_istream stream)</CODE>
 147 <DD>
 148 Reads a character from <CODE>stream</CODE>. Returns <CODE>cl_EOF</CODE> (not a <SAMP>`char'</SAMP>!)
 149 if the end of stream was encountered or an error occurred.
 150
 151 <DT><CODE>int funreadchar (cl_istream stream, int c)</CODE>
 152 <DD>
 153 Puts back <CODE>c</CODE> onto <CODE>stream</CODE>. <CODE>c</CODE> must be the result of the
 154 last <CODE>freadchar</CODE> operation on <CODE>stream</CODE>.
 155 </DL>
 156
 157 <P>
 158 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
 159 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
 160 defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following input function:
 161
 162
 163 <DL COMPACT>
 164
 165 <DT><CODE>cl_istream operator&#62;&#62; (cl_istream stream, <VAR>type</VAR>&#38; result)</CODE>
 166 <DD>
 167 Reads a number from <CODE>stream</CODE> and stores it in the <CODE>result</CODE>.
 168 </DL>
 169
 170 <P>
 171 The most flexible input functions, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
 172 are the following:
 173
 174
 175 <DL COMPACT>
 176
 177 <DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 178 <DD>
 179 <DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 180 <DD>
 181 <DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 182 <DD>
 183 <DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 184 <DD>
 185 <DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 186 <DD>
 187 Reads a number from <CODE>stream</CODE>. The <CODE>flags</CODE> are parameters which
 188 affect the input syntax. Whitespace before the number is silently skipped.
 189
 190 <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>
 191 <DD>
 192 <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>
 193 <DD>
 194 <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>
 195 <DD>
 196 <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>
 197 <DD>
 198 <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>
 199 <DD>
 200 Reads a number from a string in memory. The <CODE>flags</CODE> are parameters which
 201 affect the input syntax. The string starts at <CODE>string</CODE> and ends at
 202 <CODE>string_limit</CODE> (exclusive limit). <CODE>string_limit</CODE> may also be
 203 <CODE>NULL</CODE>, denoting the entire string, i.e. equivalent to
 204 <CODE>string_limit = string + strlen(string)</CODE>. If <CODE>end_of_parse</CODE> is
 205 <CODE>NULL</CODE>, the string in memory must contain exactly one number and nothing
 206 more, else a fatal error will be signalled. If <CODE>end_of_parse</CODE>
 207 is not <CODE>NULL</CODE>, <CODE>*end_of_parse</CODE> will be assigned a pointer past
 208 the last parsed character (i.e. <CODE>string_limit</CODE> if nothing came after
 209 the number). Whitespace is not allowed.
 210 </DL>
 211
 212 <P>
 213 The structure <CODE>cl_read_flags</CODE> contains the following fields:
 214
 215
 216 <DL COMPACT>
 217
 218 <DT><CODE>cl_read_syntax_t syntax</CODE>
 219 <DD>
 220 The possible results of the read operation. Possible values are
 221 <CODE>syntax_number</CODE>, <CODE>syntax_real</CODE>, <CODE>syntax_rational</CODE>,
 222 <CODE>syntax_integer</CODE>, <CODE>syntax_float</CODE>, <CODE>syntax_sfloat</CODE>,
 223 <CODE>syntax_ffloat</CODE>, <CODE>syntax_dfloat</CODE>, <CODE>syntax_lfloat</CODE>.
 224
 225 <DT><CODE>cl_read_lsyntax_t lsyntax</CODE>
 226 <DD>
 227 Specifies the language-dependent syntax variant for the read operation.
 228 Possible values are
 229
 230 <DL COMPACT>
 231
 232 <DT><CODE>lsyntax_standard</CODE>
 233 <DD>
 234 accept standard algebraic notation only, no complex numbers,
 235 <DT><CODE>lsyntax_algebraic</CODE>
 236 <DD>
 237 accept the algebraic notation <CODE><VAR>x</VAR>+<VAR>y</VAR>i</CODE> for complex numbers,
 238 <DT><CODE>lsyntax_commonlisp</CODE>
 239 <DD>
 240 accept the <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> syntaxes for binary, octal,
 241 hexadecimal numbers,
 242 <CODE>#<VAR>base</VAR>R</CODE> for rational numbers in a given base,
 243 <CODE>#c(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE> for complex numbers,
 244 <DT><CODE>lsyntax_all</CODE>
 245 <DD>
 246 accept all of these extensions.
 247 </DL>
 248
 249 <DT><CODE>unsigned int rational_base</CODE>
 250 <DD>
 251 The base in which rational numbers are read.
 252
 253 <DT><CODE>cl_float_format_t float_flags.default_float_format</CODE>
 254 <DD>
 255 The float format used when reading floats with exponent marker <SAMP>`e'</SAMP>.
 256
 257 <DT><CODE>cl_float_format_t float_flags.default_lfloat_format</CODE>
 258 <DD>
 259 The float format used when reading floats with exponent marker <SAMP>`l'</SAMP>.
 260
 261 <DT><CODE>cl_boolean float_flags.mantissa_dependent_float_format</CODE>
 262 <DD>
 263 When this flag is true, floats specified with more digits than corresponding
 264 to the exponent marker they contain, but without <VAR>_nnn</VAR> suffix, will get a
 265 precision corresponding to their number of significant digits.
 266 </DL>
 267
 268
 269
 270 <H2><A NAME="SEC47" HREF="cln_toc.html#TOC47">5.3 Output functions</A></H2>
 271
 272 <P>
 273 Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_ostream</CODE>, which is
 274 the type of the first argument to all output functions. Unless you build
 275 and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_ostream</CODE>
 276 is the same as <CODE>ostream&#38;</CODE>.
 277
 278
 279 <P>
 280 The variable
 281
 282 <UL>
 283 <LI>
 284
 285 <CODE>cl_ostream cl_stdout</CODE>
 286 </UL>
 287
 288 <P>
 289 contains the standard output stream.
 290
 291
 292 <P>
 293 The variable
 294
 295 <UL>
 296 <LI>
 297
 298 <CODE>cl_ostream cl_stderr</CODE>
 299 </UL>
 300
 301 <P>
 302 contains the standard error output stream.
 303
 304
 305 <P>
 306 These are the simple output functions:
 307
 308
 309 <DL COMPACT>
 310
 311 <DT><CODE>void fprintchar (cl_ostream stream, char c)</CODE>
 312 <DD>
 313 Prints the character <CODE>x</CODE> literally on the <CODE>stream</CODE>.
 314
 315 <DT><CODE>void fprint (cl_ostream stream, const char * string)</CODE>
 316 <DD>
 317 Prints the <CODE>string</CODE> literally on the <CODE>stream</CODE>.
 318
 319 <DT><CODE>void fprintdecimal (cl_ostream stream, int x)</CODE>
 320 <DD>
 321 <DT><CODE>void fprintdecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
 322 <DD>
 323 Prints the integer <CODE>x</CODE> in decimal on the <CODE>stream</CODE>.
 324
 325 <DT><CODE>void fprintbinary (cl_ostream stream, const cl_I&#38; x)</CODE>
 326 <DD>
 327 Prints the integer <CODE>x</CODE> in binary (base 2, without prefix)
 328 on the <CODE>stream</CODE>.
 329
 330 <DT><CODE>void fprintoctal (cl_ostream stream, const cl_I&#38; x)</CODE>
 331 <DD>
 332 Prints the integer <CODE>x</CODE> in octal (base 8, without prefix)
 333 on the <CODE>stream</CODE>.
 334
 335 <DT><CODE>void fprinthexadecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
 336 <DD>
 337 Prints the integer <CODE>x</CODE> in hexadecimal (base 16, without prefix)
 338 on the <CODE>stream</CODE>.
 339 </DL>
 340
 341 <P>
 342 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
 343 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
 344 defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following output functions:
 345
 346
 347 <DL COMPACT>
 348
 349 <DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
 350 <DD>
 351 <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
 352 <DD>
 353 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
 354 on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
 355 The <CODE>ostream</CODE> flags and settings (flags, width and locale) are
 356 ignored.
 357 </DL>
 358
 359 <P>
 360 The most flexible output function, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
 361 are the following:
 362
 363 <PRE>
 364 void print_complex  (cl_ostream stream, const cl_print_flags&#38; flags,
 365                      const cl_N&#38; z);
 366 void print_real     (cl_ostream stream, const cl_print_flags&#38; flags,
 367                      const cl_R&#38; z);
 368 void print_float    (cl_ostream stream, const cl_print_flags&#38; flags,
 369                      const cl_F&#38; z);
 370 void print_rational (cl_ostream stream, const cl_print_flags&#38; flags,
 371                      const cl_RA&#38; z);
 372 void print_integer  (cl_ostream stream, const cl_print_flags&#38; flags,
 373                      const cl_I&#38; z);
 374 </PRE>
 375
 376 <P>
 377 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The <CODE>flags</CODE> are
 378 parameters which affect the output.
 379
 380
 381 <P>
 382 The structure type <CODE>cl_print_flags</CODE> contains the following fields:
 383
 384
 385 <DL COMPACT>
 386
 387 <DT><CODE>unsigned int rational_base</CODE>
 388 <DD>
 389 The base in which rational numbers are printed. Default is <CODE>10</CODE>.
 390
 391 <DT><CODE>cl_boolean rational_readably</CODE>
 392 <DD>
 393 If this flag is true, rational numbers are printed with radix specifiers in
 394 Common Lisp syntax (<CODE>#<VAR>n</VAR>R</CODE> or <CODE>#b</CODE> or <CODE>#o</CODE> or <CODE>#x</CODE>
 395 prefixes, trailing dot). Default is false.
 396
 397 <DT><CODE>cl_boolean float_readably</CODE>
 398 <DD>
 399 If this flag is true, type specific exponent markers have precedence over 'E'.
 400 Default is false.
 401
 402 <DT><CODE>cl_float_format_t default_float_format</CODE>
 403 <DD>
 404 Floating point numbers of this format will be printed using the 'E' exponent
 405 marker. Default is <CODE>cl_float_format_ffloat</CODE>.
 406
 407 <DT><CODE>cl_boolean complex_readably</CODE>
 408 <DD>
 409 If this flag is true, complex numbers will be printed using the Common Lisp
 410 syntax <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>. Default is false.
 411
 412 <DT><CODE>cl_string univpoly_varname</CODE>
 413 <DD>
 414 Univariate polynomials with no explicit indeterminate name will be printed
 415 using this variable name. Default is <CODE>"x"</CODE>.
 416 </DL>
 417
 418 <P>
 419 The global variable <CODE>cl_default_print_flags</CODE> contains the default values,
 420 used by the function <CODE>fprint</CODE>.
 421
 422
 423 <P><HR><P>
 424 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>.
 425 </BODY>
 426 </HTML>