home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / c++ / ssbuf.z / ssbuf
Encoding:
Text File  |  2002-10-03  |  6.7 KB  |  117 lines
  1. SSBUF(3C)                                            Last changed: 10-20-98
  2.  
  3.  
  4. NNAAMMEE
  5.      ssttrrssttrreeaammbbuuff - ssttrreeaammbbuuff specialized to arrays
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<iioossttrreeaamm..hh>>
  9.      ##iinncclluuddee <<ssttrrssttrreeaamm..hh>>
  10.  
  11.      ccllaassss ssttrrssttrreeaammbbuuff :: ppuubblliicc ssttrreeaammbbuuff {{
  12.      ppuubblliicc::
  13.                ssttrrssttrreeaammbbuuff(()) ;;
  14.                ssttrrssttrreeaammbbuuff((cchhaarr**,, iinntt,, cchhaarr**));;
  15.                ssttrrssttrreeaammbbuuff((iinntt));;
  16.                ssttrrssttrreeaammbbuuff((uunnssiiggnneedd cchhaarr**,, iinntt,, uunnssiiggnneedd cchhaarr**));;
  17.                ssttrrssttrreeaammbbuuff((vvooiidd** ((**aa))((lloonngg)),, vvooiidd((**ff))((vvooiidd**))));;
  18.  
  19.           vvooiidd ffrreeeezzee((iinntt nn==11)) ;;
  20.           cchhaarr**     ssttrr(());;
  21.           vviirrttuuaall ssttrreeaammbbuuff**  sseettbbuuff((cchhaarr**,, iinntt))
  22.      }};;
  23.  
  24. IIMMPPLLEEMMEENNTTAATTIIOONN
  25.      IRIX systems
  26.  
  27. DDEESSCCRRIIPPTTIIOONN
  28.      A ssttrrssttrreeaammbbuuff is a ssttrreeaammbbuuff that uses an array of bytes (a string)
  29.      to hold the sequence of characters.  Given the convention that a cchhaarr**
  30.      should be interpreted as pointing just before the cchhaarr it really
  31.      points at, the mapping between the abstract get/put pointers (see
  32.      ssbbuuff..ppuubb(3C)) and cchhaarr** pointers is direct.  Moving the pointers
  33.      corresponds exactly to incrementing and decrementing the cchhaarr** values.
  34.  
  35.      To accommodate the need for arbitrary length strings, ssttrrssttrreeaammbbuuff
  36.      supports a dynamic mode.  When a ssttrrssttrreeaammbbuuff is in dynamic mode,
  37.      space for the character sequence is allocated as needed.  When the
  38.      sequence is extended too far, it will be copied to a new array.
  39.  
  40.      The following descriptions make the following assumptions:
  41.  
  42.      * _s_s_b is a ssttrrssttrreeaammbbuuff**.
  43.  
  44.      * _n is an iinntt.
  45.  
  46.      * _p_t_r and _p_s_t_a_r_t are cchhaarr**s or uunnssiiggnneedd cchhaarr**s.
  47.  
  48.      * _a is a vvooiidd** ((**))((lloonngg)).
  49.  
  50.      * _f is a vvooiidd** ((**))((vvooiidd**)).
  51.  
  52.    CCoonnssttrruuccttoorrss
  53.      ssttrrssttrreeaammbbuuff(())
  54.           Constructs an empty ssttrrssttrreeaammbbuuff in dynamic mode.  This means
  55.           that space will be automatically allocated to accommodate the
  56.           characters that are put into the ssttrrssttrreeaammbbuuff (using operators
  57.           nneeww and ddeelleettee).  Because this may require copying the original
  58.           characters, it is recommended that when many characters are to be
  59.           inserted, the program should use sseettbbuuff(()) (described on this man
  60.           page) to inform the ssttrrssttrreeaammbbuuff.
  61.  
  62.      ssttrrssttrreeaammbbuuff((_a,, _f))
  63.           Constructs an empty ssttrrssttrreeaammbbuuff in dynamic mode.  _a is used as
  64.           the allocator function in dynamic mode.  The argument passed to _a
  65.           will be a lloonngg denoting the number of bytes to be allocated.  If
  66.           _a is null, ooppeerraattoorr nneeww will be used.  _f is used to free (or
  67.           delete) areas returned by _a.  The argument to _f will be a pointer
  68.           to the array allocated by _a.  If _f is null, ooppeerraattoorr ddeelleettee is
  69.           used.
  70.  
  71.      ssttrrssttrreeaammbbuuff((_n))
  72.           Constructs an empty ssttrrssttrreeaammbbuuff in dynamic mode.  The initial
  73.           allocation of space will be at least _n bytes.
  74.  
  75.      ssttrrssttrreeaammbbuuff((_p_t_r,, _n,, _p_s_t_a_r_t))
  76.           Constructs a ssttrrssttrreeaammbbuuff to use the bytes starting at _p_t_r.  The
  77.           ssttrrssttrreeaammbbuuff will be in static mode; it will not grow
  78.           dynamically.  If _n is positive, then the _n bytes starting at _p_t_r
  79.           are used as the ssttrrssttrreeaammbbuuff.  If _n is zero, _p_t_r is assumed to
  80.           point to the beginning of a null terminated string and the bytes
  81.           of that string (not including the terminating null character)
  82.           will constitute the ssttrrssttrreeaammbbuuff.  If _n is negative, the
  83.           ssttrrssttrreeaammbbuuff is assumed to continue indefinitely.  The get
  84.           pointer is initialized to _p_t_r.  The put pointer is initialized to
  85.           _p_s_t_a_r_t.  If _p_s_t_a_r_t is null, then stores will be treated as
  86.           errors.  If _p_s_t_a_r_t is non-null, then the initial sequence for
  87.           fetching (the get area) consists of the bytes between _p_t_r and
  88.           _p_s_t_a_r_t.  If _p_s_t_a_r_t is null, then the initial get area consists of
  89.           the entire array.
  90.  
  91.    MMeemmbbeerr FFuunnccttiioonnss
  92.      _s_s_b-->>ffrreeeezzee((_n))
  93.           Inhibits (when _n is nonzero) or permits (when _n is zero)
  94.           automatic deletion of the current array.  Deletion normally
  95.           occurs when more space is needed or when _s_s_b is being destroyed.
  96.           Only space obtained via dynamic allocation is ever freed.  It is
  97.           an error (and the effect is undefined) to store characters into a
  98.           ssttrrssttrreeaammbbuuff that was in dynamic allocation mode and is now
  99.           frozen.  It is possible, however, to thaw (unfreeze) such a
  100.           ssttrrssttrreeaammbbuuff and resume storing characters.
  101.  
  102.      _p_t_r==_s_s_b-->>ssttrr(())
  103.           Returns a pointer to the first cchhaarr of the current array and
  104.           freezes _s_s_b.  If _s_s_b was constructed with an explicit array, _p_t_r
  105.           will point to that array.  If _s_s_b is in dynamic allocation mode,
  106.           but nothing has yet been stored, _p_t_r may be null.
  107.  
  108.      _s_s_b-->>sseettbbuuff((00,,_n))
  109.           _s_s_b remembers _n and the next time it does a dynamic mode
  110.           allocation, it makes sure that at least _n bytes are allocated.
  111.  
  112. SSEEEE AALLSSOO
  113.      ssbbuuff..ppuubb(3C), ssttrrssttrreeaamm(3C)
  114.  
  115.      This man page is available only online.
  116.  
  117.