cstring.3 (7331B)
1 .Dd cstring\-VERSION 2 .Dt CSTRING 3 3 .Sh NAME 4 .Nm cstring 5 .Nd A simple and lightweight string library for C inspired by C++'s 6 STL string class 7 .Sh LIBRARY 8 C String (-lcstring) 9 .Sh SYNOPSIS 10 #include <cstring.h> 11 .Sh DESCRIPTION 12 .Pp 13 The 14 .Nm 15 library offers a lightweight and fast way to manage 16 strings with a wide range of useful functions. 17 .Bl -tag -width Ds 18 typedef struct _cstring { 19 size_t len; /* string length */ 20 size_t capacity; /* string capacity */ 21 char *str; /* contents of string */ 22 CSTRING_SORT_ASCENDING 0x01 /* sort in ascending order */ 23 CSTRING_SORT_DESCENDING 0x02 /* sort in descending order */ 24 CSTRING_SORT_CALLBACK 0x04 /* sort using a callback function */ 25 CSTRING_SORT_REST 0x10 /* sort the rest of the array */ 26 } cstring; 27 .It typedef\ int\ (*cstring_sort_callback)(const void *, const void *); 28 Used in sort functions. 29 .El 30 .Sh USAGE 31 You must 32 .Ar always 33 call the 34 .Fn cstring_create 35 and 36 .Fn cstring_delete 37 functions whenever you want to make a new instance of 38 .Ar cstring 39 and stop using it respectively, in order to not cause any memory 40 leaks. 41 .Pp 42 The recommended way of initializing an empty string is by doing 43 .Ar cstring foo = cstring_create(CSTRING_INIT_EMPTY) 44 .Pp 45 If a function requires a 46 .Ar char * 47 you can access the 48 .Ar .str 49 field and pass it to the function. 50 .Sh FUNCTIONS 51 .Bl -tag -width Ds 52 .It void Fn cstring_create "const char *s" 53 Instanciates and initializes a 54 .Ar cstring 55 object. 56 .It void Fn cstring_delete "cstring *cs" 57 Deallocate string. 58 .It void Fn cstring_assign "cstring *cs" "const char *s" 59 Assign a new string to current string. 60 .It void Fn cstring_insert "cstring *cs" "const char *s" "size_t i" 61 Insert at a specific index. 62 .It void Fn cstring_append "cstring *cs" "const char *s" 63 Append to end of string. 64 .It void Fn cstring_prepend "cstring *cs" "const char *s" 65 Prepend to beginning of string. 66 .It void Fn cstring_erase "cstring *cs" "size_t pos" "size_t len" 67 Erase a portion of the string. 68 .It void Fn cstring_erase_matching "cstring *cs" "const char *s" 69 Erase first match from string. 70 .It void Fn cstring_erase_all_matching "cstring *cs" "const char *s" 71 Erase all matches from string. 72 .It void Fn cstring_trim "cstring *cs" "const char *s" 73 Trim characters from string. 74 .It void Fn cstring_push_back "cstring *cs" "char c" 75 Add a character at the end of the string. 76 .It void Fn cstring_pop_back "cstring *cs" 77 Remove the last character in the string. 78 .It void Fn cstring_replace_char "cstring *cs" "size_t i" "char c" 79 Replace character at a specific index. 80 .It void Fn cstring_replace_str "cstring *cs" "const char *s" "size_t pos" "size_t olen" 81 Replace portion of the string. 82 .Ar olen 83 is the length of the old string. 84 An example use could be: 85 .br 86 .Fn cstring_replace_str "&string" "new_word" "cstring_find(&s, old_word)" "old_word_len" 87 .It cstring Fn cstring_substr "cstring *cs" "size_t pos" "size_t len" 88 Extract a substring from current string. 89 .It void Fn cstring_swap "cstring *lhs" "cstring *rhs" 90 Swap contents of two strings. 91 .It void Fn cstring_sort "cstring *cs" "size_t len" "int flags" "cstring_sort_callback callback" 92 Sort an array of cstrings. 93 If you want to use the builtin comparison pass 94 .Ar NULL 95 in the last argument. 96 In case you want to use your own callback use the 97 .Ar CSTRING_SORT_CALLBACK 98 flag and pass your own callback function in the last argument. 99 You can also combine flags using the bitwise OR operator. 100 .It void Fn cstring_sort_partial "cstring *cs" "size_t pos" "size_t len" "int flags" "cstring_sort_callback callback" 101 Like 102 .Fn cstring_sort 103 but for specified part of an array. 104 .It void Fn cstring_sort_chars "cstring *cs" "int flags" "cstring_sort_callback callback" 105 Sort a cstring's contents. 106 If you want to use the builtin comparison pass 107 .Ar NULL 108 in the last argument. 109 In case you want to use your own callback use the 110 .Ar CSTRING_SORT_CALLBACK 111 flag and pass your own callback function in the last argument. 112 You can also combine flags using the bitwise OR operator. 113 .It void Fn cstring_sort_chars_partial "cstring *cs" "size_t pos" "size_t len" "int flags" "cstring_sort_callback callback" 114 Like 115 .Fn cstring_sort_chars 116 but for specified part of string. 117 .It void Fn cstring_shrink_to_fit "cstring *cs" 118 Reduce string's capacity to its size. 119 .It void Fn cstring_clear "cstring *cs" 120 Erase the whole string. 121 .It size_t Fn cstring_find "const cstring *cs" "const char *s" 122 Find first occurence of a pattern in string. 123 .It size_t Fn cstring_rfind "const cstring *cs" "const char *s" 124 Find last occurence of a pattern in string. 125 .It size_t Fn cstring_find_first_of "const cstring *cs" "const char *s" 126 Find first occurence of specified characters in string. 127 .It size_t Fn cstring_find_first_not_of "const cstring *cs" "const char *s" 128 Find the first character that does not match any of the specified characters. 129 .It size_t Fn cstring_find_last_of "const cstring *cs" "const char *s" 130 Find last occurence of specified characters in string. 131 .It size_t Fn cstring_find_last_not_of "const cstring *cs" "const char *s" 132 Find the last character that does not match any of the specified characters. 133 .It char Fn cstring_front "const cstring *cs" 134 Returns the first character of the string. 135 .It char Fn cstring_back "const cstring *cs" 136 Returns the last character of the string. 137 .It int Fn cstring_empty "const cstring *cs" 138 Check to see if the string is empty. 139 .It int Fn cstring_starts_with_str "const cstring *cs" "const char *s" 140 Check to see if string begins with 141 .Ar s 142 .It int Fn cstring_ends_with_str "const cstring *cs" "const char *s" 143 Check to see if string ends with 144 .Ar s 145 .It int Fn cstring_starts_with_char "const cstring *cs" "char c" 146 Check to see if string starts with 147 .Ar c 148 .It int Fn cstring_ends_with_char "const cstring *cs" "char c" 149 Check to see if string ends with 150 .Ar c 151 .It void Fn *cstring_data "const cstring *cs" 152 Get string's content in raw bytes. 153 .It char Fn *cstring_copy "const char *s" 154 Make a copy of a given 155 .Ar const\ char\ * 156 .It void Fn cstring_resize "cstring *cs" "size_t newcapacity" 157 Resize the 158 .Ar str 159 array inside a given 160 .Ar cstring 161 struct. 162 .It cstring Fn *cstring_getline "FILE *fd" "cstring *cs" "char delim" 163 Read a line from a 164 .Ar FILE 165 stream. 166 Similar behavior to 167 .Ar stdio's\ getline 168 .It int Fn cstring_equal "const cstring *lhs" "const cstring *rhs" 169 Check if lhs == rhs 170 .It int Fn cstring_greater "const cstring *lhs" "const cstring *rhs" 171 Check if lhs > rhs 172 .It int Fn cstring_greater_or_equal "const cstring *lhs" "const cstring *rhs" 173 Check if lhs >= rhs 174 .It int Fn cstring_less "const cstring *lhs" "const cstring *rhs" 175 Check if lhs < rhs 176 .It int Fn cstring_less_or_equal "const cstring *lhs" "const cstring *rhs" 177 Check if lhs <= rhs 178 .El 179 .Sh MACROS 180 .Bl -tag -width Ds 181 .It Fn CSTRING_OUT_OF_BOUNDS "len" "pos" 182 Check if 183 .Ar pos 184 is out of bounds (pos > len). 185 .It Fn CSTRING_ARR_LEN "x" 186 Determine an array's length. 187 The macro must be called in the same function the array is declared. 188 .It Fn CSTRING_MALLOC "ptr" "size" 189 Allocate memory with error cheking. 190 .El 191 .Sh CONSTANTS 192 .Bl -tag -width Ds 193 .It CSTRING_NPOS 194 This constant signifies that a pattern hasn't been found inside 195 the string. 196 Its value is -1. 197 .It CSTRING_INIT_EMPTY 198 Used with 199 .Fn cstring_create 200 in case the string is to be initliazed as empty. 201 .El 202 .Sh AUTHORS 203 .An Christos Margiolis Aq Mt christos@margiolis.net