README.md

   1 # libstring [![Codacy Badge](https://app.codacy.com/project/badge/Grade/265e20e3a7b6416d85609612e600d16f)](https://www.codacy.com/gh/carmesim/libstring?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=carmesim/libstring&amp;utm_campaign=Badge_Grade) [![CodeFactor](https://www.codefactor.io/repository/github/carmesim/libstring/badge)](https://www.codefactor.io/repository/github/carmesim/libstring) [![Build Status](https://travis-ci.org/carmesim/libstring.svg?branch=master)](https://travis-ci.org/carmesim/libstring) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
   2
   3   **Early work in progress. ⚠️*
   4
   5 `libstring` aims to be a highly portable, [Valgrind](https://www.valgrind.org/)-passing, single-header library that brings better support for strings and string manipulation to ANSI C. This library does **not** depend on `string.h` or `strings.h`, using only `stdio.h`, `stdlib.h` and `stdbool.h` (when available, falls back to the usual typedef when not on C99 or newer).
   6
   7 ## Currently implemented public functions
   8
   9 ```C
  10 cstr_t * string_init(const char * origin);                 // Initializes a new cstr_t *.
  11 void  string_free_all (void);                              // Frees all heap allocations made by libstring.
  12 char * string_first_token(char * str, char * delim);       // Sets up tokenization and returns the first token
  13 void string_replace(cstr_t *str, char * old, const char * new); // Replaces all instances of `old` to `new` within `str`
  14 char * string_get_token(char * delim);                     // Returns a token from the char * str passed onto the previous function
  15 cstr_t * string_to_lower_case(cstr_t * origin);            // Returns a new cstr_t * with the contents of origin lower-cased
  16 cstr_t * string_to_upper_case(cstr_t * origin);            // Returns a new cstr_t * with the contents of origin upper-cased
  17 cstr_t * string_concat(cstr_t * str1, const char * str2);  // Returns a new cstr_t * with the concatenation of str1 and str2
  18 size_t string_concat_to(cstr_t * str1, const char * str2); // Concatenates str1 and str2 to str1.
  19 bool string_contains(cstr_t * str1, const char * str2);    // Returns true if str2 is a substring of str1.
  20 size_t string_update(cstr_t * str, const char * new_val);  // Updates the value of str. Increases its memory reservation if needed.
  21 bool string_swap(cstr_t * str1, cstr_t * str2);            // Swaps the contents of str1 and str2.
  22 bool string_reserve(cstr_t *str, size_t capacity);         // Increases str's memory reservation
  23 size_t string_replace_char(cstr_t *str, char before, char after); // Replaces all instances of a char with another.
  24 cstr_t * string_mid(cstr_t * str, size_t pos, long length); // Returns a substring of a given string starting at position pos with a given length.
  25 cstr_t * string_left(cstr_t * str, size_t length); // Returns the first (length) characters of a string starting from the left.
  26 cstr_t * string_right(cstr_t * str, long length); // Returns the first (length) characters of a string starting from the right.
  27 ```
  28
  29 The other functions defined in `libstring.c` are internal and not accessible.
  30
  31 ## Building the test file
  32
  33 The unit tests are done using [Criterion](https://github.com/Snaipe/Criterion).
  34 Running the `run-tests.sh` file builds the test file and runs it through Valgrind.
  35
  36
  37 ## For C89
  38
  39 The only thing deterring builds for C89 are the C++-style comments.
  40
  41 You can solve this problem by removing all comments and then building:
  42
  43 ```console
  44 gcc -fpreprocessed -dD -E src/libstring.c >> src/89libstring.c
  45 gcc -fpreprocessed -dD -E src/libstring.h >> src/89libstring.h
  46 ```
  47
  48 You can then use `89libstring.c` and `89libstring.h` on C89 projects.
  49