Libdynamic

A Fast and Usable C dynamic string library.

Key Features • Installation • Usage • Structures • Functions • License

Key Features

Libdynamic is a C dynamic string library with a focus on performance and usability, bringing string manipulation closer to that of languages such as C++. It achieves this through length-aware strings and pre-allocation to minimize the number of resizings necessarry. This makes it an excellent choice for applications with even a large number of strings, as memory is kept fairly dense as long as strings are not appended an outrageous amount of times.

Warning Keep in mind that Libdymamic's resizing strategy is optimisitic, which is to say it always assumes there is enough memory left for allocation. If this fails, the library will automatically exit.

Installation

Dependencies	Usage
	Unit testing
	Compilation

You can install libdynamic alognside your project as a git submodule. This is the preferred way of using the library as it will 'freeze' the version being used and associate it to you project. If you wish to use a newer version of the library, you will have to manually pull it and commit the change to your project.

1. Navigate to the directory you want to clone libdynamic at. This can be somewhere like vendor/:

   mkdir vendor && cd vendor

2. Add libdynamic as a submodule:

   git submodule add https://github.com/Trantorian1/dynamic.git

Usage

Libdynamic does not come with pre-built binaries yet, so you will have to build from source yourself.

1. Head to the folder in which you cloned libdynamic and run the following command:

   make final

   If this does not work, make sure you have docker installed and the docker engine running as libdynamic uses it to compile and run its unit tests.

2. Once all unit tests have been run, you will find the following archive:

   bin/libdynamic.a

Make sure to link this archive using -Lvendor/dynamic/bin -ldynamic -Ivendor when compiling your code.

• Here's a basic example of how to use libdynamic in your C code:

  #include <stdio.h>
  #include "dynamic/string.h"
  
  int  main(void)
  {
    t_str  *str;
  
    // creates a new dynamic string from a C string
    str = str_create("");
  
    // you can append to a string, one character at a time...
    str_append_char(str, 'H');
    str_append_char(str, 'e');
    str_append_char(str, 'l');
    str_append_char(str, 'l');
    str_append_char(str, 'o');
  
    // or one C string at a time...
    str_append_str(str, "world");
  
    // you can also insert characters...
    str_insert_char(str, ' ', 5);
  
    // or strings...
    str_insert_str(str, "there ", 6);
  
    // how about prepending? Yep, you can do that too!
    str_prepend_char(str, ' ');
    str_prepend_str(str, "Hey!");
  
    // of course you might want to retrieve the string's value and length
    printf("str='%s' len=%zu\n", str->get, str->len);
  
    // remember that strings created with str_create must be destroyed with
    // str_destroy otherwise you risk having still reachable memory
    str_destroy(str);
  
    return (0);
  }

Structures

Libdynamic introduces a new t_str structure as well as the type t_cstr.

// new dynamic string structure
typedef struct s_str
{
	char *_Nonnull get;
	size_t         len;
}	t_str;

// slightly more idomatic typedef to c's default strings
typedef char * t_cstr;

Note t_str also has several library-reserved attributes. You can find those in include/s_str.h. Make sure you know what you are doing as erroneous manipulation might break the library!

Functions

• t_str *_Nullable    str_create(t_cstr _Nonnull cstr)

  Creates a new dynamic string of the given C string.

• void                str_destroy(t_str *_Nullable str)

  Frees up the memory used by a dynamic string.

• t_str *_Nullable    str_append_char(t_str *_Nonnull str, char c)

  Appends a character at the end of a dynamic string.

• t_str *_Nullable    str_append_str(t_str *_Nonnull str, t_cstr _Nonnull cstr)

  Appends a C string at the end of a dynamic string.

• t_str *_Nullable    str_prepend_char(t_str *_Nonnull str, char c)

  Prepends a character at the front of a dynamic string.

• t_str *_Nullable    str_prepend_str(t_str *_Nonnull str, t_cstr _Nonnull cstr)

  Prepends a C string at the frint of a dynamic string.

• t_str *_Nullable    str_insert_char(t_str *_Nonnull str, char c, size_t index)

  Inserts a character at a given index in a dynamic string.

• t_str *_Nullable    str_insert_str(t_str *_Nonnull str, t_cstr _Nonnull cstr, size_t index)

  Inserts a C string at a given index in a dynamic string.

License

MIT