forked from Archive/PX4-Autopilot
179 lines
5.2 KiB
Plaintext
179 lines
5.2 KiB
Plaintext
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:
|
|
|