home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / gnu / libg++-2.5.3-bin.lha / info / iostream.info (.txt) next >
GNU Info File  |  1994-02-27  |  63KB  |  1,270 lines
  1. This is Info file iostream.info, produced by Makeinfo-1.55 from the
  2. input file ./iostream.texi.
  3. START-INFO-DIR-ENTRY
  4. * iostream::                    The C++ input/output facility.
  5. END-INFO-DIR-ENTRY
  6.    This file describes libio, the GNU library for C++ iostreams and C
  7. stdio.
  8.    libio includes software developed by the University of California,
  9. Berkeley.
  10.    Copyright (C) 1993 Free Software Foundation, Inc.
  11.    Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided also
  16. that the entire resulting derived work is distributed under the terms
  17. of a permission notice identical to this one.
  18.    Permission is granted to copy and distribute translations of this
  19. manual into another language, under the above conditions for modified
  20. versions.
  21. File: iostream.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
  22. The GNU C++ Iostream Library
  23. ****************************
  24.    This file provides reference information on the GNU C++ iostream
  25. library (`libio'), version 0.50.
  26. * Menu:
  27. * Introduction::
  28. * Operators::            Operators and default streams.
  29. * Streams::            Stream classes.
  30. * Files and Strings::        Classes for files and strings.
  31. * Streambuf::            Using the streambuf layer.
  32. * Stdio::            C input and output.
  33. * Index::
  34. File: iostream.info,  Node: Introduction,  Next: Operators,  Prev: Top,  Up: Top
  35. Introduction
  36. ************
  37.    The iostream classes implement most of the features of AT&T version
  38. 2.0 iostream library classes, and most of the features of the ANSI X3J16
  39. library draft (which is based on the AT&T design).
  40.    This manual is meant as a reference; for tutorial material on
  41. iostreams, see the corresponding section of any recent popular
  42. introduction to C++.
  43. * Menu:
  44. * Copying::        Special GNU licensing terms for libio.
  45. * Acknowledgements::    Contributors to GNU iostream.
  46. File: iostream.info,  Node: Copying,  Next: Acknowledgements,  Up: Introduction
  47. Licensing terms for `libio'
  48. ===========================
  49.    Since the `iostream' classes are so fundamental to standard C++, the
  50. Free Software Foundation has agreed to a special exception to its
  51. standard license, when you link programs with `libio.a':
  52.      As a special exception, if you link this library with files
  53.      compiled with a GNU compiler to produce an executable, this does
  54.      not cause the resulting executable to be covered by the GNU
  55.      General Public License.  This exception does not however
  56.      invalidate any other reasons why the executable file might be
  57.      covered by the GNU General Public License.
  58.    The code is under the GNU General Public License (version 2) for all
  59. other purposes than linking with this library; that means that you can
  60. modify and redistribute the code as usual, but remember that if you do,
  61. your modifications, and anything you link with the modified code, must
  62. be available to others on the same terms.
  63.    These functions are also available as part of the `libg++' library;
  64. if you link with that library instead of `libio', the GNU Library
  65. General Public License applies.
  66. File: iostream.info,  Node: Acknowledgements,  Prev: Copying,  Up: Introduction
  67. Acknowledgements
  68. ================
  69.    Per Bothner wrote most of the `iostream' library, but some portions
  70. have their origins elsewhere in the free software community.  Heinz
  71. Seidl wrote the IO manipulators.  The floating-point conversion software
  72. is by David M. Gay of AT&T.  Some code was derived from parts of BSD
  73. 4.4, which was written at the University of California, Berkeley.
  74.    The iostream classes are found in the `libio' library.  An early
  75. version was originally distributed in `libg++', and they are still
  76. included there as well, for convenience if you need other `libg++'
  77. classes.  Doug Lea was the original author of `libg++', and some of the
  78. file-management code still in `libio' is his.
  79.    Various people found bugs or offered suggestions.  Hongjiu Lu worked
  80. hard to use the library as the default stdio implementation for Linux,
  81. and has provided much stress-testing of the library.
  82. File: iostream.info,  Node: Operators,  Next: Streams,  Prev: Introduction,  Up: Top
  83. Operators and Default Streams
  84. *****************************
  85.    The GNU iostream library, `libio', implements the standard input and
  86. output facilities for C++.  These facilities are roughly analogous (in
  87. their purpose and ubiquity, at least) with those defined by the C
  88. `stdio' functions.
  89.    Although these definitions come from a library, rather than being
  90. part of the "core language", they are sufficiently central to be
  91. specified in the latest working papers for C++.
  92.    You can use two operators defined in this library for basic input and
  93. output operations.  They are familiar from any C++ introductory
  94. textbook: `<<' for output, and `>>' for input.  (Think of data flowing
  95. in the direction of the "arrows".)
  96.    These operators are often used in conjunction with three streams that
  97. are open by default:
  98.  - Variable: ostream cout
  99.      The standard output stream, analogous to the C `stdout'.
  100.  - Variable: istream cin
  101.      The standard input stream, analogous to the C `stdin'.
  102.  - Variable: ostream cerr
  103.      An alternative output stream for errors, analogous to the C
  104.      `stderr'.
  105. For example, this bare-bones C++ version of the traditional "hello"
  106. program uses `<<' and `cout':
  107.      #include <iostream.h>
  108.      
  109.      int main(int argc, char **argv)
  110.      {
  111.        cout << "Well, hi there.\n";
  112.        return 0;
  113.      }
  114.    Casual use of these operators may be seductive, but--other than in
  115. writing throwaway code for your own use--it is not necessarily simpler
  116. than managing input and output in any other language.  For example,
  117. robust code should check the state of the input and output streams
  118. between operations (for example, using the method `good').  *Note
  119. Checking the state of a stream: States.  You may also need to adjust
  120. maximum input or output field widths, using manipulators like `setw' or
  121. `setprecision'.
  122.  - Operator on ostream: <<
  123.      Write output to an open output stream of class `ostream'.  Defined
  124.      by this library on any OBJECT of a C++ primitive type, and on
  125.      other classes of the library.  You can overload the definition for
  126.      any of your own applications' classes.
  127.      Returns a reference to the implied argument `*this' (the open
  128.      stream it writes on), permitting statements like
  129.           cout << "The value of i is " << i << "\n";
  130.  - Operator on istream: >>
  131.      Read input from an open input stream of class `istream'.  Defined
  132.      by this library on primitive numeric, pointer, and string types;
  133.      you can extend the definition for any of your own applications'
  134.      classes.
  135.      Returns a reference to the implied argument `*this' (the open
  136.      stream it reads), permitting multiple inputs in one statement.
  137. File: iostream.info,  Node: Streams,  Next: Files and Strings,  Prev: Operators,  Up: Top
  138. Stream Classes
  139. **************
  140.    The previous chapter referred in passing to the classes `ostream'
  141. and `istream', for output and input respectively.  These classes share
  142. certain properties, captured in their base class `ios'.
  143. * Menu:
  144. * Ios::       Shared properties.
  145. * Ostream::   Managing output streams.
  146. * Istream::   Managing input streams.
  147. * Iostream::  Input and output together.
  148. File: iostream.info,  Node: Ios,  Next: Ostream,  Up: Streams
  149. Shared properties: class `ios'
  150. ==============================
  151.    The base class `ios' provides methods to test and manage the state
  152. of input or output streams.
  153.    `ios' delegates the job of actually reading and writing bytes to the
  154. abstract class `streambuf', which is designed to provide buffered
  155. streams (compatible with C, in the GNU implementation).  *Note Using
  156. the `streambuf' layer: Streambuf, for information on the facilities
  157. available at the `streambuf' level.
  158.  - Constructor:  ios::ios ([streambuf* SB [, ostream* TIE])
  159.      The `ios' constructor by default initializes a new `ios', and if
  160.      you supply a `streambuf' SB to associate with it, sets the state
  161.      `good' in the new `ios' object.