Synesis Software

What is cstring?

Version 3.6.2


cstring is a small and simple C library for the definition and manipulation of expandable C-style strings.


cstring is released under the BSD license, which basically means its free for any use, but you can't claim it's yours.


The library is implemented in C, and provides a simple C-API, consisting of the following functions: Consider the following example, which creates a cstring instance, and then appends two other C-style strings to it, prints it to stdout, truncates it, prints it again, and then destroys it:

  cstring_t       str;

  // create a string from the C-style string "Hello,"
  cstring_create(&str, "Hello,");

  // append a space
  cstring_appendLen(&str, " ", 1);

  // append "World!"
  cstring_append(&str, "World!");

  // print it out, passing length+ptr to printf
  printf("cstring contents: %.*s\n", str.len, str.ptr);

  // truncate it to length 5
  cstring_truncate(&str, 5);

  // print it again, passing the ptr member to puts()

  // destroy it

Custom Memory

cstring supports different allocation from differnet memory libraries. For example, to create a string that allocates its buffer from the Win32 process heap, specify the CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY to cstring_createEx, as in:

  cstring_t       str;

  cstring_createEx(&str, "G'day!", CSTRING_F_USE_WIN32_PROCESSHEAP_MEMORY, NULL, 0);

All subsequent operations that require memory (de-)allocation on this string will use thw Win32 process heap, e.g.:

  cstring_assign(&str, "Welcome to the Pleasuredome"); // Will go to the Win32 process heap

Borrowed Memory

cstring supports the specification of external memory blocks for use by cstring instances, via specification of the CSTRING_F_MEMORY_IS_BORROWED flag, as in:

  char                buff[101];
  struct cstring_t    str;
  CSTRING_RC          rc  =   cstring_createEx( &str
                                              , "Some contents for this "
                                              , CSTRING_F_MEMORY_IS_BORROWED
                                              , &buff[0]
                                              , sizeof(buff));
The str instance will do all its memory (de-)allocation with respect to the fixed buffer buff. It will not comply with any operation that requires it to have a capacity of more than sizeof(buff).

cstring Library documentation (c) Matthew Wilson and Synesis Software Pty Ltd, 1994-2009