diff options
Diffstat (limited to 'apps/systemlib/uthash/doc/utstring.txt')
| -rw-r--r-- | apps/systemlib/uthash/doc/utstring.txt | 178 |
1 files changed, 0 insertions, 178 deletions
diff --git a/apps/systemlib/uthash/doc/utstring.txt b/apps/systemlib/uthash/doc/utstring.txt deleted file mode 100644 index abfdcd107..000000000 --- a/apps/systemlib/uthash/doc/utstring.txt +++ /dev/null @@ -1,178 +0,0 @@ -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: - |