What is cstring?

Version 3.6.2

Introduction

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

License

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

C-API

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()
  puts(str.ptr);

  // destroy it
  cstring_destroy(&str);

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).