Import of Troy Hanson's uthash package, v1.9.6

2026-10-23 04:13:33 +08:00 · 2012-08-19 01:31:27 -07:00
parent a86974e3e3
commit 2c85075221
8 changed files with 4273 additions and 0 deletions
@@ -0,0 +1,178 @@
+utstring: dynamic string macros for C 
+=====================================
+Troy D. Hanson <thanson@users.sourceforge.net>
+v1.9.5, November 2011
+
+include::sflogo.txt[]
+include::topnav_utstring.txt[]
+
+Introduction
+------------
+include::toc.txt[]
+
+A set of very basic dynamic string macros for C programs are included with
+uthash in `utstring.h`.  To use these macros in your own C program, just
+copy `utstring.h` into your source directory and use it in your programs.
+
+  #include "utstring.h"
+
+The dynamic string supports basic operations such as inserting data (including
+binary data-- despite its name, utstring is not limited to string content),
+concatenation, getting the length and content, and clearing it.  The string
+<<operations,operations>> are listed below.
+
+Download
+~~~~~~~~
+To download the `utstring.h` header file, follow the link on the
+http://uthash.sourceforge.net[uthash home page]. 
+
+BSD licensed
+~~~~~~~~~~~~
+This software is made available under the 
+link:license.html[revised BSD license]. 
+It is free and open source. 
+
+Platforms
+~~~~~~~~~
+The 'utstring' macros have been tested on:
+
+ * Linux, 
+ * Windows, using Visual Studio 2008 and Visual Studio 2010
+
+Usage 
+-----
+
+Declaration
+~~~~~~~~~~~
+
+The dynamic string itself has the data type `UT_string`.  It is declared like,
+
+  UT_string *str;
+
+New and free
+~~~~~~~~~~~~
+The next step is to create the string using `utstring_new`. Later when you're
+done with it, `utstring_free` will free it and all its content. 
+
+Manipulation
+~~~~~~~~~~~~
+The `utstring_printf` or `utstring_bincpy` operations insert (copy) data into
+the string. To concatenate one utstring to another, use `utstring_concat`.  To
+clear the content of the string, use `utstring_clear`. The length of the string
+is available from `utstring_len`, and its content from `utstring_body`. This 
+evaluates to a `char*`.  The buffer it points to is always null-terminated.
+So, it can be used directly with external functions that expect a string.
+This automatic null terminator is not counted in the length of the string.
+
+Samples
+~~~~~~~
+
+These examples show how to use utstring.
+
+.Sample 1
+-------------------------------------------------------------------------------
+#include <stdio.h>
+#include "utstring.h"
+
+int main() {
+    UT_string *s;
+
+    utstring_new(s);
+    utstring_printf(s, "hello world!" );
+    printf("%s\n", utstring_body(s));
+
+    utstring_free(s);
+    return 0;
+}
+-------------------------------------------------------------------------------
+
+The next example is meant to demonstrate that printf 'appends' to the string.
+It also shows concatenation.
+
+.Sample 2
+-------------------------------------------------------------------------------
+#include <stdio.h>
+#include "utstring.h"
+
+int main() {
+    UT_string *s, *t;
+
+    utstring_new(s);
+    utstring_new(t);
+
+    utstring_printf(s, "hello " );
+    utstring_printf(s, "world " );
+
+    utstring_printf(t, "hi " );
+    utstring_printf(t, "there " );
+
+    utstring_concat(s, t);
+    printf("length: %u\n", utstring_len(s));
+    printf("%s\n", utstring_body(s));
+
+    utstring_free(s);
+    utstring_free(t);
+    return 0;
+}
+-------------------------------------------------------------------------------
+
+The last example shows how binary data can be inserted into the string. It also
+clears the string and prints new data into it.
+
+.Sample 3
+-------------------------------------------------------------------------------
+#include <stdio.h>
+#include "utstring.h"
+
+int main() {
+    UT_string *s;
+    char binary[] = "\xff\xff";
+
+    utstring_new(s);
+    utstring_bincpy(s, binary, sizeof(binary));
+    printf("length is %u\n", utstring_len(s));
+
+    utstring_clear(s);
+    utstring_printf(s,"number %d", 10);
+    printf("%s\n", utstring_body(s));
+
+    utstring_free(s);
+    return 0;
+}
+-------------------------------------------------------------------------------
+
+[[operations]]
+Reference
+---------
+These are the utstring operations. 
+
+Operations
+~~~~~~~~~~
+
+[width="100%",cols="50<m,40<",grid="none",options="none"]
+|===============================================================================
+| utstring_new(s) | allocate a new utstring
+| utstring_renew(s) | allocate a new utstring (if s is `NULL`) otherwise clears it
+| utstring_free(s) | free an allocated utstring
+| utstring_init(s)  |  init a utstring (non-alloc)
+| utstring_done(s) |  dispose of a utstring (non-allocd)
+| utstring_printf(s,fmt,...) | printf into a utstring (appends)
+| utstring_bincpy(s,bin,len) | insert binary data of length len (appends)
+| utstring_concat(dst,src) | concatenate src utstring to end of dst utstring
+| utstring_clear(s) | clear the content of s (setting its length to 0)
+| utstring_len(s) | obtain the length of s as an unsigned integer
+| utstring_body(s) | get `char*` to body of s (buffer is always null-terminated)
+|===============================================================================
+
+Notes
+~~~~~
+
+1. `utstring_new` and `utstring_free` are used to allocate a new string and free it,
+   while `utstring_init` and `utstring_done` can be used if the UT_string is already
+   allocated and just needs to be initialized or have its internal resources
+   freed.
+2. `utstring_printf` is actually a function defined statically in `utstring.h`
+   rather than a macro.
+
+// vim: set nowrap syntax=asciidoc: 
+