cstring

Lightweight string library for C
git clone git://git.margiolis.net/cstring.git
Log | Files | Refs | README | LICENSE

cstring.3 (7368B)


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