README.md (5293B)
1 # cstring 2 3 A simple and lightweight string library for C inspired by C++'s STL `string` class, 4 but with a many additions. 5 6 ## Building 7 8 `cstring` is a static library. The header file is installed in `/usr/local/include` and 9 the library file in `/usr/local/lib`. 10 11 In order to install it do the following 12 ```shell 13 $ cd /path/to/cstring 14 $ sudo make install clean 15 ``` 16 17 You can also run a few tests 18 ```shell 19 $ cd /path/to/cstring/tests 20 $ make && make run clean 21 ``` 22 23 In order to make a distribution do 24 ```shell 25 $ cd /path/to/cstring 26 $ make dist 27 ``` 28 29 If you want to uninstall the library do the following 30 ```shell 31 $ cd /path/to/cstring 32 $ sudo make uninstall 33 ``` 34 35 A file using `cstring` has to be linked using the `-lcstring` linker flag. 36 In case you want to run your project in debug mode, compile the library using the `-DCSTRING_DBG` option. 37 38 ## Usage 39 40 When using this library, you must **always** call the `cstring_create` and `cstring_delete` 41 functions whenever you want to make a new instance of `cstring` and stop using it respectively, 42 in order not to cause any memory leaks, as there's no *constructor* and *destructor* to do it for you. 43 44 The recommended way of initializing an empty string is by doing `cstring foo = cstring_create(CSTRING_INIT_EMPTY)`. 45 46 Read the `man` page for more detailed info. 47 48 ## Functions 49 50 * `cstring_create`: Initiliaze string. 51 * `cstring_delete`: Deallocate string. 52 * `cstring_assign`: Assign new string. 53 * `cstring_insert`: Insert at a specific index. 54 * `cstring_append`: Append to end of string. 55 * `cstring_prepend`: Prepend to beginning of string. 56 * `cstring_erase`: Erase portion of string. 57 * `cstring_erase_matching`: Erase first match. 58 * `cstring_erase_all_matching`: Erase all matches. 59 * `cstring_trim`: Trim character. 60 * `cstring_push_back`: Add character to end of string. 61 * `cstring_pop_back`: Remove the last character from string. 62 * `cstring_replace_char`: Replace character at a specific index. 63 * `cstring_replace_str`: Replace portion of string. 64 * `cstring_substr`: Extract a substring. 65 * `cstring_swap`: Swap contents of two strings. 66 * `cstring_sort`: Sort an array of `cstring` objects. 67 * `cstring_sort_partial`: Like `cstring_sort` but for part of the array. 68 * `cstring_sort_chars`: Sort `cstring`'s contents. 69 * `cstring_sort_chars_partial`: Like `cstring_sort_chars` but for part of the string. 70 * `cstring_shrink_to_fit`: Shrink string's capacity to fit its size. 71 * `cstring_clear`: Clear contents of string 72 * `cstring_find`: Find first occurence of a pattern in string. 73 * `cstring_rfind`: Fnid last occurence of a pattern in string. 74 * `cstring_find_first_of`: Find first occurence of specified characters in string. 75 * `cstring_find_first_not_of`: Find the first character that does not match any of the specified characters. 76 * `cstring_find_last_of`: Find last occurence of specified characters in string. 77 * `cstring_find_last_not_of`: Find the last character that does not match any of the specified characters. 78 * `cstring_front`: Get first character in string. 79 * `cstring_back`: Get last character in string. 80 * `cstring_empty`: Check if string is empty. 81 * `cstring_starts_with_str`: Check if string starts with specified `char *`. 82 * `cstring_ends_with_str`: Check if string ends with specified `char *`. 83 * `cstring_starts_with_char`: Check if string starts with specified `char`. 84 * `cstring_ends_with_char`: Check if string ends with specified `char`. 85 * `cstring_data`: Get string's content in raw bytes. 86 * `cstring_copy`: Copy contents of a `char *`. 87 * `cstring_resize`: Resize string. 88 * `cstring_getline`: Read a line from a `FILE` stream. 89 * `cstring_equal`: Check if `lhs == rhs`. 90 * `cstring_greater`: Check if `lhs > rhs`. 91 * `cstring_greater_or_equal`: Check if `lhs >= rhs`. 92 * `cstring_less`: Check if `lhs < rhs`. 93 * `cstring_less_or_equal`: Check if `lhs <= rhs`. 94 95 `lhs`: Left hand side 96 `rhs`: Right hand side 97 98 ## Macros 99 100 * `CSTRING_OUT_OF_BOUNDS`: Check if value is out of bounds. 101 * `CSTRING_ARR_LEN`: Determine an array's length. The macro must be called in the same function the array is declared. 102 * `CSTRING_MALLOC`: Allocate memory with error checking. 103 The following macros can only be used in debug mode 104 * `CSTIRNG_DBG_LOG`: Prints a message in the format of `DEBUG: file:line:func(): msg`. 105 * `CSTRING_DBG_LOG_CSTR_INFO`: Prints all the contents of a `cstring` struct. The argument *has* to be a pointer. 106 * `CSTRING_DBG_LOG_CSTR_INFO_NPTR`: Like `CSTRING_DBG_LOG_CSTR_INFO` but the argument has to be a non-pointer. 107 * `CSTRING_DBG_LOG_STR_INFO`: Print contents of a normal string. 108 109 ## Constants 110 111 * `CSTRING_NPOS`: Signifies that a pattern hasn't been found inside the string. Its value is -1. 112 * `CSTRING_INIT_EMPTY`: Used with `cstring_create` in case the string is to be initiliazed as empty. 113 114 ## Flags 115 116 * `CSTRING_SORT_ASCENDING`: Sort in ascending order. 117 * `CSTRING_SORT_DESCENDING`: Sort in descending order. 118 * `CSTRING_SORT_CALLBACK`: Sort using a callback function. 119 * `CSTRING_SORT_REST`: Sort the rest of the array. 120 121 ## Example 122 123 See the test programs in `tests` for more. 124 125 ```c 126 #include <cstring.h> 127 128 /* outputs "Foobar" to the screen */ 129 int 130 main(int argc, char **argv) 131 { 132 cstring s = cstring_create("Foo"); 133 cstring_append(&s, "bar"); 134 printf("%s\n", s.str); 135 cstring_delete(&s); 136 137 return 0; 138 } 139 ```