about the "strt" module

crux-00013: $SRC/strt/README.strt

* "strt": reference counted dynamically allocated strings

  The "str" functions provide basic resizable string.



* The "strt" interface

  The interface is largely self evident.

  A string is properly declared and initialized this way:

      #include "str/str.h"


      struct strt a_strt;

      a_strt = strt_new ();

  Such strings are initially created with a reference count
  of 1.

  The reference count can be incremented or decremented:

	strt_ref (r);
        strt_unref (r);

  The current reference count is available to facilitate
  copy-on-write algorithms.

	int x = strt_refs (r);

  The "str/str.h" string manipulation functions
  are translated to strt versions:

  int strt_length (strt);
    Return the length of a string.

  char * strt_view (strt, int pos, int l);
   Return a character pointer into a string.
   The pointer returned is invalidated by any
   call to a "strt_" function that might change the
   size of this string.

  void strt_set_length (strt, int l);
   Change the size of a string, appending 0s as needed.

  void strt_set (strt, int l, char * s);
  void strt_set0 (strt, char * s);
  void strt_adjoin (strt, char c);
  void strt_append (strt, int l, char * s);
  void strt_append0 (strt, char *);
  void strt_copy (strt, strt);
  void strt_cat (strt, strt);
    Ways to build strings.

  void strt_trim (strt);
    Internally, strings may allocate more memory
    than is needed.  This function trims a string
    to use minimal memory.  (See the function ar_trim
    in utils/README.ar)

  int strt_overlaps (strt s, int l, char * c);
    Return 1 if c[0..(l-1)] is contained in s.
    Panic if c and/or l are known to be invalid.
    Otherwise return 0.

/*

    This file is part of Crux.

    Crux is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Crux is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Crux.  If not, see <http://www.gnu.org/licenses/>.

*/