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

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>
     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
     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
    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.
    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