1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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:
|
