IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/c++/sbuf.pub.z/sbuf.pub

Text File | 1998-10-30 | 20.0 KB | 265 lines

SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))                                                  SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))



NNNNAAAAMMMMEEEE
     streambuf - public interface of character buffering class

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_iiii_oooo_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>>

     _tttt_yyyy_pppp_eeee_dddd_eeee_ffff _llll_oooo_nnnn_gggg _ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff_,,,, _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_;;;;
     _cccc_llll_aaaa_ssss_ssss _iiii_oooo_ssss _{{{{
     _pppp_uuuu_bbbb_llll_iiii_cccc_::::
               _eeee_nnnn_uuuu_mmmm      _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr _{{{{ _bbbb_eeee_gggg_,,,, _cccc_uuuu_rrrr_,,,, _eeee_nnnn_dddd _}}}}_;;;;
               _eeee_nnnn_uuuu_mmmm      _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee _{{{{ _iiii_nnnn_,,,, _oooo_uuuu_tttt_,,,, _aaaa_tttt_eeee_,,,, _aaaa_pppp_pppp_,,,, _tttt_rrrr_uuuu_nnnn_cccc_,,,, _nnnn_oooo_cccc_rrrr_eeee_aaaa_tttt_eeee_,,,, _nnnn_oooo_rrrr_eeee_pppp_llll_aaaa_cccc_eeee _}}}} _;;;;
               _////_//// _aaaa_nnnn_dddd _llll_oooo_tttt_ssss _oooo_ffff _oooo_tttt_hhhh_eeee_rrrr _ssss_tttt_uuuu_ffff_ffff _...._...._.... _SSSS_eeee_eeee _iiii_oooo_ssss_((((_3333_CCCC_++++_++++_))))
     _}}}} _;;;;

     _cccc_llll_aaaa_ssss_ssss _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff _{{{{
     _pppp_uuuu_bbbb_llll_iiii_cccc _::::

               _iiii_nnnn_tttt       _iiii_nnnn______aaaa_vvvv_aaaa_iiii_llll_((((_))))_;;;;
               _iiii_nnnn_tttt       _oooo_uuuu_tttt______wwww_aaaa_iiii_tttt_iiii_nnnn_gggg_((((_))))_;;;;
               _iiii_nnnn_tttt       _ssss_bbbb_uuuu_mmmm_pppp_cccc_((((_))))_;;;;
               _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff_****_ssss_eeee_tttt_bbbb_uuuu_ffff_((((_cccc_hhhh_aaaa_rrrr_**** _pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _llll_eeee_nnnn_))))_;;;;
               _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss _ssss_eeee_eeee_kkkk_pppp_oooo_ssss_((((_ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_,,,, _iiii_nnnn_tttt _====_iiii_oooo_ssss_::::_::::_iiii_nnnn_||||_iiii_oooo_ssss_::::_::::_oooo_uuuu_tttt_))))_;;;;
               _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff_,,,, _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr_,,,, _iiii_nnnn_tttt _====_iiii_oooo_ssss_::::_::::_iiii_nnnn_||||_iiii_oooo_ssss_::::_::::_oooo_uuuu_tttt_))))_;;;;
               _iiii_nnnn_tttt       _ssss_gggg_eeee_tttt_cccc_((((_))))_;;;;
               _iiii_nnnn_tttt       _ssss_gggg_eeee_tttt_nnnn_((((_cccc_hhhh_aaaa_rrrr_**** _pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _nnnn_))))_;;;;
               _iiii_nnnn_tttt       _ssss_nnnn_eeee_xxxx_tttt_cccc_((((_))))_;;;;
               _iiii_nnnn_tttt       _ssss_pppp_uuuu_tttt_bbbb_aaaa_cccc_kkkk_cccc_((((_cccc_hhhh_aaaa_rrrr_))))_;;;;
               _iiii_nnnn_tttt       _ssss_pppp_uuuu_tttt_cccc_((((_iiii_nnnn_tttt _cccc_))))_;;;;
               _iiii_nnnn_tttt       _ssss_pppp_uuuu_tttt_nnnn_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr_**** _ssss_,,,, _iiii_nnnn_tttt _nnnn_))))_;;;;
               _vvvv_oooo_iiii_dddd      _ssss_tttt_oooo_ssss_ssss_cccc_((((_))))_;;;;
               _vvvv_iiii_rrrr_tttt_uuuu_aaaa_llll _iiii_nnnn_tttt_ssss_yyyy_nnnn_cccc_((((_))))_;;;;
     _}}}}_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff class supports buffers into which characters can be
     inserted (put) or from which characters can be fetched (gotten).
     Abstractly, such a buffer is a sequence of characters together with one
     or two pointers (a get and/or a put pointer) that define the location at
     which characters are to be inserted or fetched.  The pointers should be
     thought of as pointing between characters rather than at them.  This
     makes it easier to understand the boundary conditions (a pointer before
     the first character or after the last).  Some of the effects of getting
     and putting are defined by this class but most of the details are left to
     specialized classes derived from _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff.  (See _ffff_iiii_llll_eeee_bbbb_uuuu_ffff(3C++),
     _ssss_ssss_bbbb_uuuu_ffff(3C++), and _ssss_tttt_dddd_iiii_oooo_bbbb_uuuu_ffff(3C++).)

     Classes derived from _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff vary in their treatments of the get and
     put pointers.  The simplest are unidirectional buffers which permit only
     gets or only puts.  Such classes serve as pure sources (producers) or
     sinks (consumers) of characters.  Queuelike buffers (e.g., see
     _ssss_tttt_rrrr_ssss_tttt_rrrr_eeee_aaaa_mmmm(3C++) and _ssss_ssss_bbbb_uuuu_ffff(3C++)) have a put and a get pointer which move
     independently of each other.  In such buffers characters that are stored



                                                                        PPPPaaaaggggeeee 1111






SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))                                                  SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))



     are held (i.e., queued) until they are later fetched.  Filelike buffers
     (e.g., _ffff_iiii_llll_eeee_bbbb_uuuu_ffff, see _ffff_iiii_llll_eeee_bbbb_uuuu_ffff(3C++)) permit both gets and puts but have
     only a single pointer.  (An alternative description is that the get and
     put pointers are tied together so that when one moves so does the other.)

     Most _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff member functions are organized into two phases.  As far as
     possible, operations are performed inline by storing into or fetching
     from arrays (the _g_e_t _a_r_e_a and the _p_u_t _a_r_e_a, which together form the
     _r_e_s_e_r_v_e _a_r_e_a, or _b_u_f_f_e_r).  From time to time, virtual functions are
     called to deal with collections of characters in the get and put areas.
     That is, the virtual functions are called to fetch more characters from
     the ultimate producer or to flush a collection of characters to the
     ultimate consumer.  Generally the user of a _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff does not have to
     know anything about these details, but some of the public members pass
     back information about the state of the areas.  Further detail about
     these areas is provided in _ssss_bbbb_uuuu_ffff_...._pppp_rrrr_oooo_tttt(3C++), which describes the protected
     interface.

     The public member functions of the _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff class are described below.
     In the following descriptions assume:
     - _i, _n, and _l_e_n are _iiii_nnnn_tttts.
     - _c is an _iiii_nnnn_tttt. It always holds a ``character'' value or _EEEE_OOOO_FFFF.  A
     ``character'' value is always positive even when _cccc_hhhh_aaaa_rrrr is normally sign
     extended.
     - _s_b and _s_b_1 are _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff_****s.
     - _p_t_r is a _cccc_hhhh_aaaa_rrrr_****.
     - _o_f_f is a _ssss_tttt_rrrr_eeee_aaaa_mmmm_oooo_ffff_ffff.
     - _p_o_s is a _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss.
     - _d_i_r is a _ssss_eeee_eeee_kkkk______dddd_iiii_rrrr.
     - _m_o_d_e is an _iiii_nnnn_tttt representing an _oooo_pppp_eeee_nnnn______mmmm_oooo_dddd_eeee.

     Public member functions:

     _i_====_s_b_----_>>>>_iiii_nnnn______aaaa_vvvv_aaaa_iiii_llll_((((_))))
          Returns the number of characters that are immediately available in
          the get area for fetching.  _i characters may be fetched with a
          guarantee that no errors will be reported.

     _i_====_s_b_----_>>>>_oooo_uuuu_tttt______wwww_aaaa_iiii_tttt_iiii_nnnn_gggg_((((_))))
          Returns the number of characters in the put area that have not been
          consumed (by the ultimate consumer).

     _c_====_s_b_----_>>>>_ssss_bbbb_uuuu_mmmm_pppp_cccc_((((_))))
          Moves the get pointer forward one character and returns the
          character it moved past.  Returns _EEEE_OOOO_FFFF if the get pointer is
          currently at the end of the sequence.

     _p_o_s_====_s_b_----_>>>>_ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_o_f_f_,,,, _d_i_r_,,,, _m_o_d_e_))))
          Repositions the get and/or put pointers.  _m_o_d_e specifies whether the
          put pointer (_iiii_oooo_ssss_::::_::::_oooo_uuuu_tttt bit set) or the get pointer (_iiii_oooo_ssss_::::_::::_iiii_nnnn bit set)
          is to be modified.  Both bits may be set in which case both pointers
          should be affected.  _o_f_f is interpreted as a byte offset.  (Notice



                                                                        PPPPaaaaggggeeee 2222






SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))                                                  SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))



          that it is a signed quantity.)  The meanings of possible values of
          _d_i_r are

          _iiii_oooo_ssss_::::_::::_bbbb_eeee_gggg
               The beginning of the stream.

          _iiii_oooo_ssss_::::_::::_cccc_uuuu_rrrr
               The current position.

          _iiii_oooo_ssss_::::_::::_eeee_nnnn_dddd
               The end of the stream (end of file.)

     Not all classes derived from _ssss_tttt_rrrr_eeee_aaaa_mmmm_bbbb_uuuu_ffff support repositioning.  _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_))))
     will return _EEEE_OOOO_FFFF if the class does not support repositioning.  If the
     class does support repositioning, _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_)))) will return the new position
     or _EEEE_OOOO_FFFF on error.

     _p_o_s_====_s_b_----_>>>>_ssss_eeee_eeee_kkkk_pppp_oooo_ssss_((((_p_o_s_,,,, _m_o_d_e_))))
          Repositions the streambuf get and/or put pointer to _p_o_s.  _m_o_d_e
          specifies which pointers are affected as for _ssss_eeee_eeee_kkkk_oooo_ffff_ffff_((((_)))).  Returns _p_o_s
          (the argument) or _EEEE_OOOO_FFFF if the class does not support repositioning or
          an error occurs.  In general a _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss should be treated as a
          ``magic cookie'' and no arithmetic should be performed on it.  Two
          particular values have special meaning:

          _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_((((_0000_))))
               The beginning of the file.

          _ssss_tttt_rrrr_eeee_aaaa_mmmm_pppp_oooo_ssss_((((_EEEE_OOOO_FFFF_))))
               Used as an error indication.

     _c_====_s_b_----_>>>>_ssss_gggg_eeee_tttt_cccc_((((_))))
          Returns the character after the get pointer.  Contrary to what most
          people expect from the name _I_T _D_O_E_S _N_O_T _M_O_V_E _T_H_E _G_E_T _P_O_I_N_T_E_R .
          Returns _EEEE_OOOO_FFFF if there is no character available.

     _s_b_1_====_s_b_----_>>>>_ssss_eeee_tttt_bbbb_uuuu_ffff_((((_p_t_r_,,,, _l_e_n_,,,, _i_))))
          Offers the _l_e_n bytes starting at _p_t_r as the reserve area.  If _p_t_r is
          null or _l_e_n is zero or less, then an unbuffered state is requested.
          Whether the offered area is used, or a request for unbuffered state
          is honored depends on details of the derived class.  _ssss_eeee_tttt_bbbb_uuuu_ffff_((((_))))
          normally returns _s_b, but if it does not accept the offer or honor
          the request, it returns 0.

     _i_====_s_b_----_>>>>_ssss_gggg_eeee_tttt_nnnn_((((_p_t_r_,,,, _n_))))
          Fetches the _n characters following the get pointer and copies them
          to the area starting at _p_t_r.  When there are fewer than _n characters
          left before the end of the sequence _ssss_gggg_eeee_tttt_nnnn_((((_)))) fetches whatever
          characters remain.  _ssss_gggg_eeee_tttt_nnnn_((((_)))) repositions the get pointer following
          the fetched characters and returns the number of characters fetched.





                                                                        PPPPaaaaggggeeee 3333






SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))                                                  SSSSBBBBUUUUFFFF....PPPPUUUUBBBB((((3333CCCC++++++++))))



     _c_====_s_b_----_>>>>_ssss_nnnn_eeee_xxxx_tttt_cccc_((((_))))
          Moves the get pointer forward one character and returns the
          character following the new position.  It returns _EEEE_OOOO_FFFF if the pointer
          is currently at the end of the sequence or is at the end of the
          sequence after moving forward.

     _i_====_s_b_----_>>>>_ssss_pppp_uuuu_tttt_bbbb_aaaa_cccc_kkkk_cccc_((((_c_))))
          Moves the get pointer back one character.  _c must be the current
          content of the sequence just before the get pointer.  The underlying
          mechanism may simply back up the get pointer or may rearrange its
          internal data structures so the _c is saved.  Thus the effect of
          _ssss_pppp_uuuu_tttt_bbbb_aaaa_cccc_kkkk_cccc_((((_)))) is undefined if _c is not the character before the get
          pointer.  _ssss_pppp_uuuu_tttt_bbbb_aaaa_cccc_kkkk_cccc_((((_)))) returns _EEEE_OOOO_FFFF when it fails.  The conditions
          under which it can fail depend on the details of the derived class.

     _i_====_s_b_----_>>>>_ssss_pppp_uuuu_tttt_cccc_((((_c_))))
          Stores _c after the put pointer, and moves the put pointer past the
          stored character; usually this extends the sequence.  It returns _EEEE_OOOO_FFFF
          when an error occurs.  The conditions that can cause errors depend
          on the derived class.

     _i_====_s_b_----_>>>>_ssss_pppp_uuuu_tttt_nnnn_((((_p_t_r_,,,, _n_))))
          Stores the _n characters starting at _p_t_r after the put pointer and
          moves the put pointer past them.  _ssss_pppp_uuuu_tttt_nnnn_((((_)))) returns _i, the number of
          characters stored successfully.  Normally _i is _n, but it may be less
          when errors occur.

     _s_b_----_>>>>_ssss_tttt_oooo_ssss_ssss_cccc_((((_))))
          Moves the get pointer forward one character.  If the pointer started
          at the end of the sequence this function has no effect.

     _i_====_s_b_----_>>>>_ssss_yyyy_nnnn_cccc_((((_))))
          Establishes consistency between the internal data structures and the
          external source or sink.  The details of this function depend on the
          derived class.  Usually this ``flushes'' any characters that have
          been stored but not yet consumed, and ``gives back'' any characters
          that may have been produced but not yet fetched.  _ssss_yyyy_nnnn_cccc_((((_)))) returns _EEEE_OOOO_FFFF
          to indicate errors.

CCCCAAAAVVVVEEEEAAAATTTTSSSS
     _ssss_eeee_tttt_bbbb_uuuu_ffff does not really belong in the public interface. It is there for
     compatibility with the stream package.

     Requiring the program to provide the previously fetched character to
     _ssss_pppp_uuuu_tttt_bbbb_aaaa_cccc_kkkk is probably a botch.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _iiii_oooo_ssss(3C++) _iiii_ssss_tttt_rrrr_eeee_aaaa_mmmm(3C++) _oooo_ssss_tttt_rrrr_eeee_aaaa_mmmm(3C++), _ssss_bbbb_uuuu_ffff_...._pppp_rrrr_oooo_tttt(3C++)







                                                                        PPPPaaaaggggeeee 4444