# utstring: dynamic string macros for C

Troy D. Hanson
`<thanson@users.sourceforge.net>`
version 1.9, March 2010

## Introduction

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 are listed below.

### Download

To download the `utstring.h` header file, follow the link on the uthash home page.

### BSD licensed

This software is made available under the 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;
    }

## Reference

These are the utstring operations.

### Operations

`utstring_new(s)` | allocate a new utstring
`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.