cstring

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

README (4715B)

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