cstring

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

README (4673B)


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