c_cpp/lib/uthash/doc/utstring.txt

   1 utstring: dynamic string macros for C
   2 =====================================
   3 Troy D. Hanson <tdh@tkhanson.net>
   4 v2.0.2, March 2017
   5
   6 Here's a link back to the https://github.com/troydhanson/uthash[GitHub project page].
   7
   8 Introduction
   9 ------------
  10 A set of basic dynamic string macros for C programs are included with
  11 uthash in `utstring.h`.  To use these in your own C program, just copy
  12 `utstring.h` into your source directory and use it in your programs.
  13
  14   #include "utstring.h"
  15
  16 The dynamic string supports operations such as inserting data, concatenation,
  17 getting the length and content, substring search, and clear.  It's ok to put
  18 binary data into a utstring too. The string <<operations,operations>> are
  19 listed below.
  20
  21 Some utstring operations are implemented as functions rather than macros.
  22
  23 Download
  24 ~~~~~~~~
  25 To download the `utstring.h` header file,
  26 follow the links on https://github.com/troydhanson/uthash to clone uthash or get a zip file,
  27 then look in the src/ sub-directory.
  28
  29 BSD licensed
  30 ~~~~~~~~~~~~
  31 This software is made available under the
  32 link:license.html[revised BSD license].
  33 It is free and open source.
  34
  35 Platforms
  36 ~~~~~~~~~
  37 The 'utstring' macros have been tested on:
  38
  39  * Linux,
  40  * Windows, using Visual Studio 2008 and Visual Studio 2010
  41
  42 Usage
  43 -----
  44
  45 Declaration
  46 ~~~~~~~~~~~
  47
  48 The dynamic string itself has the data type `UT_string`.  It is declared like,
  49
  50   UT_string *str;
  51
  52 New and free
  53 ~~~~~~~~~~~~
  54 The next step is to create the string using `utstring_new`. Later when you're
  55 done with it, `utstring_free` will free it and all its content.
  56
  57 Manipulation
  58 ~~~~~~~~~~~~
  59 The `utstring_printf` or `utstring_bincpy` operations insert (copy) data into
  60 the string. To concatenate one utstring to another, use `utstring_concat`.  To
  61 clear the content of the string, use `utstring_clear`. The length of the string
  62 is available from `utstring_len`, and its content from `utstring_body`. This
  63 evaluates to a `char*`.  The buffer it points to is always null-terminated.
  64 So, it can be used directly with external functions that expect a string.
  65 This automatic null terminator is not counted in the length of the string.
  66
  67 Samples
  68 ~~~~~~~
  69
  70 These examples show how to use utstring.
  71
  72 .Sample 1
  73 -------------------------------------------------------------------------------
  74 #include <stdio.h>
  75 #include "utstring.h"
  76
  77 int main() {
  78     UT_string *s;
  79
  80     utstring_new(s);
  81     utstring_printf(s, "hello world!" );
  82     printf("%s\n", utstring_body(s));
  83
  84     utstring_free(s);
  85     return 0;
  86 }
  87 -------------------------------------------------------------------------------
  88
  89 The next example demonstrates that `utstring_printf` 'appends' to the string.
  90 It also shows concatenation.
  91
  92 .Sample 2
  93 -------------------------------------------------------------------------------
  94 #include <stdio.h>
  95 #include "utstring.h"
  96
  97 int main() {
  98     UT_string *s, *t;
  99
 100     utstring_new(s);
 101     utstring_new(t);
 102
 103     utstring_printf(s, "hello " );
 104     utstring_printf(s, "world " );
 105
 106     utstring_printf(t, "hi " );
 107     utstring_printf(t, "there " );
 108
 109     utstring_concat(s, t);
 110     printf("length: %u\n", utstring_len(s));
 111     printf("%s\n", utstring_body(s));
 112
 113     utstring_free(s);
 114     utstring_free(t);
 115     return 0;
 116 }
 117 -------------------------------------------------------------------------------
 118
 119 The next example shows how binary data can be inserted into the string. It also
 120 clears the string and prints new data into it.
 121
 122 .Sample 3
 123 -------------------------------------------------------------------------------
 124 #include <stdio.h>
 125 #include "utstring.h"
 126
 127 int main() {
 128     UT_string *s;
 129     char binary[] = "\xff\xff";
 130
 131     utstring_new(s);
 132     utstring_bincpy(s, binary, sizeof(binary));
 133     printf("length is %u\n", utstring_len(s));
 134
 135     utstring_clear(s);
 136     utstring_printf(s,"number %d", 10);
 137     printf("%s\n", utstring_body(s));
 138
 139     utstring_free(s);
 140     return 0;
 141 }
 142 -------------------------------------------------------------------------------
 143
 144 [[operations]]
 145 Reference
 146 ---------
 147 These are the utstring operations.
 148
 149 Operations
 150 ~~~~~~~~~~
 151
 152 [width="100%",cols="50<m,40<",grid="none",options="none"]
 153 |===============================================================================
 154 | utstring_new(s) | allocate a new utstring
 155 | utstring_renew(s) | allocate a new utstring (if s is `NULL`) otherwise clears it
 156 | utstring_free(s) | free an allocated utstring
 157 | utstring_init(s)  | init a utstring (non-alloc)
 158 | utstring_done(s) | dispose of a utstring (non-alloc)
 159 | utstring_printf(s,fmt,...) | printf into a utstring (appends)
 160 | utstring_bincpy(s,bin,len) | insert binary data of length len (appends)
 161 | utstring_concat(dst,src) | concatenate src utstring to end of dst utstring
 162 | utstring_clear(s) | clear the content of s (setting its length to 0)
 163 | utstring_len(s) | obtain the length of s as an unsigned integer
 164 | utstring_body(s) | get `char*` to body of s (buffer is always null-terminated)
 165 | utstring_find(s,pos,str,len) | forward search from pos for a substring
 166 | utstring_findR(s,pos,str,len) | reverse search from pos for a substring
 167 |===============================================================================
 168
 169 New/free vs. init/done
 170 ~~~~~~~~~~~~~~~~~~~~~~
 171 Use `utstring_new` and `utstring_free` to allocate a new string or free it.  If
 172 the UT_string is statically allocated, use `utstring_init` and `utstring_done`
 173 to initialize or free its internal memory.
 174
 175 Substring search
 176 ~~~~~~~~~~~~~~~~
 177 Use `utstring_find` and `utstring_findR` to search for a substring in a utstring.
 178 It comes in forward and reverse varieties. The reverse search scans from the end of
 179 the string backward. These take a position to start searching from, measured from 0
 180 (the start of the utstring).  A negative position is counted from the end of
 181 the string, so, -1 is the last position.  Note that in the reverse search, the
 182 initial position anchors to the 'end' of the substring being searched for;
 183 e.g., the 't' in 'cat'. The return value always refers to the offset where the
 184 substring 'starts' in the utstring.  When no substring match is found, -1 is
 185 returned.
 186
 187 For example if a utstring called `s` contains:
 188
 189   ABC ABCDAB ABCDABCDABDE
 190
 191 Then these forward and reverse substring searches for `ABC` produce these results:
 192
 193   utstring_find(  s, -9, "ABC", 3 ) = 15
 194   utstring_find(  s,  3, "ABC", 3 ) =  4
 195   utstring_find(  s, 16, "ABC", 3 ) = -1
 196   utstring_findR( s, -9, "ABC", 3 ) = 11
 197   utstring_findR( s, 12, "ABC", 3 ) =  4
 198   utstring_findR( s,  2, "ABC", 3 ) =  0
 199
 200 "Multiple use" substring search
 201 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 202 The preceding examples show "single use" versions of substring matching, where
 203 the internal Knuth-Morris-Pratt (KMP) table is internally built and then freed
 204 after the search. If your program needs to run many searches for a given
 205 substring, it is more efficient to save the KMP table and reuse it.
 206
 207 To reuse the KMP table, build it manually and then pass it into the internal
 208 search functions. The functions involved are:
 209
 210  _utstring_BuildTable  (build the KMP table for a forward search)
 211  _utstring_BuildTableR (build the KMP table for a reverse search)
 212  _utstring_find        (forward search using a prebuilt KMP table)
 213  _utstring_findR       (reverse search using a prebuilt KMP table)
 214
 215 This is an example of building a forward KMP table for the substring "ABC", and
 216 then using it in a search:
 217
 218  long *KPM_TABLE, offset;
 219  KPM_TABLE = (long *)malloc( sizeof(long) * (strlen("ABC")) + 1));
 220  _utstring_BuildTable("ABC", 3, KPM_TABLE);
 221  offset = _utstring_find(utstring_body(s), utstring_len(s), "ABC", 3, KPM_TABLE );
 222  free(KPM_TABLE);
 223
 224 Note that the internal `_utstring_find` has the length of the UT_string as its
 225 second argument, rather than the start position. You can emulate the position
 226 parameter by adding to the string start address and subtracting from its length.
 227
 228 // vim: set nowrap syntax=asciidoc:
 229