Skunkware 5/Skunkware 5.iso/man/cat.3/DString.3

Text File | 1995-07-26 | 11.2 KB | 199 lines

     TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))



     _________________________________________________________________

     NNNNAAAAMMMMEEEE
          Tcl_DStringInit, Tcl_DStringAppend,
          Tcl_DStringAppendElement, Tcl_DStringStartSublist,
          Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue,
          Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult -
          manipulate dynamic strings

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt(_d_s_P_t_r)

          char *
          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnndddd(_d_s_P_t_r, _s_t_r_i_n_g, _l_e_n_g_t_h)

          char *
          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt(_d_s_P_t_r, _s_t_r_i_n_g)

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggSSSSttttaaaarrrrttttSSSSuuuubbbblllliiiisssstttt(_d_s_P_t_r)

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggEEEEnnnnddddSSSSuuuubbbblllliiiisssstttt(_d_s_P_t_r)

          int
          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggLLLLeeeennnnggggtttthhhh(_d_s_P_t_r)

          char *
          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggVVVVaaaalllluuuueeee(_d_s_P_t_r)

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggTTTTrrrruuuunnnncccc(_d_s_P_t_r, _n_e_w_L_e_n_g_t_h)

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggFFFFrrrreeeeeeee(_d_s_P_t_r)

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggRRRReeeessssuuuulllltttt(_i_n_t_e_r_p, _d_s_P_t_r)

     AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
          Tcl_DString   *_d_s_P_t_r      (in/out)  Pointer   to   structure
                                              that is used to manage a
                                              dynamic string.

          char          *_s_t_r_i_n_g     (in)      Pointer to characters to
                                              add to dynamic string.

          int           _l_e_n_g_t_h      (in)      Number   of   characters
                                              from  string  to  add to
                                              dynamic string.  If  -1,
                                              add all characters up to
                                              null         terminating
                                              character.

          int           _n_e_w_L_e_n_g_t_h   (in)      New length  for  dynamic



     Page 1                                          (printed 7/10/95)






     TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))



                                              string,   not  including
                                              null         terminating
                                              character.
     _________________________________________________________________


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          Dynamic  strings  provide  a  mechanism  for   building   up
          arbitrarily long strings by gradually appending information.
          If the dynamic string is short then there will be no  memory
          allocation  overhead;  as the string gets larger, additional
          space will be allocated as needed.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt initializes a dynamic string to zero length.
          The  Tcl_DString  structure  must have been allocated by the
          caller.  No assumptions are made about the current state  of
          the  structure; anything already in it is discarded.  If the
          structure has been used previously,  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggFFFFrrrreeeeeeee  should
          be  called first to free up any memory allocated for the old
          string.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnndddd adds new information to a dynamic  string,
          allocating  more memory for the string if needed.  If _l_e_n_g_t_h
          is less than zero then everything in _s_t_r_i_n_g is  appended  to
          the  dynamic  string;  otherwise _l_e_n_g_t_h specifies the number
          of bytes to append.  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnndddd returns a pointer  to
          the  characters  of  the new string.  The string can also be
          retrieved  from  the  _s_t_r_i_n_g  field   of   the   Tcl_DString
          structure.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt  is  similar  to  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnndddd
          except  that  it  doesn't take a _l_e_n_g_t_h argument (it appends
          all of _s_t_r_i_n_g) and it converts the string to a  proper  list
          element  before  appending.  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt adds a
          separator space before the new list element unless  the  new
          list element is the first in a list or sub-list (i.e. either
          the current string is  empty,  or  it  contains  the  single
          character  ``{'',  or the last two characters of the current
          string are  ``  {'').   TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt  returns  a
          pointer to the characters of the new string.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggSSSSttttaaaarrrrttttSSSSuuuubbbblllliiiisssstttt  and  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggEEEEnnnnddddSSSSuuuubbbblllliiiisssstttt  can  be
          used  to create nested lists.  To append a list element that
          is itself a  sublist,  first  call  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggSSSSttttaaaarrrrttttSSSSuuuubbbblllliiiisssstttt,
          then  call TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggAAAAppppppppeeeennnnddddEEEElllleeeemmmmeeeennnntttt for each of the elements
          in the sublist, then call TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggEEEEnnnnddddSSSSuuuubbbblllliiiisssstttt to  end  the
          sublist.   TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggSSSSttttaaaarrrrttttSSSSuuuubbbblllliiiisssstttt appends a space character
          if needed, followed by an open brace;  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggEEEEnnnnddddSSSSuuuubbbblllliiiisssstttt
          appends a close brace.  Lists can be nested to any depth.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggLLLLeeeennnnggggtttthhhh is a macro that returns the current length
          of  a  dynamic  string  (not  including the terminating null



     Page 2                                          (printed 7/10/95)






     TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))          TTTTccccllll ((((7777....0000))))          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggIIIInnnniiiitttt((((3333))))



          character).  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggVVVVaaaalllluuuueeee is a   macro  that  returns  a
          pointer to the current contents of a dynamic string.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggTTTTrrrruuuunnnncccc truncates  a  dynamic  string  to  a  given
          length.   It has no effect if the string was already smaller
          than  _n_e_w_L_e_n_g_t_h.   This  procedure  does  not  free  up  the
          string's  storage  space, even if the string is truncated to
          zero length,  so  TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggFFFFrrrreeeeeeee  will  still  need  to  be
          called.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggFFFFrrrreeeeeeee should be called when you're finished  using
          the  string.   It frees up any memory that was allocated for
          the string and reinitializes the string's value to an  empty
          string.

          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggRRRReeeessssuuuulllltttt sets the result of _i_n_t_e_r_p to the value  of
          the dynamic string given by _d_s_P_t_r.  It does this by moving a
          pointer from _d_s_P_t_r to _i_n_t_e_r_p->_r_e_s_u_l_t.  This saves  the  cost
          of   allocating   new   memory   and   copying  the  string.
          TTTTccccllll____DDDDSSSSttttrrrriiiinnnnggggRRRReeeessssuuuulllltttt also reinitializes the dynamic  string  to
          an empty string.


     KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
          append, dynamic string, free, result






























     Page 3                                          (printed 7/10/95)