doc/cln_5.html

   1 <HTML>
   2 <HEAD>
   3 <!-- Created by texi2html 1.56k from cln.texi on 28 August 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="IDX237"></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="IDX238"></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="IDX239"></A>
  37 converting an external to an internal representation is called "reading".
  38 <A NAME="IDX240"></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;cln/io.h&#62;</CODE> defines a type <CODE>cl_istream</CODE>, which is
 122 the type of the first argument to all input functions. <CODE>cl_istream</CODE>
 123 is the same as <CODE>std::istream&#38;</CODE>.
 124
 125
 126 <P>
 127 The variable
 128
 129 <UL>
 130 <LI>
 131
 132 <CODE>cl_istream stdin</CODE>
 133 </UL>
 134
 135 <P>
 136 contains the standard input stream.
 137
 138
 139 <P>
 140 These are the simple input functions:
 141
 142
 143 <DL COMPACT>
 144
 145 <DT><CODE>int freadchar (cl_istream stream)</CODE>
 146 <DD>
 147 Reads a character from <CODE>stream</CODE>. Returns <CODE>cl_EOF</CODE> (not a <SAMP>`char'</SAMP>!)
 148 if the end of stream was encountered or an error occurred.
 149
 150 <DT><CODE>int funreadchar (cl_istream stream, int c)</CODE>
 151 <DD>
 152 Puts back <CODE>c</CODE> onto <CODE>stream</CODE>. <CODE>c</CODE> must be the result of the
 153 last <CODE>freadchar</CODE> operation on <CODE>stream</CODE>.
 154 </DL>
 155
 156 <P>
 157 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
 158 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
 159 defines, in <CODE>&#60;cln/<VAR>type</VAR>_io.h&#62;</CODE>, the following input function:
 160
 161
 162 <DL COMPACT>
 163
 164 <DT><CODE>cl_istream operator&#62;&#62; (cl_istream stream, <VAR>type</VAR>&#38; result)</CODE>
 165 <DD>
 166 Reads a number from <CODE>stream</CODE> and stores it in the <CODE>result</CODE>.
 167 </DL>
 168
 169 <P>
 170 The most flexible input functions, defined in <CODE>&#60;cln/<VAR>type</VAR>_io.h&#62;</CODE>,
 171 are the following:
 172
 173
 174 <DL COMPACT>
 175
 176 <DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 177 <DD>
 178 <DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 179 <DD>
 180 <DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 181 <DD>
 182 <DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 183 <DD>
 184 <DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
 185 <DD>
 186 Reads a number from <CODE>stream</CODE>. The <CODE>flags</CODE> are parameters which
 187 affect the input syntax. Whitespace before the number is silently skipped.
 188
 189 <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>
 190 <DD>
 191 <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>
 192 <DD>
 193 <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>
 194 <DD>
 195 <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>
 196 <DD>
 197 <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>
 198 <DD>
 199 Reads a number from a string in memory. The <CODE>flags</CODE> are parameters which
 200 affect the input syntax. The string starts at <CODE>string</CODE> and ends at
 201 <CODE>string_limit</CODE> (exclusive limit). <CODE>string_limit</CODE> may also be
 202 <CODE>NULL</CODE>, denoting the entire string, i.e. equivalent to
 203 <CODE>string_limit = string + strlen(string)</CODE>. If <CODE>end_of_parse</CODE> is
 204 <CODE>NULL</CODE>, the string in memory must contain exactly one number and nothing
 205 more, else a fatal error will be signalled. If <CODE>end_of_parse</CODE>
 206 is not <CODE>NULL</CODE>, <CODE>*end_of_parse</CODE> will be assigned a pointer past
 207 the last parsed character (i.e. <CODE>string_limit</CODE> if nothing came after
 208 the number). Whitespace is not allowed.
 209 </DL>
 210
 211 <P>
 212 The structure <CODE>cl_read_flags</CODE> contains the following fields:
 213
 214
 215 <DL COMPACT>
 216
 217 <DT><CODE>cl_read_syntax_t syntax</CODE>
 218 <DD>
 219 The possible results of the read operation. Possible values are
 220 <CODE>syntax_number</CODE>, <CODE>syntax_real</CODE>, <CODE>syntax_rational</CODE>,
 221 <CODE>syntax_integer</CODE>, <CODE>syntax_float</CODE>, <CODE>syntax_sfloat</CODE>,
 222 <CODE>syntax_ffloat</CODE>, <CODE>syntax_dfloat</CODE>, <CODE>syntax_lfloat</CODE>.
 223
 224 <DT><CODE>cl_read_lsyntax_t lsyntax</CODE>
 225 <DD>
 226 Specifies the language-dependent syntax variant for the read operation.
 227 Possible values are
 228
 229 <DL COMPACT>
 230
 231 <DT><CODE>lsyntax_standard</CODE>
 232 <DD>
 233 accept standard algebraic notation only, no complex numbers,
 234 <DT><CODE>lsyntax_algebraic</CODE>
 235 <DD>
 236 accept the algebraic notation <CODE><VAR>x</VAR>+<VAR>y</VAR>i</CODE> for complex numbers,
 237 <DT><CODE>lsyntax_commonlisp</CODE>
 238 <DD>
 239 accept the <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> syntaxes for binary, octal,
 240 hexadecimal numbers,
 241 <CODE>#<VAR>base</VAR>R</CODE> for rational numbers in a given base,
 242 <CODE>#c(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE> for complex numbers,
 243 <DT><CODE>lsyntax_all</CODE>
 244 <DD>
 245 accept all of these extensions.
 246 </DL>
 247
 248 <DT><CODE>unsigned int rational_base</CODE>
 249 <DD>
 250 The base in which rational numbers are read.
 251
 252 <DT><CODE>cl_float_format_t float_flags.default_float_format</CODE>
 253 <DD>
 254 The float format used when reading floats with exponent marker <SAMP>`e'</SAMP>.
 255
 256 <DT><CODE>cl_float_format_t float_flags.default_lfloat_format</CODE>
 257 <DD>
 258 The float format used when reading floats with exponent marker <SAMP>`l'</SAMP>.
 259
 260 <DT><CODE>cl_boolean float_flags.mantissa_dependent_float_format</CODE>
 261 <DD>
 262 When this flag is true, floats specified with more digits than corresponding
 263 to the exponent marker they contain, but without <VAR>_nnn</VAR> suffix, will get a
 264 precision corresponding to their number of significant digits.
 265 </DL>
 266
 267
 268
 269 <H2><A NAME="SEC47" HREF="cln_toc.html#TOC47">5.3 Output functions</A></H2>
 270
 271 <P>
 272 Including <CODE>&#60;cln/io.h&#62;</CODE> defines a type <CODE>cl_ostream</CODE>, which is
 273 the type of the first argument to all output functions. <CODE>cl_ostream</CODE>
 274 is the same as <CODE>std::ostream&#38;</CODE>.
 275
 276
 277 <P>
 278 The variable
 279
 280 <UL>
 281 <LI>
 282
 283 <CODE>cl_ostream stdout</CODE>
 284 </UL>
 285
 286 <P>
 287 contains the standard output stream.
 288
 289
 290 <P>
 291 The variable
 292
 293 <UL>
 294 <LI>
 295
 296 <CODE>cl_ostream stderr</CODE>
 297 </UL>
 298
 299 <P>
 300 contains the standard error output stream.
 301
 302
 303 <P>
 304 These are the simple output functions:
 305
 306
 307 <DL COMPACT>
 308
 309 <DT><CODE>void fprintchar (cl_ostream stream, char c)</CODE>
 310 <DD>
 311 Prints the character <CODE>x</CODE> literally on the <CODE>stream</CODE>.
 312
 313 <DT><CODE>void fprint (cl_ostream stream, const char * string)</CODE>
 314 <DD>
 315 Prints the <CODE>string</CODE> literally on the <CODE>stream</CODE>.
 316
 317 <DT><CODE>void fprintdecimal (cl_ostream stream, int x)</CODE>
 318 <DD>
 319 <DT><CODE>void fprintdecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
 320 <DD>
 321 Prints the integer <CODE>x</CODE> in decimal on the <CODE>stream</CODE>.
 322
 323 <DT><CODE>void fprintbinary (cl_ostream stream, const cl_I&#38; x)</CODE>
 324 <DD>
 325 Prints the integer <CODE>x</CODE> in binary (base 2, without prefix)
 326 on the <CODE>stream</CODE>.
 327
 328 <DT><CODE>void fprintoctal (cl_ostream stream, const cl_I&#38; x)</CODE>
 329 <DD>
 330 Prints the integer <CODE>x</CODE> in octal (base 8, without prefix)
 331 on the <CODE>stream</CODE>.
 332
 333 <DT><CODE>void fprinthexadecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
 334 <DD>
 335 Prints the integer <CODE>x</CODE> in hexadecimal (base 16, without prefix)
 336 on the <CODE>stream</CODE>.
 337 </DL>
 338
 339 <P>
 340 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
 341 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
 342 defines, in <CODE>&#60;cln/<VAR>type</VAR>_io.h&#62;</CODE>, the following output functions:
 343
 344
 345 <DL COMPACT>
 346
 347 <DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
 348 <DD>
 349 <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
 350 <DD>
 351 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
 352 on the global printer settings in the variable <CODE>default_print_flags</CODE>.
 353 The <CODE>ostream</CODE> flags and settings (flags, width and locale) are
 354 ignored.
 355 </DL>
 356
 357 <P>
 358 The most flexible output function, defined in <CODE>&#60;cln/<VAR>type</VAR>_io.h&#62;</CODE>,
 359 are the following:
 360
 361 <PRE>
 362 void print_complex  (cl_ostream stream, const cl_print_flags&#38; flags,
 363                      const cl_N&#38; z);
 364 void print_real     (cl_ostream stream, const cl_print_flags&#38; flags,
 365                      const cl_R&#38; z);
 366 void print_float    (cl_ostream stream, const cl_print_flags&#38; flags,
 367                      const cl_F&#38; z);
 368 void print_rational (cl_ostream stream, const cl_print_flags&#38; flags,
 369                      const cl_RA&#38; z);
 370 void print_integer  (cl_ostream stream, const cl_print_flags&#38; flags,
 371                      const cl_I&#38; z);
 372 </PRE>
 373
 374 <P>
 375 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The <CODE>flags</CODE> are
 376 parameters which affect the output.
 377
 378
 379 <P>
 380 The structure type <CODE>cl_print_flags</CODE> contains the following fields:
 381
 382
 383 <DL COMPACT>
 384
 385 <DT><CODE>unsigned int rational_base</CODE>
 386 <DD>
 387 The base in which rational numbers are printed. Default is <CODE>10</CODE>.
 388
 389 <DT><CODE>cl_boolean rational_readably</CODE>
 390 <DD>
 391 If this flag is true, rational numbers are printed with radix specifiers in
 392 Common Lisp syntax (<CODE>#<VAR>n</VAR>R</CODE> or <CODE>#b</CODE> or <CODE>#o</CODE> or <CODE>#x</CODE>
 393 prefixes, trailing dot). Default is false.
 394
 395 <DT><CODE>cl_boolean float_readably</CODE>
 396 <DD>
 397 If this flag is true, type specific exponent markers have precedence over 'E'.
 398 Default is false.
 399
 400 <DT><CODE>cl_float_format_t default_float_format</CODE>
 401 <DD>
 402 Floating point numbers of this format will be printed using the 'E' exponent
 403 marker. Default is <CODE>cl_float_format_ffloat</CODE>.
 404
 405 <DT><CODE>cl_boolean complex_readably</CODE>
 406 <DD>
 407 If this flag is true, complex numbers will be printed using the Common Lisp
 408 syntax <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>. Default is false.
 409
 410 <DT><CODE>cl_string univpoly_varname</CODE>
 411 <DD>
 412 Univariate polynomials with no explicit indeterminate name will be printed
 413 using this variable name. Default is <CODE>"x"</CODE>.
 414 </DL>
 415
 416 <P>
 417 The global variable <CODE>default_print_flags</CODE> contains the default values,
 418 used by the function <CODE>fprint</CODE>.
 419
 420
 421 <P><HR><P>
 422 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>.
 423 </BODY>
 424 </HTML>