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 next >
Encoding:
GNU Info File  |  1994-02-27  |  61.6 KB  |  1,643 lines
  1. This is Info file iostream.info, produced by Makeinfo-1.55 from the
  2. input file ./iostream.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * iostream::                    The C++ input/output facility.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file describes libio, the GNU library for C++ iostreams and C
  9. stdio.
  10.  
  11.    libio includes software developed by the University of California,
  12. Berkeley.
  13.  
  14.    Copyright (C) 1993 Free Software Foundation, Inc.
  15.  
  16.    Permission is granted to make and distribute verbatim copies of this
  17. manual provided the copyright notice and this permission notice are
  18. preserved on all copies.
  19.  
  20.    Permission is granted to copy and distribute modified versions of
  21. this manual under the conditions for verbatim copying, provided also
  22. that the entire resulting derived work is distributed under the terms
  23. of a permission notice identical to this one.
  24.  
  25.    Permission is granted to copy and distribute translations of this
  26. manual into another language, under the above conditions for modified
  27. versions.
  28.  
  29. 
  30. File: iostream.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)
  31.  
  32. The GNU C++ Iostream Library
  33. ****************************
  34.  
  35.    This file provides reference information on the GNU C++ iostream
  36. library (`libio'), version 0.50.
  37.  
  38. * Menu:
  39.  
  40. * Introduction::
  41. * Operators::            Operators and default streams.
  42. * Streams::            Stream classes.
  43. * Files and Strings::        Classes for files and strings.
  44. * Streambuf::            Using the streambuf layer.
  45. * Stdio::            C input and output.
  46. * Index::
  47.  
  48. 
  49. File: iostream.info,  Node: Introduction,  Next: Operators,  Prev: Top,  Up: Top
  50.  
  51. Introduction
  52. ************
  53.  
  54.    The iostream classes implement most of the features of AT&T version
  55. 2.0 iostream library classes, and most of the features of the ANSI X3J16
  56. library draft (which is based on the AT&T design).
  57.  
  58.    This manual is meant as a reference; for tutorial material on
  59. iostreams, see the corresponding section of any recent popular
  60. introduction to C++.
  61.  
  62. * Menu:
  63.  
  64. * Copying::        Special GNU licensing terms for libio.
  65. * Acknowledgements::    Contributors to GNU iostream.
  66.  
  67. 
  68. File: iostream.info,  Node: Copying,  Next: Acknowledgements,  Up: Introduction
  69.  
  70. Licensing terms for `libio'
  71. ===========================
  72.  
  73.    Since the `iostream' classes are so fundamental to standard C++, the
  74. Free Software Foundation has agreed to a special exception to its
  75. standard license, when you link programs with `libio.a':
  76.  
  77.      As a special exception, if you link this library with files
  78.      compiled with a GNU compiler to produce an executable, this does
  79.      not cause the resulting executable to be covered by the GNU
  80.      General Public License.  This exception does not however
  81.      invalidate any other reasons why the executable file might be
  82.      covered by the GNU General Public License.
  83.  
  84.    The code is under the GNU General Public License (version 2) for all
  85. other purposes than linking with this library; that means that you can
  86. modify and redistribute the code as usual, but remember that if you do,
  87. your modifications, and anything you link with the modified code, must
  88. be available to others on the same terms.
  89.  
  90.    These functions are also available as part of the `libg++' library;
  91. if you link with that library instead of `libio', the GNU Library
  92. General Public License applies.
  93.  
  94. 
  95. File: iostream.info,  Node: Acknowledgements,  Prev: Copying,  Up: Introduction
  96.  
  97. Acknowledgements
  98. ================
  99.  
  100.    Per Bothner wrote most of the `iostream' library, but some portions
  101. have their origins elsewhere in the free software community.  Heinz
  102. Seidl wrote the IO manipulators.  The floating-point conversion software
  103. is by David M. Gay of AT&T.  Some code was derived from parts of BSD
  104. 4.4, which was written at the University of California, Berkeley.
  105.  
  106.    The iostream classes are found in the `libio' library.  An early
  107. version was originally distributed in `libg++', and they are still
  108. included there as well, for convenience if you need other `libg++'
  109. classes.  Doug Lea was the original author of `libg++', and some of the
  110. file-management code still in `libio' is his.
  111.  
  112.    Various people found bugs or offered suggestions.  Hongjiu Lu worked
  113. hard to use the library as the default stdio implementation for Linux,
  114. and has provided much stress-testing of the library.
  115.  
  116. 
  117. File: iostream.info,  Node: Operators,  Next: Streams,  Prev: Introduction,  Up: Top
  118.  
  119. Operators and Default Streams
  120. *****************************
  121.  
  122.    The GNU iostream library, `libio', implements the standard input and
  123. output facilities for C++.  These facilities are roughly analogous (in
  124. their purpose and ubiquity, at least) with those defined by the C
  125. `stdio' functions.
  126.  
  127.    Although these definitions come from a library, rather than being
  128. part of the "core language", they are sufficiently central to be
  129. specified in the latest working papers for C++.
  130.  
  131.    You can use two operators defined in this library for basic input and
  132. output operations.  They are familiar from any C++ introductory
  133. textbook: `<<' for output, and `>>' for input.  (Think of data flowing
  134. in the direction of the "arrows".)
  135.  
  136.    These operators are often used in conjunction with three streams that
  137. are open by default:
  138.  
  139.  - Variable: ostream cout
  140.      The standard output stream, analogous to the C `stdout'.
  141.  
  142.  - Variable: istream cin
  143.      The standard input stream, analogous to the C `stdin'.
  144.  
  145.  - Variable: ostream cerr
  146.      An alternative output stream for errors, analogous to the C
  147.      `stderr'.
  148.  
  149. For example, this bare-bones C++ version of the traditional "hello"
  150. program uses `<<' and `cout':
  151.  
  152.      #include <iostream.h>
  153.      
  154.      int main(int argc, char **argv)
  155.      {
  156.        cout << "Well, hi there.\n";
  157.        return 0;
  158.      }
  159.  
  160.    Casual use of these operators may be seductive, but--other than in
  161. writing throwaway code for your own use--it is not necessarily simpler
  162. than managing input and output in any other language.  For example,
  163. robust code should check the state of the input and output streams
  164. between operations (for example, using the method `good').  *Note
  165. Checking the state of a stream: States.  You may also need to adjust
  166. maximum input or output field widths, using manipulators like `setw' or
  167. `setprecision'.
  168.  
  169.  - Operator on ostream: <<
  170.      Write output to an open output stream of class `ostream'.  Defined
  171.      by this library on any OBJECT of a C++ primitive type, and on
  172.      other classes of the library.  You can overload the definition for
  173.      any of your own applications' classes.
  174.  
  175.      Returns a reference to the implied argument `*this' (the open
  176.      stream it writes on), permitting statements like
  177.           cout << "The value of i is " << i << "\n";
  178.  
  179.  - Operator on istream: >>
  180.      Read input from an open input stream of class `istream'.  Defined
  181.      by this library on primitive numeric, pointer, and string types;
  182.      you can extend the definition for any of your own applications'
  183.      classes.
  184.  
  185.      Returns a reference to the implied argument `*this' (the open
  186.      stream it reads), permitting multiple inputs in one statement.
  187.  
  188. 
  189. File: iostream.info,  Node: Streams,  Next: Files and Strings,  Prev: Operators,  Up: Top
  190.  
  191. Stream Classes
  192. **************
  193.  
  194.    The previous chapter referred in passing to the classes `ostream'
  195. and `istream', for output and input respectively.  These classes share
  196. certain properties, captured in their base class `ios'.
  197.  
  198. * Menu:
  199.  
  200. * Ios::       Shared properties.
  201. * Ostream::   Managing output streams.
  202. * Istream::   Managing input streams.
  203. * Iostream::  Input and output together.
  204.  
  205. 
  206. File: iostream.info,  Node: Ios,  Next: Ostream,  Up: Streams
  207.  
  208. Shared properties: class `ios'
  209. ==============================
  210.  
  211.    The base class `ios' provides methods to test and manage the state
  212. of input or output streams.
  213.  
  214.    `ios' delegates the job of actually reading and writing bytes to the
  215. abstract class `streambuf', which is designed to provide buffered
  216. streams (compatible with C, in the GNU implementation).  *Note Using
  217. the `streambuf' layer: Streambuf, for information on the facilities
  218. available at the `streambuf' level.
  219.  
  220.  - Constructor:  ios::ios ([streambuf* SB [, ostream* TIE])
  221.      The `ios' constructor by default initializes a new `ios', and if
  222.      you supply a `streambuf' SB to associate with it, sets the state
  223.      `good' in the new `ios' object.  It also sets the default
  224.      properties of the new object.
  225.  
  226.      You can also supply an optional second argument TIE to the
  227.      constructor: if present, it is an initial value for `ios::tie', to
  228.      associate the new `ios' object with another stream.
  229.  
  230.  - Destructor:  ios::~ios ()
  231.      The `ios' destructor is virtual, permitting application-specific
  232.      behavior when a stream is closed--typically, the destructor frees
  233.      any storage associated with the stream and releases any other
  234.      associated objects.
  235.  
  236. * Menu:
  237.  
  238. * States::        Checking the state of a stream.
  239. * Format Control::    Choices in formatting.
  240. * Manipulators::    Convenient ways of changing stream properties.
  241. * Extending::        Extended data fields.
  242. * Synchronization::    Synchronizing related streams.
  243. * Streambuf from Ios::    Reaching the underlying streambuf.
  244.  
  245. 
  246. File: iostream.info,  Node: States,  Next: Format Control,  Up: Ios
  247.  
  248. Checking the state of a stream
  249. ------------------------------
  250.  
  251.    Use this collection of methods to test for (or signal) errors and
  252. other exceptional conditions of streams:
  253.  
  254.  - Method: ios::operator void* () const
  255.      You can do a quick check on the state of the most recent operation
  256.      on a stream by examining a pointer to the stream itself.  The
  257.      pointer is arbitrary except for its truth value; it is true if no
  258.      failures have occurred (`ios::fail' is not true).  For example,
  259.      you might ask for input on `cin' only if all prior output
  260.      operations succeeded:
  261.  
  262.           if (cout)
  263.           {
  264.             // Everything OK so far
  265.             cin >> new_value;
  266.             ...
  267.           }
  268.  
  269.  - Method: ios::operator ! () const
  270.      In case it is more convenient to check whether something has
  271.      failed, the operator `!' returns true if `ios::fail' is true (an
  272.      operation has failed).  For example, you might issue an error
  273.      message if input failed:
  274.  
  275.           if (!cin)
  276.           {
  277.             // Oops
  278.             cerr << "Eh?\n";
  279.           }
  280.  
  281.  - Method: iostate ios::rdstate () const
  282.      Return the state flags for this stream.  The value is from the
  283.      enumeration `iostate'.  You can test for any combination of
  284.  
  285.     `goodbit'
  286.           There are no indications of exceptional states on this stream.
  287.  
  288.     `eofbit'
  289.           End of file.
  290.  
  291.     `failbit'
  292.           An operation has failed on this stream; this usually
  293.           indicates bad format of input.
  294.  
  295.     `badbit'
  296.           The stream is unusable.
  297.  
  298.  - Method: void ios::setstate (iostate STATE)
  299.      Set the state flag for this stream to STATE *in addition to* any
  300.      state flags already set.  Synonym (for upward compatibility):
  301.      `ios::set'.
  302.  
  303.      See `ios::clear' to set the stream state without regard to existing
  304.      state flags.  See `ios::good', `ios::eof', `ios::fail', and
  305.      `ios::bad', to test the state.
  306.  
  307.  - Method: int ios::good () const
  308.      Test the state flags associated with this stream; true if no error
  309.      indicators are set.
  310.  
  311.  - Method: int ios::bad () const
  312.      Test whether a stream is marked as unusable.  (Whether
  313.      `ios::badbit' is set.)
  314.  
  315.  - Method: int ios::eof () const
  316.      True if end of file was reached on this stream.  (If `ios::eofbit'
  317.      is set.)
  318.  
  319.  - Method: int ios::fail () const
  320.      Test for any kind of failure on this stream: *either* some
  321.      operation failed, *or* the stream is marked as bad.  (If either
  322.      `ios::failbit' or `ios::badbit' is set.)
  323.  
  324.  - Method: void ios::clear (iostate STATE)
  325.      Set the state indication for this stream to the argument STATE.
  326.      You may call `ios::clear' with no argument, in which case the state
  327.      is set to `good' (no errors pending).
  328.  
  329.      See `ios::good', `ios::eof', `ios::fail', and `ios::bad', to test
  330.      the state; see `ios::set' or `ios::setstate' for an alternative
  331.      way of setting the state.
  332.  
  333. 
  334. File: iostream.info,  Node: Format Control,  Next: Manipulators,  Prev: States,  Up: Ios
  335.  
  336. Choices in formatting
  337. ---------------------
  338.  
  339.    These methods control (or report on) settings for some details of
  340. controlling streams, primarily to do with formatting output:
  341.  
  342.  - Method: char ios::fill () const
  343.      Report on the padding character in use.
  344.  
  345.  - Method: char ios::fill (char PADDING)
  346.      Set the padding character.  You can also use the manipulator
  347.      `setfill'.  *Note Changing stream properties in expressions:
  348.      Manipulators.
  349.  
  350.      Default: blank.
  351.  
  352.  - Method: int ios::precision () const
  353.      Report the number of significant digits currently in use for
  354.      output of floating point numbers.
  355.  
  356.      Default: `6'.
  357.  
  358.  - Method: int ios::precision (int SIGNIF)
  359.      Set the number of significant digits (for input and output numeric
  360.      conversions) to SIGNIF.
  361.  
  362.      You can also use the manipulator `setprecision' for this purpose.
  363.      *Note Changing stream properties using manipulators: Manipulators.
  364.  
  365.  - Method: int ios::width () const
  366.      Report the current output field width setting (the number of
  367.      characters to write on the next `<<' output operation).
  368.  
  369.      Default: `0', which means to use as many characters as necessary.
  370.  
  371.  - Method: int ios::width (int NUM)
  372.      Set the input field width setting to NUM.  Return the *previous*
  373.      value for this stream.
  374.  
  375.      This value resets to zero (the default) every time you use `<<';
  376.      it is essentially an additional implicit argument to that
  377.      operator.  You can also use the manipulator `setw' for this
  378.      purpose.  *Note Changing stream properties using manipulators:
  379.      Manipulators.
  380.  
  381.  - Method: fmtflags ios::flags () const
  382.      Return the current value of the complete collection of flags
  383.      controlling the format state.  These are the flags and their
  384.      meanings when set:
  385.  
  386.     `ios::dec'
  387.     `ios::oct'
  388.     `ios::hex'
  389.           What numeric base to use in converting integers from internal
  390.           to display representation, or vice versa: decimal, octal, or
  391.           hexadecimal, respectively.  (You can change the base using
  392.           the manipulator `setbase', or any of the manipulators `dec',
  393.           `oct', or `hex'; *note Changing stream properties in
  394.           expressions: Manipulators..)
  395.  
  396.           On input, if none of these flags is set, read numeric
  397.           constants according to the prefix: decimal if no prefix (or a
  398.           `.' suffix), octal if a `0' prefix is present, hexadecimal if
  399.           a `0x' prefix is present.
  400.  
  401.           Default: `dec'.
  402.  
  403.     `ios::fixed'
  404.           Avoid scientific notation, and always show a fixed number of
  405.           digits after the decimal point, according to the output
  406.           precision in effect.  Use `ios::precision' to set precision.
  407.  
  408.     `ios::left'
  409.     `ios::right'
  410.     `ios::internal'
  411.           Where output is to appear in a fixed-width field;
  412.           left-justified, right-justified, or with padding in the
  413.           middle (e.g. between a numeric sign and the associated
  414.           value), respectively.
  415.  
  416.     `ios::scientific'
  417.           Use scientific (exponential) notation to display numbers.
  418.  
  419.     `ios::showbase'
  420.           Display the conventional prefix as a visual indicator of the
  421.           conversion base: no prefix for decimal, `0' for octal, `0x'
  422.           for hexadecimal.
  423.  
  424.     `ios::showpoint'
  425.           Display a decimal point and trailing zeros after it to fill
  426.           out numeric fields, even when redundant.
  427.  
  428.     `ios::showpos'
  429.           Display a positive sign on display of positive numbers.
  430.  
  431.     `ios::skipws'
  432.           Skip white space.  (On by default).
  433.  
  434.     `ios::stdio'
  435.           Flush the C `stdio' streams `stdout' and `stderr' after each
  436.           output operation (for programs that mix C and C++ output
  437.           conventions).
  438.  
  439.     `ios::unitbuf'
  440.           Flush after each output operation.
  441.  
  442.     `ios::uppercase'
  443.           Use upper-case characters for the non-numeral elements in
  444.           numeric displays; for instance, `0X7A' rather than `0x7a', or
  445.           `3.14E+09' rather than `3.14e+09'.
  446.  
  447.  - Method: fmtflags ios::flags (fmtflags VALUE)
  448.      Set VALUE as the complete collection of flags controlling the
  449.      format state.  The flag values are described under `ios::flags ()'.
  450.  
  451.      Use `ios::setf' or `ios::unsetf' to change one property at a time.
  452.  
  453.  - Method: fmtflags ios::setf (fmtflags FLAG)
  454.      Set one particular flag (of those described for `ios::flags ()';
  455.      return the complete collection of flags *previously* in effect.
  456.      (Use `ios::unsetf' to cancel.)
  457.  
  458.  - Method: fmtflags ios::setf (fmtflags FLAG, fmtflags MASK)
  459.      Clear the flag values indicated by MASK, then set any of them that
  460.      are also in FLAG.  (Flag values are described for `ios::flags
  461.      ()'.)  Return the complete collection of flags *previously* in
  462.      effect.  (See `ios::unsetf' for another way of clearing flags.)
  463.  
  464.  - Method: fmtflags ios::unsetf (fmtflags FLAG)
  465.      Make certain FLAG (a combination of flag values described for
  466.      `ios::flags ()') is not set for this stream; converse of
  467.      `ios::setf'.  Returns the old values of those flags.
  468.  
  469. 
  470. File: iostream.info,  Node: Manipulators,  Next: Extending,  Prev: Format Control,  Up: Ios
  471.  
  472. Changing stream properties using manipulators
  473. ---------------------------------------------
  474.  
  475.    For convenience, MANIPULATORS provide a way to change certain
  476. properties of streams, or otherwise affect them, in the middle of
  477. expressions involving `<<' or `>>'.  For example, you might write
  478.  
  479.      cout << "|" << setfill('*') << setw(5) << 234 << "|";
  480.  
  481. to produce `|**234|' as output.
  482.  
  483.  - Manipulator:  ws
  484.      Skip whitespace.
  485.  
  486.  - Manipulator:  flush
  487.      Flush an output stream.  For example, `cout << ... <<flush;' has
  488.      the same effect as `cout << ...; cout.flush();'.
  489.  
  490.  - Manipulator:  endl
  491.      Write an end of line character `\n', then flushes the output
  492.      stream.
  493.  
  494.  - Manipulator:  ends
  495.      Write `\0' (the string terminator character).
  496.  
  497.  - Manipulator:  setprecision (int SIGNIF)
  498.      You can change the value of `ios::precision' in `<<' expressions
  499.      with the manipulator `setprecision(SIGNIF)'; for example,
  500.  
  501.           cout << setprecision(2) << 4.567;
  502.  
  503.      prints `4.6'.  Requires `#include <iomanip.h>'.
  504.  
  505.  - Manipulator:  setw (int N)
  506.      You can change the value of `ios::width' in `<<' expressions with
  507.      the manipulator `setw(N)'; for example,
  508.  
  509.           cout << setw(5) << 234;
  510.  
  511.      prints `  234' with two leading blanks.  Requires `#include
  512.      <iomanip.h>'.
  513.  
  514.  - Manipulator:  setbase (int BASE)
  515.      Where BASE is one of `10' (decimal), `8' (octal), or `16'
  516.      (hexadecimal), change the base value for numeric representations.
  517.      Requires `#include <iomanip.h>'.
  518.  
  519.  - Manipulator:  dec
  520.      Select decimal base; equivalent to `setbase(10)'.
  521.  
  522.  - Manipulator:  hex
  523.      Select hexadecimal base; equivalent to `setbase(16)'.
  524.  
  525.  - Manipulator:  oct
  526.      Select octal base; equivalent to `setbase(8)'.
  527.  
  528.  - Manipulator:  setfill (char PADDING)
  529.      Set the padding character, in the same way as `ios::fill'.
  530.      Requires `#include <iomanip.h>'.
  531.  
  532. 
  533. File: iostream.info,  Node: Extending,  Next: Synchronization,  Prev: Manipulators,  Up: Ios
  534.  
  535. Extended data fields
  536. --------------------
  537.  
  538.    A related collection of methods allows you to extend this collection
  539. of flags and parameters for your own applications, without risk of
  540. conflict between them:
  541.  
  542.  - Method: static fmtflags ios::bitalloc ()
  543.      Reserve a bit (the single bit on in the result) to use as a flag.
  544.      Using `bitalloc' guards against conflict between two packages that
  545.      use `ios' objects for different purposes.
  546.  
  547.      This method is available for upward compatibility, but is not in
  548.      the ANSI working paper.  The number of bits available is limited; a
  549.      return value of `0' means no bit is available.
  550.  
  551.  - Method: static int ios::xalloc ()
  552.      Reserve space for a long integer or pointer parameter.  The result
  553.      is a unique nonnegative integer.  You can use it as an index to
  554.      `ios::iword' or `ios::pword'.  Use `xalloc' to arrange for
  555.      arbitrary special-purpose data in your `ios' objects, without risk
  556.      of conflict between packages designed for different purposes.
  557.  
  558.  - Method: long& ios::iword (int INDEX)
  559.      Return a reference to arbitrary data, of long integer type, stored
  560.      in an `ios' instance.  INDEX, conventionally returned from
  561.      `ios::xalloc', identifies what particular data you need.
  562.  
  563.  - Method: long ios::iword (int INDEX) const
  564.      Return the actual value of a long integer stored in an `ios'.
  565.  
  566.  - Method: void*& ios::pword (int INDEX)
  567.      Return a reference to an arbitrary pointer, stored in an `ios'
  568.      instance.  INDEX, originally returned from `ios::xalloc',
  569.      identifies what particular pointer you need.
  570.  
  571.  - Method: void* ios::pword (int INDEX) const
  572.      Return the actual value of a pointer stored in an `ios'.
  573.  
  574. 
  575. File: iostream.info,  Node: Synchronization,  Next: Streambuf from Ios,  Prev: Extending,  Up: Ios
  576.  
  577. Synchronizing related streams
  578. -----------------------------
  579.  
  580.    You can use these methods to synchronize related streams with one
  581. another:
  582.  
  583.  - Method: ostream* ios::tie () const
  584.      Report on what output stream, if any, is to be flushed before
  585.      accessing this one.  A pointer value of `0' means no stream is
  586.      tied.
  587.  
  588.  - Method: ostream* ios::tie (ostream* ASSOC)
  589.      Declare that output stream ASSOC must be flushed before accessing
  590.      this stream.
  591.  
  592.  - Method: int ios::sync_with_stdio ([int SWITCH])
  593.      Unless iostreams and C `stdio' are designed to work together, you
  594.      may have to choose between efficient C++ streams output and output
  595.      compatible with C `stdio'.  Use `ios::sync_with_stdio()' to select
  596.      C compatibility.
  597.  
  598.      The argument SWITCH is a GNU extension; use `0' as the argument to
  599.      choose output that is not necessarily compatible with C `stdio'.
  600.      The default value for SWITCH is `1'.
  601.  
  602.      If you install the `stdio' implementation that comes with GNU
  603.      `libio', there are compatible input/output facilities for both C
  604.      and C++.  In that situation, this method is unnecessary--but you
  605.      may still want to write programs that call it, for portability.
  606.  
  607. 
  608. File: iostream.info,  Node: Streambuf from Ios,  Prev: Synchronization,  Up: Ios
  609.  
  610. Reaching the underlying `streambuf'
  611. -----------------------------------
  612.  
  613.    Finally, you can use this method to access the underlying object:
  614.  
  615.  - Method: streambuf* ios::rdbuf () const
  616.      Return a pointer to the `streambuf' object that underlies this
  617.      `ios'.
  618.  
  619. 
  620. File: iostream.info,  Node: Ostream,  Next: Istream,  Prev: Ios,  Up: Streams
  621.  
  622. Managing output streams: class `ostream'
  623. ========================================
  624.  
  625.    Objects of class `ostream' inherit the generic methods from `ios',
  626. and in addition have the following methods available.  Declarations for
  627. this class come from `iostream.h'.
  628.  
  629.  - Constructor:  ostream::ostream ()
  630.      The simplest form of the constructor for an `ostream' simply
  631.      allocates a new `ios' object.
  632.  
  633.  - Constructor:  ostream::ostream (streambuf* SB [, ostream TIE])
  634.      This alternative constructor requires a first argument SB of type
  635.      `streambuf*', to use an existing open stream for output.  It also
  636.      accepts an optional second argument TIE, to specify a related
  637.      `ostream*' as the initial value for `ios::tie'.
  638.  
  639.      If you give the `ostream' a `streambuf' explicitly, using this
  640.      constructor, the SB is *not* destroyed (or deleted or closed) when
  641.      the `ostream' is destroyed.
  642.  
  643. * Menu:
  644.  
  645. * Writing::        Writing on an ostream.
  646. * Output Position::    Repositioning an ostream.
  647. * Ostream Housekeeping:: Miscellaneous ostream utilities.
  648.  
  649. 
  650. File: iostream.info,  Node: Writing,  Next: Output Position,  Up: Ostream
  651.  
  652. Writing on an `ostream'
  653. -----------------------
  654.  
  655.    These methods write on an `ostream' (you may also use the operator
  656. `<<'; *note Operators and Default Streams: Operators.).
  657.  
  658.  - Method: ostream& ostream::put (char C)
  659.      Write the single character C.
  660.  
  661.  - Method: ostream& ostream::write (STRING, int LENGTH)
  662.      Write LENGTH characters of a string to this `ostream', beginning
  663.      at the pointer STRING.
  664.  
  665.      STRING may have any of these types: `char*', `unsigned char*',
  666.      `signed char*'.
  667.  
  668.  - Method: ostream& ostream::form (const char *FORMAT, ...)
  669.      A GNU extension, similar to `fprintf(FILE, FORMAT, ...)'.
  670.  
  671.      FORMAT is a `printf'-style format control string, which is used to
  672.      format the (variable number of) arguments, printing the result on
  673.      this `ostream'.  See `ostream::vform' for a version that uses an
  674.      argument list rather than a variable number of arguments.
  675.  
  676.  - Method: ostream& ostream::vform (const char *FORMAT, va_list ARGS)
  677.      A GNU extension, similar to `vfprintf(FILE, FORMAT, ARGS)'.
  678.  
  679.      FORMAT is a `printf'-style format control string, which is used to
  680.      format the argument list ARGS, printing the result on this
  681.      `ostream'.  See `ostream::form' for a version that uses a variable
  682.      number of arguments rather than an argument list.
  683.  
  684. 
  685. File: iostream.info,  Node: Output Position,  Next: Ostream Housekeeping,  Prev: Writing,  Up: Ostream
  686.  
  687. Repositioning an `ostream'
  688. --------------------------
  689.  
  690.    You can control the output position (on output streams that actually
  691. support positions, typically files) with these methods:
  692.  
  693.  - Method: streampos ostream::tellp ()
  694.      Return the current write position in the stream.
  695.  
  696.  - Method: ostream& ostream::seekp (streampos LOC)
  697.      Reset the output position to LOC (which is usually the result of a
  698.      previous call to `ostream::tellp').  LOC specifies an absolute
  699.      position in the output stream.
  700.  
  701.  - Method: ostream& ostream::seekp (streamoff LOC, REL)
  702.      Reset the output position to LOC, relative to the beginning, end,
  703.      or current output position in the stream, as indicated by REL (a
  704.      value from the enumeration `ios::seekdir'):
  705.  
  706.     `beg'
  707.           Interpret LOC as an absolute offset from the beginning of the
  708.           file.
  709.  
  710.     `cur'
  711.           Interpret LOC as an offset relative to the current output
  712.           position.
  713.  
  714.     `end'
  715.           Interpret LOC as an offset from the current end of the output
  716.           stream.
  717.  
  718. 
  719. File: iostream.info,  Node: Ostream Housekeeping,  Prev: Output Position,  Up: Ostream
  720.  
  721. Miscellaneous `ostream' utilities
  722. ---------------------------------
  723.  
  724.    You may need to use these `ostream' methods for housekeeping:
  725.  
  726.  - Method: ostream& flush ()
  727.      Deliver any pending buffered output for this `ostream'.
  728.  
  729.  - Method: int ostream::opfx ()
  730.      `opfx' is a "prefix" method for operations on `ostream' objects;
  731.      it is designed to be called before any further processing.  See
  732.      `ostream::osfx' for the converse.
  733.  
  734.      `opfx' tests that the stream is in state `good', and if so flushes
  735.      any stream tied to this one.
  736.  
  737.      The result is `1' when `opfx' succeeds; else (if the stream state
  738.      is not `good'), the result is `0'.
  739.  
  740.  - Method: void ostream::osfx ()
  741.      `osfx' is a "suffix" method for operations on `ostream' objects;
  742.      it is designed to be called at the conclusion of any processing.
  743.      All the `ostream' methods end by calling `osfx'.  See
  744.      `ostream::opfx' for the converse.
  745.  
  746.      If the `unitbuf' flag is set for this stream, `osfx' flushes any
  747.      buffered output for it.
  748.  
  749.      If the `stdio' flag is set for this stream, `osfx' flushes any
  750.      output buffered for the C output streams `stdout' and `stderr'.
  751.  
  752. 
  753. File: iostream.info,  Node: Istream,  Next: Iostream,  Prev: Ostream,  Up: Streams
  754.  
  755. Managing input streams: class `istream'
  756. =======================================
  757.  
  758.    Class `istream' objects are specialized for input; as for `ostream',
  759. they are derived from `ios', so you can use any of the general-purpose
  760. methods from that base class.  Declarations for this class also come
  761. from `iostream.h'.
  762.  
  763.  - Constructor:  istream::istream ()
  764.      When used without arguments, the `istream' constructor simply
  765.      allocates a new `ios' object and initializes the input counter (the
  766.      value reported by `istream::gcount') to `0'.
  767.  
  768.  - Constructor:  istream::istream (streambuf *SB [, ostream TIE])
  769.      You can also call the constructor with one or two arguments.  The
  770.      first argument SB is a `streambuf*'; if you supply this pointer,
  771.      the constructor uses that `streambuf' for input.  You can use the
  772.      second optional argument TIE to specify a related output stream as
  773.      the initial value for `ios::tie'.
  774.  
  775.      If you give the `istream' a `streambuf' explicitly, using this
  776.      constructor, the SB is *not* destroyed (or deleted or closed) when
  777.      the `ostream' is destroyed.
  778.  
  779. * Menu:
  780.  
  781. * Char Input::        Reading one character.
  782. * String Input::    Reading strings.
  783. * Input Position::    Repositioning an istream.
  784. * Istream Housekeeping:: Miscellaneous istream utilities.
  785.  
  786. 
  787. File: iostream.info,  Node: Char Input,  Next: String Input,  Up: Istream
  788.  
  789. Reading one character
  790. ---------------------
  791.  
  792.    Use these methods to read a single character from the input stream:
  793.  
  794.  - Method: int istream::get ()
  795.      Read a single character (or `EOF') from the input stream, returning
  796.      it (coerced to an unsigned char) as the result.
  797.  
  798.  - Method: istream& istream::get (char& C)
  799.      Read a single character from the input stream, into `&C'.
  800.  
  801.  - Method: int istream::peek ()
  802.      Return the next available input character, but *without* changing
  803.      the current input position.
  804.  
  805. 
  806. File: iostream.info,  Node: String Input,  Next: Input Position,  Prev: Char Input,  Up: Istream
  807.  
  808. Reading strings
  809. ---------------
  810.  
  811.    Use these methods to read strings (for example, a line at a time)
  812. from the input stream:
  813.  
  814.  - Method: istream& istream::get (char* C, int LEN [, char DELIM])
  815.      Read a string from the input stream, into the array at C.
  816.  
  817.      The remaining arguments limit how much to read: up to `len-1'
  818.      characters, or up to (but not including) the first occurrence in
  819.      the input of a particular delimiter character DELIM--newline
  820.      (`\n') by default.  (Naturally, if the stream reaches end of file
  821.      first, that too will terminate reading.)
  822.  
  823.      If DELIM was present in the input, it remains available as if
  824.      unread; to discard it instead, see `iostream::getline'.
  825.  
  826.      `get' writes `\0' at the end of the string, regardless of which
  827.      condition terminates the read.
  828.  
  829.  - Method: istream& istream::get (streambuf& SB [, char DELIM])
  830.      Read characters from the input stream and copy them on the
  831.      `streambuf' object SB.  Copying ends either just before the next
  832.      instance of the delimiter character DELIM (newline `\n' by
  833.      default), or when either stream ends.   If DELIM was present in
  834.      the input, it remains available as if unread.
  835.  
  836.  - Method: istream& istream::getline (CHARPTR, int LEN [, char DELIM])
  837.      Read a line from the input stream, into the array at CHARPTR.
  838.      cHARPTR may be any of three kinds of pointer: `char*', `unsigned
  839.      char*', or `signed char*'.
  840.  
  841.      The remaining arguments limit how much to read: up to (but not
  842.      including) the first occurrence in the input of a line delimiter
  843.      character DELIM--newline (`\n') by default, or up to `len-1'
  844.      characters (or to end of file, if that happens sooner).
  845.  
  846.      If `getline' succeeds in reading a "full line", it also discards
  847.      the trailing delimiter character from the input stream.  (To
  848.      preserve it as available input, see the similar form of
  849.      `iostream::get'.)
  850.  
  851.      If DELIM was *not* found before LEN characters or end of file,
  852.      `getline' sets the `ios::fail' flag, as well as the `ios::eof'
  853.      flag if appropriate.
  854.  
  855.      `getline' writes a null character at the end of the string,
  856.      regardless of which condition terminates the read.
  857.  
  858.  - Method: istream& istream::read (POINTER, int LEN)
  859.      Read LEN bytes into the location at POINTER, unless the input ends
  860.      first.
  861.  
  862.      POINTER may be of type `char*', `void*', `unsigned char*', or
  863.      `signed char*'.
  864.  
  865.      If the `istream' ends before reading LEN bytes, `read' sets the
  866.      `ios::fail' flag.
  867.  
  868.  - Method: istream& istream::gets (char **S [, char DELIM])
  869.      A GNU extension, to read an arbitrarily long string from the
  870.      current input position to the next instance of the DELIM character
  871.      (newline `\n' by default).
  872.  
  873.      To permit reading a string of arbitrary length, `gets' allocates
  874.      whatever memory is required.  Notice that the first argument S is
  875.      an address to record a character pointer, rather than the pointer
  876.      itself.
  877.  
  878.  - Method: istream& istream::scan (const char *format ...)
  879.      A GNU extension, similar to `fscanf(FILE, FORMAT, ...)'.  The
  880.      FORMAT is a `scanf'-style format control string, which is used to
  881.      read the variables in the remainder of the argument list from the
  882.      `istream'.
  883.  
  884.  - Method: istream& istream::vscan (const char *format, va_list args)
  885.      Like `istream::scan', but takes a single `va_list' argument.
  886.  
  887. 
  888. File: iostream.info,  Node: Input Position,  Next: Istream Housekeeping,  Prev: String Input,  Up: Istream
  889.  
  890. Repositioning an `istream'
  891. --------------------------
  892.  
  893.    Use these methods to control the current input position:
  894.  
  895.  - Method: streampos istream::tellg ()
  896.      Return the current read position, so that you can save it and
  897.      return to it later with `istream::seekg'.
  898.  
  899.  - Method: istream& istream::seekg (streampos P)
  900.      Reset the input pointer (if the input device permits it) to P,
  901.      usually the result of an earlier call to `istream::tellg'.
  902.  
  903.  - Method: istream& istream::seekg (streamoff OFFSET, ios::seek_dir REF)
  904.      Reset the input pointer (if the input device permits it) to OFFSET
  905.      characters from the beginning of the input, the current position,
  906.      or the end of input.  Specify how to interpret OFFSET with one of
  907.      these values for the second argument:
  908.  
  909.     `ios::beg'
  910.           Interpret LOC as an absolute offset from the beginning of the
  911.           file.
  912.  
  913.     `ios::cur'
  914.           Interpret LOC as an offset relative to the current output
  915.           position.
  916.  
  917.     `ios::end'
  918.           Interpret LOC as an offset from the current end of the output
  919.           stream.
  920.  
  921. 
  922. File: iostream.info,  Node: Istream Housekeeping,  Prev: Input Position,  Up: Istream
  923.  
  924. Miscellaneous `istream' utilities
  925. ---------------------------------
  926.  
  927.    Use these methods for housekeeping on `istream' objects:
  928.  
  929.  - Method: int istream::gcount ()
  930.      Report how many characters were read from this `istream' in the
  931.      last unformatted input operation.
  932.  
  933.  - Method: int istream::ipfx (int KEEPWHITE)
  934.      Ensure that the `istream' object is ready for reading; check for
  935.      errors and end of file and flush any tied stream.  `ipfx' skips
  936.      whitespace if you specify `0' as the KEEPWHITE argument, *and*
  937.      `ios::skipws' is set for this stream.
  938.  
  939.      To avoid skipping whitespace (regardless of the `skipws' setting on
  940.      the stream), use `1' as the argument.
  941.  
  942.      Call `istream::ipfx' to simplify writing your own methods for
  943.      reading `istream' objects.
  944.  
  945.  - Method: void istream::isfx ()
  946.      A placeholder for compliance with the draft ANSI standard; this
  947.      method does nothing whatever.
  948.  
  949.      If you wish to write portable standard-conforming code on `istream'
  950.      objects, call `isfx' after any operation that reads from an
  951.      `istream'; if `istream::ipfx' has any special effects that must be
  952.      cancelled when done, `istream::isfx' will cancel them.
  953.  
  954.  - Method: istream& istream::ignore ([int N] [, int DELIM])
  955.      Discard some number of characters pending input.  The first
  956.      optional argument N specifies how many characters to skip.  The
  957.      second optional argument DELIM specifies a "boundary" character:
  958.      `ignore' returns immediately if this character appears in the
  959.      input.
  960.  
  961.      By default, DELIM is `EOF'; that is, if you do not specify a
  962.      second argument, only the count N restricts how much to ignore
  963.      (while input is still available).
  964.  
  965.      If you do not specify how many characters to ignore, `ignore'
  966.      returns after discarding only one character.
  967.  
  968.  - Method: istream& istream::putback (char CH)
  969.      Attempts to back up one character, replacing the character
  970.      backed-up over by CH.  Returns `EOF' if this is not allowed.
  971.      Putting back the most recently read character is always allowed.
  972.      (This method corresponds to the C function `ungetc'.)
  973.  
  974.  - Method: istream& istream::unget ()
  975.      Attempt to back up one character.
  976.  
  977. 
  978. File: iostream.info,  Node: Iostream,  Prev: Istream,  Up: Streams
  979.  
  980. Input and output together: class `iostream'
  981. ===========================================
  982.  
  983.    If you need to use the same stream for input and output, you can use
  984. an object of the class `iostream', which is derived from *both*
  985. `istream' and `ostream'.
  986.  
  987.    The constructors for `iostream' behave just like the constructors
  988. for `istream'.
  989.  
  990.  - Constructor:  iostream::iostream ()
  991.      When used without arguments, the `iostream' constructor simply
  992.      allocates a new `ios' object, and initializes the input counter
  993.      (the value reported by `istream::gcount') to `0'.
  994.  
  995.  - Constructor:  iostream::iostream (streambuf* SB [, ostream* TIE])
  996.      You can also call a constructor with one or two arguments.  The
  997.      first argument SB is a `streambuf*'; if you supply this pointer,
  998.      the constructor uses that `streambuf' for input and output.
  999.  
  1000.      You can use the optional second argument TIE (an `ostream*') to
  1001.      specify a related output stream as the initial value for
  1002.      `ios::tie'.
  1003.  
  1004.    As for `ostream' and `istream', `iostream' simply uses the `ios'
  1005. destructor.  However, an `iostream' is not deleted by its destructor.
  1006.  
  1007.    You can use all the `istream', `ostream', and `ios' methods with an
  1008. `iostream' object.
  1009.  
  1010. 
  1011. File: iostream.info,  Node: Files and Strings,  Next: Streambuf,  Prev: Streams,  Up: Top
  1012.  
  1013. Classes for Files and Strings
  1014. *****************************
  1015.  
  1016.    There are two very common special cases of input and output: using
  1017. files, and using strings in memory.
  1018.  
  1019.    `libio' defines four specialized classes for these cases:
  1020.  
  1021. `ifstream'
  1022.      Methods for reading files.
  1023.  
  1024. `ofstream'
  1025.      Methods for writing files.
  1026.  
  1027. `istrstream'
  1028.      Methods for reading strings from memory.
  1029.  
  1030. `ostrstream'
  1031.      Methods for writing strings in memory.
  1032.  
  1033. * Menu:
  1034.  
  1035. * Files::    Reading and writing files.
  1036. * Strings::    Reading and writing strings in memory.
  1037.  
  1038. 
  1039. File: iostream.info,  Node: Files,  Next: Strings,  Up: Files and Strings
  1040.  
  1041. Reading and writing files
  1042. =========================
  1043.  
  1044.    These methods are declared in `fstream.h'.
  1045.  
  1046.    You can read data from class `ifstream' with any operation from class
  1047. `istream'.  There are also a few specialized facilities:
  1048.  
  1049.  - Constructor:  ifstream::ifstream ()
  1050.      Make an `ifstream' associated with a new file for input.  (If you
  1051.      use this version of the constructor, you need to call
  1052.      `ifstream::open' before actually reading anything)
  1053.  
  1054.  - Constructor:  ifstream::ifstream (int FD)
  1055.      Make an `ifstream' for reading from a file that was already open,
  1056.      using file descriptor FD.  (This constructor is compatible with
  1057.      other versions of iostreams for POSIX systems, but is not part of
  1058.      the ANSI working paper.)
  1059.  
  1060.  - Constructor:  ifstream::ifstream (const char* FNAME [, int MODE
  1061.           [, int PROT]])
  1062.      Open a file `*FNAME' for this `ifstream' object.
  1063.  
  1064.      By default, the file is opened for input (with `ios::in' as MODE).
  1065.      If you use this constructor, the file will be closed when the
  1066.      `ifstream' is destroyed.
  1067.  
  1068.      You can use the optional argument MODE to specify how to open the
  1069.      file, by combining these enumerated values (with `|' bitwise or).
  1070.      (These values are actually defined in class `ios', so that all
  1071.      file-related streams may inherit them.)  Only some of these modes
  1072.      are defined in the latest draft ANSI specification; if portability
  1073.      is important, you may wish to avoid the others.
  1074.  
  1075.     `ios::in'
  1076.           Open for input.  (Included in ANSI draft.)
  1077.  
  1078.     `ios::out'
  1079.           Open for output.  (Included in ANSI draft.)
  1080.  
  1081.     `ios::ate'
  1082.           Set the initial input (or output) position to the end of the
  1083.           file.
  1084.  
  1085.     `ios::app'
  1086.           Seek to end of file before each write.  (Included in ANSI
  1087.           draft.)
  1088.  
  1089.     `ios::trunc'
  1090.           Guarantee a fresh file; discard any contents that were
  1091.           previously associated with it.
  1092.  
  1093.     `ios::nocreate'
  1094.           Guarantee an existing file; fail if the specified file did
  1095.           not already exist.
  1096.  
  1097.     `ios::noreplace'
  1098.           Guarantee a new file; fail if the specified file already
  1099.           existed.
  1100.  
  1101.     `ios::bin'
  1102.           Open as a binary file (on systems where binary and text files
  1103.           have different properties, typically how `\n' is mapped;
  1104.           included in ANSI draft).
  1105.  
  1106.      The last optional argument PROT is specific to Unix-like systems;
  1107.      it specifies the file protection (by default `644').
  1108.  
  1109.  - Method: void ifstream::open (const char* FNAME [, int MODE [, int
  1110.           PROT]])
  1111.      Open a file explicitly after the associated `ifstream' object
  1112.      already exists (for instance, after using the default
  1113.      constructor).  The arguments, options and defaults all have the
  1114.      same meanings as in the fully specified `ifstream' constructor.
  1115.  
  1116.    You can write data to class `ofstream' with any operation from class
  1117. `ostream'.  There are also a few specialized facilities:
  1118.  
  1119.  - Constructor:  ofstream::ofstream ()
  1120.      Make an `ofstream' associated with a new file for output.
  1121.  
  1122.  - Constructor:  ofstream::ofstream (int FD)
  1123.      Make an `ofstream' for writing to a file that was already open,
  1124.      using file descriptor FD.
  1125.  
  1126.  - Constructor:  ofstream::ofstream (const char* FNAME [, int MODE
  1127.           [, int PROT]])
  1128.      Open a file `*FNAME' for this `ofstream' object.
  1129.  
  1130.      By default, the file is opened for output (with `ios::out' as
  1131.      MODE).  You can use the optional argument MODE to specify how to
  1132.      open the file, just as described for `ifstream::ifstream'.
  1133.  
  1134.      The last optional argument PROT specifies the file protection (by
  1135.      default `644').
  1136.  
  1137.  - Destructor:  ofstream::~ofstream ()
  1138.      The files associated with `ofstream' objects are closed when the
  1139.      corresponding object is destroyed.
  1140.  
  1141.  - Method: void ofstream::open (const char* FNAME [, int MODE [, int
  1142.           PROT]])
  1143.      Open a file explicitly after the associated `ofstream' object
  1144.      already exists (for instance, after using the default
  1145.      constructor).  The arguments, options and defaults all have the
  1146.      same meanings as in the fully specified `ofstream' constructor.
  1147.  
  1148.    The class `fstream' combines the facilities of `ifstream' and
  1149. `ofstream', just as `iostream' combines `istream' and `ostream'.
  1150.  
  1151.    The class `fstreambase' underlies both `ifstream' and `ofstream'.
  1152. They both inherit this additional method:
  1153.  
  1154.  - Method: void fstreambase::close ()
  1155.      Close the file associated with this object, and set `ios::fail' in
  1156.      this object to mark the event.
  1157.  
  1158. 
  1159. File: iostream.info,  Node: Strings,  Prev: Files,  Up: Files and Strings
  1160.  
  1161. Reading and writing in memory
  1162. =============================
  1163.  
  1164.    The classes `istrstream', `ostrstream', and `strstream' provide some
  1165. additional features for reading and writing strings in memory--both
  1166. static strings, and dynamically allocated strings.  The underlying
  1167. class `strstreambase' provides some features common to all three;
  1168. `strstreambuf' underlies that in turn.
  1169.  
  1170.  - Constructor:  istrstream::istrstream (const char* STR [, int SIZE])
  1171.      Associate the new input string class `istrstream' with an existing
  1172.      static string starting at STR, of size SIZE.  If you do not
  1173.      specify SIZE, the string is treated as a `NUL' terminated string.
  1174.  
  1175.  - Constructor:  ostrstream::ostrstream ()
  1176.      Create a new stream for output to a dynamically managed string,
  1177.      which will grow as needed.
  1178.  
  1179.  - Constructor:  ostrstream::ostrstream (char* STR, int SIZE [,int
  1180.           MODE])
  1181.      A new stream for output to a statically defined string of length
  1182.      SIZE, starting at STR.  You may optionally specify one of the
  1183.      modes described for `ifstream::ifstream'; if you do not specify
  1184.      one, the new stream is simply open for output, with mode
  1185.      `ios::out'.
  1186.  
  1187.  - Method: int ostrstream::pcount ()
  1188.      Report the current length of the string associated with this
  1189.      `ostrstream'.
  1190.  
  1191.  - Method: char* ostrstream::str ()
  1192.      A pointer to the string managed by this `ostrstream'.  Implies
  1193.      `ostrstream::freeze()'.
  1194.  
  1195.  - Method: void ostrstream::freeze ([int N])
  1196.      If N is nonzero (the default), declare that the string associated
  1197.      with this `ostrstream' is not to change dynamically; while frozen,
  1198.      it will not be reallocated if it needs more space, and it will not
  1199.      be deallocated when the `ostrstream' is destroyed.  Use
  1200.      `freeze(1)' if you refer to the string as a pointer after creating
  1201.      it via `ostrstream' facilities.
  1202.  
  1203.      `freeze(0)' cancels this declaration, allowing a dynamically
  1204.      allocated string to be freed when its `ostrstream' is destroyed.
  1205.  
  1206.      If this `ostrstream' is already static--that is, if it was created
  1207.      to manage an existing statically allocated string--`freeze' is
  1208.      unnecessary, and has no effect.
  1209.  
  1210.  - Method: int ostrstream::frozen ()
  1211.      Test whether `freeze(1)' is in effect for this string.
  1212.  
  1213.  - Method: strstreambuf* strstreambase::rdbuf ()
  1214.      A pointer to the underlying `strstreambuf'.
  1215.  
  1216. 
  1217. File: iostream.info,  Node: Streambuf,  Next: Stdio,  Prev: Files and Strings,  Up: Top
  1218.  
  1219. Using the `streambuf' Layer
  1220. ***************************
  1221.  
  1222.    The `istream' and `ostream' classes are meant to handle conversion
  1223. between objects in your program and their textual representation.
  1224.  
  1225.    By contrast, the underlying `streambuf' class is for transferring
  1226. raw bytes between your program, and input sources or output sinks.
  1227. Different `streambuf' subclasses connect to different kinds of sources
  1228. and sinks.
  1229.  
  1230.    The GNU implementation of `streambuf' is still evolving; we describe
  1231. only some of the highlights.
  1232.  
  1233. * Menu:
  1234.  
  1235. * Areas::        Areas in a streambuf.
  1236. * Formatting::        C-style formatting for streambuf objects.
  1237. * Stdiobuf::        Wrappers for C stdio.
  1238. * Backing Up::        Marking and returning to a position.
  1239. * Indirectbuf::        Forwarding I/O activity.
  1240.  
  1241. 
  1242. File: iostream.info,  Node: Areas,  Next: Formatting,  Up: Streambuf
  1243.  
  1244. Areas of a `streambuf'
  1245. ======================
  1246.  
  1247.    Streambuf buffer management is fairly sophisticated (this is a nice
  1248. way to say "complicated").  The standard protocol has the following
  1249. "areas":
  1250.  
  1251.    * The "put area" contains characters waiting for output.
  1252.  
  1253.    * The "get area" contains characters available for reading.
  1254.  
  1255.    The GNU `streambuf' design extends this, but the details are still
  1256. evolving.
  1257.  
  1258. 
  1259. File: iostream.info,  Node: Formatting,  Next: Stdiobuf,  Prev: Areas,  Up: Streambuf
  1260.  
  1261. C-style formatting for `streambuf' objects
  1262. ==========================================
  1263.  
  1264.    The GNU `streambuf' class supports `printf'-like formatting and
  1265. scanning.
  1266.  
  1267.  - Method: int streambuf::vform (const char *FORMAT, ...)
  1268.      Similar to `fprintf(FILE, FORMAT, ...)'.  The FORMAT is a
  1269.      `printf'-style format control string, which is used to format the
  1270.      (variable number of) arguments, printing the result on the `this'
  1271.      streambuf.  The result is the number of characters printed.
  1272.  
  1273.  - Method: int streambuf::vform (const char *FORMAT, va_list ARGS)
  1274.      Similar to `vfprintf(FILE, FORMAT, ARGS)'.  The FORMAT is a
  1275.      `printf'-style format control string, which is used to format the
  1276.      argument list ARGS, printing the result on the `this' streambuf.
  1277.      The result is the number of characters printed.
  1278.  
  1279.  - Method: int streambuf::scan (const char *FORMAT, ...)
  1280.      Similar to `fscanf(FILE, FORMAT, ...)'.  The FORMAT is a
  1281.      `scanf'-style format control string, which is used to read the
  1282.      (variable number of) arguments from the `this' streambuf.  The
  1283.      result is the number of items assigned, or `EOF' in case of input
  1284.      failure before any conversion.
  1285.  
  1286.  - Method: int streambuf::vscan (const char *FORMAT, va_list ARGS)
  1287.      Like `streambuf::scan', but takes a single `va_list' argument.
  1288.  
  1289. 
  1290. File: iostream.info,  Node: Stdiobuf,  Next: Backing Up,  Prev: Formatting,  Up: Streambuf
  1291.  
  1292. Wrappers for C `stdio'
  1293. ======================
  1294.  
  1295.    A "stdiobuf" is a `streambuf' object that points to a `FILE' object
  1296. (as defined by `stdio.h').  All `streambuf' operations on the
  1297. `stdiobuf' are forwarded to the `FILE'.  Thus the `stdiobuf' object
  1298. provides a wrapper around a `FILE', allowing use of `streambuf'
  1299. operations on a `FILE'.  This can be useful when mixing C code with C++
  1300. code.
  1301.  
  1302.    The pre-defined streams `cin', `cout', and `cerr' are normally
  1303. implemented as `stdiobuf' objects that point to respectively `stdin',
  1304. `stdout', and `stderr'.  This is convenient, but it does cost some
  1305. extra overhead.
  1306.  
  1307.    If you set things up to use the implementation of `stdio' provided
  1308. with this library, then `cin', `cout', and `cerr' will be set up to to
  1309. use `stdiobuf' objects, since you get their benefits for free.  *Note C
  1310. Input and Output: Stdio.
  1311.  
  1312. 
  1313. File: iostream.info,  Node: Backing Up,  Next: Indirectbuf,  Prev: Stdiobuf,  Up: Streambuf
  1314.  
  1315. Backing up
  1316. ==========
  1317.  
  1318.    The GNU iostream library allows you to ask a `streambuf' to remember
  1319. the current position.  This allows you to go back to this position
  1320. later, after reading further.  You can back up arbitrary amounts, even
  1321. on unbuffered files or multiple buffers' worth, as long as you tell the
  1322. library in advance.  This unbounded backup is very useful for scanning
  1323. and parsing applications.  This example shows a typical scenario:
  1324.  
  1325.      // Read either "dog", "hound", or "hounddog".
  1326.      // If "dog" is found, return 1.
  1327.      // If "hound" is found, return 2.
  1328.      // If "hounddog" is found, return 3.
  1329.      // If none of these are found, return -1.
  1330.      int my_scan(streambuf* sb)
  1331.      {
  1332.          streammarker fence(sb);
  1333.          char buffer[20];
  1334.          // Try reading "hounddog":
  1335.          if (sb->sgetn(buffer, 8) == 8
  1336.              && strncmp(buffer, "hounddog", 8) == 0)
  1337.            return 3;
  1338.          // No, no "hounddog":  Back up to 'fence'
  1339.          sb->seekmark(fence); //
  1340.          // ... and try reading "dog":
  1341.          if (sb->sgetn(buffer, 3) == 3
  1342.              && strncmp(buffer, "dog", 3) == 0)
  1343.            return 1;
  1344.          // No, no "dog" either:  Back up to 'fence'
  1345.          sb->seekmark(fence); //
  1346.          // ... and try reading "hound":
  1347.          if (sb->sgetn(buffer, 5) == 5
  1348.              && strncmp(buffer, "hound", 5) == 0)
  1349.            return 2;
  1350.          // No, no "hound" either:  Back up and signal failure.
  1351.          sb->seekmark(fence); // Backup to 'fence'
  1352.          return -1;
  1353.      }
  1354.  
  1355.  - Constructor:  streammarker::streammarker (streambuf* SBUF)
  1356.      Create a `streammarker' associated with SBUF that remembers the
  1357.      current position of the get pointer.
  1358.  
  1359.  - Method: int streammarker::delta (streammarker& MARK2)
  1360.      Return the difference between the get positions corresponding to
  1361.      `*this' and MARK2 (which must point into the same `streambuffer'
  1362.      as `this').
  1363.  
  1364.  - Method: int streammarker::delta ()
  1365.      Return the position relative to the streambuffer's current get
  1366.      position.
  1367.  
  1368.  - Method: int streambuffer::seekmark (streammarker& MARK)
  1369.      Move the get pointer to where it (logically) was when MARK was
  1370.      constructed.
  1371.  
  1372. 
  1373. File: iostream.info,  Node: Indirectbuf,  Prev: Backing Up,  Up: Streambuf
  1374.  
  1375. Forwarding I/O activity
  1376. =======================
  1377.  
  1378.    An "indirectbuf" is one that forwards all of its I/O requests to
  1379. another streambuf.
  1380.  
  1381.    An `indirectbuf' can be used to implement Common Lisp
  1382. synonym-streams and two-way-streams:
  1383.  
  1384.      class synonymbuf : public indirectbuf {
  1385.         Symbol *sym;
  1386.         synonymbuf(Symbol *s) { sym = s; }
  1387.         virtual streambuf *lookup_stream(int mode) {
  1388.             return coerce_to_streambuf(lookup_value(sym)); }
  1389.      };
  1390.  
  1391. 
  1392. File: iostream.info,  Node: Stdio,  Next: Index,  Prev: Streambuf,  Up: Top
  1393.  
  1394. C Input and Output
  1395. ******************
  1396.  
  1397.    `libio' is distributed with a complete implementation of the ANSI C
  1398. `stdio' facility.  It is implemented using `streambuf' objects.  *Note
  1399. Wrappers for C `stdio': Stdiobuf.
  1400.  
  1401.    The `stdio' package is intended as a replacement for the whatever
  1402. `stdio' is in your C library.  Since `stdio' works best when you build
  1403. `libc' to contain it, and that may be inconvenient, it is not installed
  1404. by default.
  1405.  
  1406.    Extensions beyond ANSI:
  1407.  
  1408.    * A stdio `FILE' is identical to a streambuf.  Hence there is no
  1409.      need to worry about synchronizing C and C++ input/output--they are
  1410.      by definition always synchronized.
  1411.  
  1412.    * If you create a new streambuf sub-class (in C++), you can use it
  1413.      as a `FILE' from C.  Thus the system is extensible using the
  1414.      standard `streambuf' protocol.
  1415.  
  1416.    * You can arbitrarily mix reading and writing, without having to seek
  1417.      in between.
  1418.  
  1419.    * Unbounded `ungetc()' buffer.
  1420.  
  1421. 
  1422. File: iostream.info,  Node: Index,  Prev: Stdio,  Up: Top
  1423.  
  1424. Index
  1425. *****
  1426.  
  1427. * Menu:
  1428.  
  1429. * (:                                    States.
  1430. * (:                                    States.
  1431. * << on ostream:                        Operators.
  1432. * >> on istream:                        Operators.
  1433. * iostream destructor:                  Iostream.
  1434. * badbit:                               States.
  1435. * beg:                                  Output Position.
  1436. * cerr:                                 Operators.
  1437. * cin:                                  Operators.
  1438. * class fstreambase:                    Files.
  1439. * class fstream:                        Files.
  1440. * class ifstream:                       Files.
  1441. * class istrstream:                     Strings.
  1442. * class ostream:                        Files.
  1443. * class ostrstream:                     Strings.
  1444. * class strstreambase:                  Strings.
  1445. * class strstreambuf:                   Strings.
  1446. * class strstream:                      Strings.
  1447. * cout:                                 Operators.
  1448. * cur:                                  Output Position.
  1449. * dec:                                  Manipulators.
  1450. * destructor for iostream:              Iostream.
  1451. * end:                                  Output Position.
  1452. * endl:                                 Manipulators.
  1453. * ends:                                 Manipulators.
  1454. * eofbit:                               States.
  1455. * failbit:                              States.
  1456. * flush:                                Manipulators.
  1457. * flush:                                Ostream Housekeeping.
  1458. * fstream:                              Files.
  1459. * fstreambase:                          Files.
  1460. * fstreambase::close:                   Files.
  1461. * get area:                             Areas.
  1462. * goodbit:                              States.
  1463. * hex:                                  Manipulators.
  1464. * ifstream:                             Files.
  1465. * ifstream:                             Files and Strings.
  1466. * ifstream::ifstream:                   Files.
  1467. * ifstream::ifstream:                   Files.
  1468. * ifstream::ifstream:                   Files.
  1469. * ifstream::open:                       Files.
  1470. * ios::app:                             Files.
  1471. * ios::ate:                             Files.
  1472. * ios::bad:                             States.
  1473. * ios::beg:                             Input Position.
  1474. * ios::bin:                             Files.
  1475. * ios::bitalloc:                        Extending.
  1476. * ios::clear:                           States.
  1477. * ios::cur:                             Input Position.
  1478. * ios::dec:                             Format Control.
  1479. * ios::end:                             Input Position.
  1480. * ios::eof:                             States.
  1481. * ios::fail:                            States.
  1482. * ios::fill:                            Format Control.
  1483. * ios::fill:                            Format Control.
  1484. * ios::fixed:                           Format Control.
  1485. * ios::flags:                           Format Control.
  1486. * ios::flags:                           Format Control.
  1487. * ios::good:                            States.
  1488. * ios::hex:                             Format Control.
  1489. * ios::in:                              Files.
  1490. * ios::internal:                        Format Control.
  1491. * ios::ios:                             Ios.
  1492. * ios::iword:                           Extending.
  1493. * ios::iword:                           Extending.
  1494. * ios::left:                            Format Control.
  1495. * ios::nocreate:                        Files.
  1496. * ios::noreplace:                       Files.
  1497. * ios::oct:                             Format Control.
  1498. * ios::out:                             Files.
  1499. * ios::precision:                       Format Control.
  1500. * ios::precision:                       Format Control.
  1501. * ios::pword:                           Extending.
  1502. * ios::pword:                           Extending.
  1503. * ios::rdbuf:                           Streambuf from Ios.
  1504. * ios::rdstate:                         States.
  1505. * ios::right:                           Format Control.
  1506. * ios::scientific:                      Format Control.
  1507. * ios::seekdir:                         Output Position.
  1508. * ios::set:                             States.
  1509. * ios::setf:                            Format Control.
  1510. * ios::setf:                            Format Control.
  1511. * ios::setstate:                        States.
  1512. * ios::showbase:                        Format Control.
  1513. * ios::showpoint:                       Format Control.
  1514. * ios::showpos:                         Format Control.
  1515. * ios::skipws:                          Format Control.
  1516. * ios::stdio:                           Format Control.
  1517. * ios::sync_with_stdio:                 Synchronization.
  1518. * ios::tie:                             Synchronization.
  1519. * ios::tie:                             Synchronization.
  1520. * ios::trunc:                           Files.
  1521. * ios::unitbuf:                         Format Control.
  1522. * ios::unsetf:                          Format Control.
  1523. * ios::uppercase:                       Format Control.
  1524. * ios::width:                           Format Control.
  1525. * ios::width:                           Format Control.
  1526. * ios::xalloc:                          Extending.
  1527. * ios::~ios:                            Ios.
  1528. * iostream::iostream:                   Iostream.
  1529. * iostream::iostream:                   Iostream.
  1530. * istream::gcount:                      Istream Housekeeping.
  1531. * istream::get:                         String Input.
  1532. * istream::get:                         Char Input.
  1533. * istream::get:                         String Input.
  1534. * istream::get:                         Char Input.
  1535. * istream::getline:                     String Input.
  1536. * istream::gets:                        String Input.
  1537. * istream::ignore:                      Istream Housekeeping.
  1538. * istream::ipfx:                        Istream Housekeeping.
  1539. * istream::isfx:                        Istream Housekeeping.
  1540. * istream::istream:                     Istream.
  1541. * istream::istream:                     Istream.
  1542. * istream::peek:                        Char Input.
  1543. * istream::putback:                     Istream Housekeeping.
  1544. * istream::read:                        String Input.
  1545. * istream::scan:                        String Input.
  1546. * istream::seekg:                       Input Position.
  1547. * istream::seekg:                       Input Position.
  1548. * istream::tellg:                       Input Position.
  1549. * istream::unget:                       Istream Housekeeping.
  1550. * istream::vscan:                       String Input.
  1551. * istrstream:                           Files and Strings.
  1552. * istrstream:                           Strings.
  1553. * istrstream::istrstream:               Strings.
  1554. * oct:                                  Manipulators.
  1555. * ofstream:                             Files and Strings.
  1556. * ofstream::ofstream:                   Files.
  1557. * ofstream::ofstream:                   Files.
  1558. * ofstream::ofstream:                   Files.
  1559. * ofstream::open:                       Files.
  1560. * ofstream::~ofstream:                  Files.
  1561. * ostream:                              Files.
  1562. * ostream::form:                        Writing.
  1563. * ostream::opfx:                        Ostream Housekeeping.
  1564. * ostream::osfx:                        Ostream Housekeeping.
  1565. * ostream::ostream:                     Ostream.
  1566. * ostream::ostream:                     Ostream.
  1567. * ostream::put:                         Writing.
  1568. * ostream::seekp:                       Output Position.
  1569. * ostream::seekp:                       Output Position.
  1570. * ostream::tellp:                       Output Position.
  1571. * ostream::vform:                       Writing.
  1572. * ostream::write:                       Writing.
  1573. * ostrstream:                           Strings.
  1574. * ostrstream:                           Files and Strings.
  1575. * ostrstream::freeze:                   Strings.
  1576. * ostrstream::frozen:                   Strings.
  1577. * ostrstream::ostrstream:               Strings.
  1578. * ostrstream::ostrstream:               Strings.
  1579. * ostrstream::pcount:                   Strings.
  1580. * ostrstream::str:                      Strings.
  1581. * put area:                             Areas.
  1582. * setbase:                              Manipulators.
  1583. * setfill:                              Manipulators.
  1584. * setprecision:                         Format Control.
  1585. * setprecision:                         Manipulators.
  1586. * setting ios::precision:               Format Control.
  1587. * setting ios::width:                   Format Control.
  1588. * setw:                                 Manipulators.
  1589. * setw:                                 Format Control.
  1590. * streambuf::scan:                      Formatting.
  1591. * streambuf::vform:                     Formatting.
  1592. * streambuf::vform:                     Formatting.
  1593. * streambuf::vscan:                     Formatting.
  1594. * streambuffer::seekmark:               Backing Up.
  1595. * streammarker::delta:                  Backing Up.
  1596. * streammarker::delta:                  Backing Up.
  1597. * streammarker::streammarker:           Backing Up.
  1598. * strstream:                            Strings.
  1599. * strstreambase:                        Strings.
  1600. * strstreambase::rdbuf:                 Strings.
  1601. * strstreambuf:                         Strings.
  1602. * ws:                                   Manipulators.
  1603.  
  1604.  
  1605. 
  1606. Tag Table:
  1607. Node: Top985
  1608. Node: Introduction1471
  1609. Node: Copying2041
  1610. Node: Acknowledgements3254
  1611. Node: Operators4238
  1612. Node: Streams7003
  1613. Node: Ios7485
  1614. Node: States9086
  1615. Node: Format Control12064
  1616. Node: Manipulators17225
  1617. Node: Extending19198
  1618. Node: Synchronization20997
  1619. Node: Streambuf from Ios22311
  1620. Node: Ostream22661
  1621. Node: Writing23795
  1622. Node: Output Position25172
  1623. Node: Ostream Housekeeping26330
  1624. Node: Istream27586
  1625. Node: Char Input28963
  1626. Node: String Input29559
  1627. Node: Input Position33067
  1628. Node: Istream Housekeeping34274
  1629. Node: Iostream36579
  1630. Node: Files and Strings37870
  1631. Node: Files38497
  1632. Node: Strings43121
  1633. Node: Streambuf45567
  1634. Node: Areas46405
  1635. Node: Formatting46879
  1636. Node: Stdiobuf48288
  1637. Node: Backing Up49232
  1638. Node: Indirectbuf51501
  1639. Node: Stdio52043
  1640. Node: Index53071
  1641. 
  1642. End Tag Table
  1643.