|
lib<fancy_string> 0.1.1
A C library for easy and fun string manipulation
|
#include <string.h>#include <stdlib.h>#include <stdio.h>#include <stdbool.h>#include <stdint.h>#include <stddef.h>#include <sys/types.h>Go to the source code of this file.
Data Structures | |
| struct | fancy_string_regex_match_info_s |
Enumerations | |
| enum | fancy_string_memory_usage_mode_e { FANCY_STRING_MEMORY_USAGE_MODE_NONE , FANCY_STRING_MEMORY_USAGE_MODE_THREAD_LOCAL , FANCY_STRING_MEMORY_USAGE_MODE_GLOBAL_SYNC } |
| struct fancy_string_regex_match_info_s |
A type (i.e., a structure), returned by the fancy_string_regex_match_info_for_index() method, containing information about a particular match.
| Data Fields | ||
|---|---|---|
| size_t | end |
The 'end' position of the match at position index .
|
| ssize_t | index |
The index (i.e., the position) of the match inside the fancy_string_regex_t instance.
|
| size_t | start |
The 'start' position of the match at position index . |
| typedef struct fancy_string_array_s fancy_string_array_t |
An opaque type that serves as a container for a list of fancy_string_t instances and which is passed to the library's "array" methods for state interrogation and manipulation.
| typedef bool(* fancy_string_filter_t) (fancy_string_t const *const string, size_t index, fancy_string_array_t const *const array, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to the fancy_string_array_filter and fancy_string_array_filtered methods.
| string | A pointer to the fancy_string_t instance that is subject to being filtered, which instance is found at position index in array . |
| index | The position (i.e., index) of string in array . |
| array | A pointer to the fancy_string_array_t instance inside of which string exists. |
| context | An application-defined context object. |
true if string has been retained, or set to false if string has been filtered out. | typedef bool(* fancy_string_find_t) (fancy_string_t const *const string, size_t index, fancy_string_array_t const *const array, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to methods such as fancy_string_array_find_index and fancy_string_array_find .
| string | A pointer to the fancy_string_t instance found at position index in array . |
| index | The position of string in array . |
| array | A pointer to the fancy_string_array_t instance inside which string exists. |
| context | An application-defined context object. |
true or false) the string object string at position index in the array object array was retained by the implementor of this interface. | typedef void(* fancy_string_for_each_t) (fancy_string_t *const string, size_t index, fancy_string_array_t const *const array, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to the fancy_string_array_for_each() method.
| string | A pointer to the fancy_string_t instance on which to operate, which is found at position index in the array object array . |
| index | The position (i.e., index) of string in array . |
| array | A pointer to the fancy_string_array_t instance inside of which string exists. |
| context | An application-defined context object. |
| typedef fancy_string_t *(* fancy_string_mapped_t) (fancy_string_t const *const string, size_t index, fancy_string_array_t const *const array, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to the fancy_string_array_mapped() method.
| string | A pointer to the fancy_string_t instance found at position index in the array object array . |
| index | The position of string in array . |
| array | A pointer to the fancy_string_array_t instance inside which string exists. |
| context | An application-defined context object. |
An enumeration whose members can be used to specify, through the fancy_string_memory_usage_init() static method, the memory usage tracking mode to be used by the library. By default, FANCY_STRING_MEMORY_USAGE_MODE_NONE is used, such that memory tracking is not enabled.
| typedef struct fancy_string_regex_match_info_s fancy_string_regex_match_info_t |
A type (i.e., a structure), returned by the fancy_string_regex_match_info_for_index() method, containing information about a particular match.
| typedef struct fancy_string_regex_s fancy_string_regex_t |
An opaque type that serves as a container for regular expression matching results, and which is passed to the library's "regex" methods for state interrogation and manipulation.
| typedef void(* fancy_string_regex_updater_t) (fancy_string_t *const match, size_t start, size_t end, fancy_string_t const *const string, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to the fancy_string_regex_to_string_with_updated_matches() method.
| match | A pointer to the fancy_string_t instance on which to operate, which corresponds to the matched string at position start to end (where end is 1 position more than the last character of the match) inside the regular expression object's string object. |
| start | The start position of the match in the regular expression object's string object. |
| end | The end position of the match in the regular expression object's string object. Note that this value is "one" position more than the last character of the match. |
| context | A pointer to the application-defined context object. |
| typedef bool(* fancy_string_sort_t) (fancy_string_t const *const string_1, fancy_string_t const *const string_2, void *context) |
The signature a callback function needs to implement to be allowed to be passed as argument to the fancy_string_array_sort and the fancy_string_array_sorted methods.
| string_1 | A pointer to a fancy_string_t instance to be compared to string_2 . |
| string_2 | A pointer to a fancy_string_t instance to be compared to string_1 . |
| context | An application-defined context object. |
false if string_1 was determined to be lesser than or equal to string_2 , else, it is set to true. | typedef struct fancy_string_s fancy_string_t |
An opaque type that serves as a container for the string data and which is passed to the library's "string" methods for state interrogation and manipulation.
An enumeration whose members can be used to specify, through the fancy_string_memory_usage_init() static method, the memory usage tracking mode to be used by the library. By default, FANCY_STRING_MEMORY_USAGE_MODE_NONE is used, such that memory tracking is not enabled.
| Enumerator | |
|---|---|
| FANCY_STRING_MEMORY_USAGE_MODE_NONE | Disables the library's memory usage tracking feature. This is the default behaviour. |
| FANCY_STRING_MEMORY_USAGE_MODE_THREAD_LOCAL | Tracks memory usage and stores the tracking data in a private static variable for each thread using the library.
|
| FANCY_STRING_MEMORY_USAGE_MODE_GLOBAL_SYNC | Tracks memory usage and stores the tracking data in a private static variable shared by all threads. Internally, synchronization is achieved using pthread_mutex_t.
|
| void fancy_string_append | ( | fancy_string_t *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Appends a string object's data (in this case string ) to the current string object's internal state (i.e., to self ).
| self | A pointer to the fancy_string_t instance to which to append. |
| string | A pointer to another fancy_string_t instance whose internal data is to be copied and appended to self 's internal data. |
| void fancy_string_append_value | ( | fancy_string_t *const | self, |
| char const *const | value | ||
| ) |
Appends a (string) value to the current string object's internal state.
| self | A pointer to the fancy_string_t instance to which to append a copy of value . |
| value | The value (i.e., a pointer to a null-terminated string) to be appended to the internal string data. |
| void fancy_string_array_append | ( | fancy_string_array_t *const | self, |
| fancy_string_array_t const *const | array | ||
| ) |
Appends the elements of another array object (i.e., array ) into the current array object (i.e., self ).
| self | A pointer to the fancy_string_array_t instance to which to append copies of the array 's elements. |
| array | A pointer to another fancy_string_array_t instance whose fancy_string_t elements are to be copied and appended to self . |
| void fancy_string_array_append_and_destroy | ( | fancy_string_array_t *const | self, |
| fancy_string_array_t * | array | ||
| ) |
Appends the elements of another array object (i.e., array) into the current array object (i.e., self), and then internally calls fancy_string_array_destroy() on array.
| self | A pointer to the fancy_string_array_t instance to which to append a copy of array 's elements. |
| array | A pointer to another fancy_string_array_t instance whose fancy_string_t elements are to be copied and appended to self, and which is to subsequently be destroyed. |
_and_destroy. | void fancy_string_array_clear | ( | fancy_string_array_t *const | self | ) |
Clears (i.e, empties) the array; i.e., destroys all of the internal fancy_string_t instances and frees the internal memory that was allocated to track those instances.
| self | A pointer to the fancy_string_array_t instance to be cleared. |
| fancy_string_array_t * fancy_string_array_clone | ( | fancy_string_array_t const *const | self | ) |
Clones an array object.
| self | A pointer to the fancy_string_array_t instance to be cloned. |
self . | fancy_string_array_t * fancy_string_array_create | ( | void | ) |
Instantiates an empty array object (i.e, a list whose components are string objects).
| fancy_string_array_t * fancy_string_array_create_with_values | ( | char const *const | first_value, |
| ... | |||
| ) |
Instantiates an array object with a variable list of string values (i.e., pointers to a null-terminated strings).
| first_value | A pointer to the first string value (i.e., a null-terminated string) argument to be used to instantiate a memory-independent string object to be added first to the array. |
| ... | A variable number of null-terminated string pointers (i.e., char *) to be used, in the order they appear, in the same way as first_value . Important: The last value should be the NULL pointer, unless first_value itself is NULL , in which case all other arguments will be ignored and an empty array will be returned. |
| void fancy_string_array_destroy | ( | fancy_string_array_t *const | self | ) |
Destroys the array object; i.e., frees the memory that was allocated for the internal pointers to fancy_string_t instances and destroys those string instances using fancy_string_destroy().
| self | A reference to the fancy_string_array_t instance to be destroyed. |
| bool fancy_string_array_every | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Checks whether fn returns true for all of the elements in the array object's internal list.
| self | A pointer to the fancy_string_array_t instance to be checked. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally) until a non-match (i.e., false value) is returned, in which case the method will return false, else the function will return true, which will mean that all elements are matching. |
| context | An application-defined context object that gets passed to fn on each call. |
true or false) fn returned true for all of the elements in the array object's internal list. | void fancy_string_array_filter | ( | fancy_string_array_t *const | self, |
| fancy_string_filter_t | fn, | ||
| void * | context | ||
| ) |
Filters (therefore likely mutates) the array object's internal list's elements based on the rules established by the fn callback.
| self | A pointer to the fancy_string_array_t instance whose elements are to be filtered. |
| fn | A pointer to the filtering function to be used. |
| context | An application-defined context object. |
| fancy_string_array_t * fancy_string_array_filtered | ( | fancy_string_array_t const *const | self, |
| fancy_string_filter_t | fn, | ||
| void * | context | ||
| ) |
Clones the array object (i.e., self ) and performs filtering on that clone, based on the rules established by the fn callback.
| self | A pointer to the fancy_string_array_t instance to be cloned and whose clone's elements to be filtered. |
| fn | A pointer to the filtering function to be used. |
| context | An application-defined context object. |
fn ) can be defined. | fancy_string_t * fancy_string_array_find | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Finds the first element in the array object's internal list for which fn returns true and returns a memory-independent copy of that element.
| self | A pointer to the fancy_string_array_t instance inside of which to look for a matching element. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally) until the first match (i.e., true value) is returned. |
| context | An application-defined context object that gets passed to fn on each call. |
self for which fn returned true. The NULL pointer is returned if all fn calls returned false, which indicates that not a single match was found. | ssize_t fancy_string_array_find_index | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Finds the first element in the array object's internal list for which fn returns true and returns that element's position.
| self | A pointer to the fancy_string_array_t instance inside of which to look for a matching element. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally) until the first match (i.e., true value) is returned. |
| context | An application-defined context object that gets passed to fn on each call. |
self for which fn returned true. The value -1 is returned if all fn calls returned false, which indicates that not a single match was found. | fancy_string_t * fancy_string_array_find_last | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Finds the last element in the array object's internal list for which fn returns true and returns a memory-independent copy of that element.
| self | A pointer to the fancy_string_array_t instance inside of which to look for a matching element. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally; starting from the last element to the first) until a match (i.e., true value) is returned. |
| context | An application-defined context object that gets passed to fn on each call. |
self for which fn returned true. The NULL pointer is returned if all fn calls returned false, which indicates that not a single match was found. | ssize_t fancy_string_array_find_last_index | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Finds the last element in the array object's internal list for which fn returns true and returns that element's position.
| self | A pointer to the fancy_string_array_t instance inside of which to look for the last matching element. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally; starting from the last element to the first) until a match (i.e., true value) is returned. |
| context | An application-defined context object that gets passed to fn on each call. |
self for which fn returned true. The value -1 is returned if all fn calls returned false, which indicates that not a single match was found. | fancy_string_t * fancy_string_array_first | ( | fancy_string_array_t const *const | self | ) |
Returns a memory-independent copy of the array object's internal list's first string object.
| self | A pointer to the fancy_string_array_t instance for which the first element of the internal list is to be copied and returned. |
| char * fancy_string_array_first_value | ( | fancy_string_array_t const *const | self | ) |
Returns a memory-independent copy of the array object's internal list's first string object's internal string value (i.e., a pointer to a null-terminated string).
| self | A pointer to the fancy_string_array_t instance for which the first element of the internal list is to have its internal string value copied and returned as a pointer. |
| void fancy_string_array_for_each | ( | fancy_string_array_t *const | self, |
| fancy_string_for_each_t | fn, | ||
| void * | context | ||
| ) |
Iterates over the array object's elements and calls the fn callback with each element (i.e., fancy_string_t instance), along with its position and a reference to its parent array object.
| self | A pointer to the fancy_string_array_t instance whose internal list's elements are to be iterated over with the specified callback fn. |
| fn | A pointer to the function to be called for each element in the array. |
| context | An application-defined context object that will be passed to fn , along with each individual fancy_string_t instance contained in the array object's internal list. |
| fancy_string_t * fancy_string_array_get | ( | fancy_string_array_t const *const | self, |
| size_t | index | ||
| ) |
Returns a memory-independent copy of the fancy_string_t instance located at position index inside the array object.
| self | A pointer to the fancy_string_array_t instance whose index -th element is to be cloned and returned. |
| index | The position (in the array object's internal list) of the sought element (i.e., fancy_string_t instance). |
index . If index is out of bounds, then the NULL pointer is returned. | char * fancy_string_array_get_value | ( | fancy_string_array_t const *const | self, |
| size_t | index | ||
| ) |
Returns a memory-independent copy of the fancy_string_t instance's internal state (i.e., string data) located at position index inside the array object.
| self | A pointer to the fancy_string_array_t instance whose index -th element is to have its internal state cloned and returned. |
| index | The position (in the array object's internal list) of the sought element (i.e., fancy_string_t instance's value). |
index . If index is out of bounds, then the NULL pointer is returned. | bool fancy_string_array_includes | ( | fancy_string_array_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Checks whether a string object's internal value is contained inside the array object's internal list.
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of at least one matching element. |
| string | A pointer to the fancy_string_t instance for whose internal value to search. |
true or false) at least one match was found. | bool fancy_string_array_includes_value | ( | fancy_string_array_t const *const | self, |
| char const *const | value | ||
| ) |
Checks whether the value value is contained inside the array object's internal list.
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of at least one matching element. |
| value | A pointer to a null-terminated string value for which to search. |
true or false) at least one match was found. | ssize_t fancy_string_array_index_of | ( | fancy_string_array_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Finds the index of the first element in the array object's internal list whose internal value is equal to string 's internal value.
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of an element (the first one) whose internal value matches string 's internal value. |
| string | A pointer to the fancy_string_t instance whose internal value is to be looked for in self 's internal list. |
self . The value -1 is returned if no matching element is found. | ssize_t fancy_string_array_index_of_value | ( | fancy_string_array_t const *const | self, |
| char const *const | value | ||
| ) |
Finds the index of the first element in the array object's internal list whose internal value is equal to value .
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of an element (the first one) whose internal value matches value . |
| value | A pointer to a null-terminated string value for which to search in self 's internal list. |
self . The value -1 is returned if no matching element is found. | void fancy_string_array_insert | ( | fancy_string_array_t *const | self, |
| fancy_string_t const *const | string, | ||
| size_t | index | ||
| ) |
Inserts a memory-independent copy of the string object string at the specified position index inside the array object's internal list.
| self | A pointer to the fancy_string_array_t instance into which to insert the string object. |
| string | A pointer to the fancy_string_t instance to be cloned and inserted into the array object's internal list. |
| index | The position at which to insert the string object into the array object's internal list. |
index is out of bounds, the array will be padded with empty string objects up to one less than index , and the string object will be added at index as requested. If an element is present at position index , that element, along with all of the elements to the right of it, will be moved right by one position. @ see fancy_string_array_insert_value | void fancy_string_array_insert_value | ( | fancy_string_array_t *const | self, |
| char const *const | value, | ||
| size_t | index | ||
| ) |
Instantiates a fancy_string_t object, with its internal state set as value , and inserts it at the specified position index inside the array object's internal list.
| self | A pointer to the fancy_string_array_t instance into which to insert the new string object. |
| value | A pointer to a null-terminated string, which corresponds to the internal state of the string object to be created and inserted into the array object's internal list. |
| index | The position at which to insert the new string object into the array object's internal list. |
index is out of bounds, the array will be padded with empty string objects up to one less than index , and the string object will be added at index as requested. If an element is present at position index , that element, along with all of the elements to the right of it, will be moved right by one position. @ see fancy_string_array_insert | bool fancy_string_array_is_empty | ( | fancy_string_array_t const *const | self | ) |
Checks whether the array is empty.
| self | A pointer to the fancy_string_array_t instance to be checked for "emptiness". |
true if the array is empty (else it is set to false). | fancy_string_t * fancy_string_array_join | ( | fancy_string_array_t const *const | self, |
| fancy_string_t const *const | separator | ||
| ) |
Creates (and returns a pointer to) a fancy_string_t instance and populates it with copies of the array object's elements' string data, from first to last, using the separator argument as separator.
| self | A pointer to the fancy_string_array_t instance to be "joined" into a string object. |
| separator | A pointer to a fancy_string_t instance whose internal string value is to be used as separator while joining. |
| fancy_string_t * fancy_string_array_join_by_value | ( | fancy_string_array_t const *const | self, |
| char const *const | separator | ||
| ) |
Creates (and returns a pointer to) a fancy_string_t instance and populates it with copies of the array object's elements' string data, from first to last, using the separator argument as separator.
| self | A pointer to the fancy_string_array_t instance to be "joined" into a string object. |
| separator | A pointer to a null-terminated string to be used as separator while joining. |
| fancy_string_t * fancy_string_array_last | ( | fancy_string_array_t const *const | self | ) |
Returns a memory-independent copy of the array object's internal list's last string object.
| self | A pointer to the fancy_string_array_t instance for which the last element of the internal list is to be copied and returned. |
| ssize_t fancy_string_array_last_index_of | ( | fancy_string_array_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Finds the index of the last element in the array object's internal list whose internal value is equal to string 's internal value.
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of an element (the last one) whose internal value matches string 's internal value. |
| string | A pointer to the fancy_string_t instance whose internal value is to be sought in self 's internal list. |
self . The value -1 is returned if no matching element is found. | ssize_t fancy_string_array_last_index_of_value | ( | fancy_string_array_t const *const | self, |
| char const *const | value | ||
| ) |
Finds the index of the last element in the array object's internal list whose internal value is equal to value .
| self | A pointer to the fancy_string_array_t instance to be searched for the presence of an element (the last one) whose internal value matches value . |
| value | A pointer to a null-terminated string value for which to search in self 's internal list. |
self . The value -1 is returned if no matching element is found. | char * fancy_string_array_last_value | ( | fancy_string_array_t const *const | self | ) |
Returns a memory-independent copy of the array object's internal list's last string object's internal string value (i.e., a pointer to a null-terminated string).
| self | A pointer to the fancy_string_array_t instance for which the last element of the internal list is to have its internal string value copied and returned as a pointer. |
| fancy_string_array_t * fancy_string_array_mapped | ( | fancy_string_array_t const *const | self, |
| fancy_string_mapped_t | fn, | ||
| void * | context | ||
| ) |
Iterates over the array object's elements and calls the fn callback with each element (i.e, fancy_string_t instance), along with its position and a reference to its parent array object.
| self | A pointer to the fancy_string_array_t instance whose internal list's elements are to be iterated over with the specified callback. |
| fn | A pointer to the function to be called for each element in the array. A call to this function will return a fancy_string_t instance that should be memory-independent of the one that was passed in. |
| context | An application-defined context object. |
-Wall and -Werror flags, however, should prevent that from happening. | bool fancy_string_array_none | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Checks whether there are no elements in the array object's internal list for which fn returns true.
| self | A pointer to the fancy_string_array_t instance in which to check for the absence of matching elements. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally) until a match (i.e., true value) is returned. Note that, in this context, a match means that this method will return false. |
| context | An application-defined context object that gets passed to fn on each call. |
true or false) no string objects were found in self for which fn returned true. | fancy_string_t * fancy_string_array_pop | ( | fancy_string_array_t *const | self | ) |
Removes the last element from the array object's internal list and returns a pointer to it.
| self | A pointer to the fancy_string_array_t instance whose internal list's last element is to be removed. |
| void fancy_string_array_pop_and_destroy | ( | fancy_string_array_t *const | self | ) |
Removes and destroys the array object's internal list's last element.
| self | A pointer to the fancy_string_array_t instance whose internal list's last element is to be removed and destroyed. |
| void fancy_string_array_print | ( | fancy_string_array_t const *const | self, |
| FILE * | stream, | ||
| bool | debug | ||
| ) |
Prints (i.e., writes) the array's string contents to the specified stream .
| self | A pointer to the fancy_string_array_t instance to be printed. |
| stream | The stream to which to write (e.g., stdout ). |
| debug | Whether to use the debug format (true) or not (false). With the debug format, additional information about the object and size is printed, while the standard format simply writes the internal string objects data as is. |
| void fancy_string_array_push | ( | fancy_string_array_t *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Appends a memory-independent copy of the string object string at the end of the array object's internal list.
| self | A pointer to the fancy_string_array_t instance to which to append a copy of string . |
| string | A pointer to the fancy_string_t instance which is to be copied and that copy appended to the array object's internal list. |
| void fancy_string_array_push_value | ( | fancy_string_array_t *const | self, |
| char const *const | value | ||
| ) |
Instantiates a string object, with internal state set to value , and appends it at the end of the array object's internal list.
| self | A pointer to the fancy_string_array_t instance onto which to push the new string object. |
| value | The value (i.e., a pointer to a null-terminated string) with which to populate the new fancy_string_t instance. |
| void fancy_string_array_push_values | ( | fancy_string_array_t *const | self, |
| char const *const | first_value, | ||
| ... | |||
| ) |
Instantiates a variable number of string objects with internal states set to first_value and ... , and appends those in order at the end of the array object's internal list.
| self | A pointer to the fancy_string_array_t instance at the end of which to insert the new string objects. |
| first_value | The value (i.e., a pointer to a null-terminated string) with which to populate the first new fancy_string_t instance. |
| ... | A variable number of null-terminated string pointers (i.e., char *) to be used, in the order they appear, in the same way as first_value . Important: The last value should be the NULL pointer, unless first_value itself is NULL, in which case all other arguments will be ignored and an the array object won't be modified. |
| fancy_string_t * fancy_string_array_remove | ( | fancy_string_array_t *const | self, |
| size_t | index | ||
| ) |
Removes and returns the pointer to the fancy_string_t instance located at position index inside the array object.
| self | A pointer to the fancy_string_array_t instance whose index -th element is to be removed and returned. |
| index | The position (in the array object's internal list) of the sought element (i.e., the fancy_string_t instance to be removed). |
| void fancy_string_array_remove_and_destroy | ( | fancy_string_array_t *const | self, |
| size_t | index | ||
| ) |
Removes and destroys the fancy_string_t instance located at position index inside the array object.
| self | A pointer to the fancy_string_array_t instance whose index -th element is to be removed and destroyed. |
| index | The position (in the array object's internal list) of the element sought for removal and destruction. |
index is out of bounds, nothing will happen. | void fancy_string_array_reverse | ( | fancy_string_array_t *const | self | ) |
Reverses the order of the elements in the array object's internal list.
| self | A pointer to the fancy_string_array_t instance whose internal list's elements order is to be reversed. |
| fancy_string_array_t * fancy_string_array_reversed | ( | fancy_string_array_t const *const | self | ) |
Clones the array object and reverses the clone's element before returning it.
| self | A pointer to the fancy_string_array_t instance which is to be cloned and whose clone is to have its internal list's elements order reversed. |
| fancy_string_t * fancy_string_array_shift | ( | fancy_string_array_t *const | self | ) |
Removes the first element from the array object's internal list and returns a pointer to it.
| self | A pointer to the fancy_string_array_t instance whose internal list's first element is to be removed. |
| void fancy_string_array_shift_and_destroy | ( | fancy_string_array_t *const | self | ) |
Removes and destroys the array object's internal list's first element.
| self | A pointer to the fancy_string_array_t instance whose internal list's first element is to be removed and destroyed. |
| size_t fancy_string_array_size | ( | fancy_string_array_t const *const | self | ) |
Returns the array object's size; i.e., the number of fancy_string_t instances it contains.
| self | A pointer to the fancy_string_array_t instance for which the size is to be returned. |
| void fancy_string_array_slice_and_destroy | ( | fancy_string_array_t *const | self, |
| ssize_t | start, | ||
| ssize_t | end | ||
| ) |
Slices the array object self based on the start and end positions, preserving the elements in that range, while destroying the elements falling outside of it.
| self | A pointer to the fancy_string_array_t instance to be sliced. |
| start | The position at which the slice starts. If set to -1, will be interpreted as 0. |
| end | The position before which the slice ends. If set to -1, will be interpreted as the array object's size (i.e., the total number of elements contained in the array object's internal list). |
start and end . Setting start to -1 will be interpreted as 0, while setting end to -1 will be interpreted as n (where n is the number of elements in the array object's internal list). Setting start such that it is greater than end will simply result in those two values being swapped with one another. If start is out of bounds, the array object will simply get cleared up (i.e., emptied). If end is out of bounds, the slice will retain every element starting at position start . | fancy_string_array_t * fancy_string_array_sliced | ( | fancy_string_array_t const *const | self, |
| ssize_t | start, | ||
| ssize_t | end | ||
| ) |
Creates a memory-independent slice of the array object.
| self | A pointer to the fancy_string_array_t instance for which to generate a slice. |
| start | The position at which the slice starts. If set to -1, will be interpreted as 0. |
| end | The position before which the slice ends. If set to -1, will be interpreted as the array object's size (i.e., the total number of elements contained in the array object's internal list). |
start and end . Setting start to -1 will be interpreted as 0, while setting end to -1 will be interpreted as n (where n is the number of elements in the array object's internal list). Setting start such that it is greater than end will simply result in those two values being swapped with one another. If start is out of bounds, an empty array object will be returned. If self is empty, an empty slice will be returned, regardless of the values of start and end . If end is out of bounds, the slice will contain a copy of every element starting at position start . | bool fancy_string_array_some | ( | fancy_string_array_t const *const | self, |
| fancy_string_find_t | fn, | ||
| void * | context | ||
| ) |
Checks whether there is at least one element in the array object's internal list for which fn returns true.
| self | A pointer to the fancy_string_array_t instance in which to check for the presence of at least one matching element. |
| fn | A pointer to a function conforming to the fancy_string_find_t interface, which function gets called (internally) until a match (i.e., true value) is returned. |
| context | An application-defined context object that gets passed to fn on each call. |
true or false) at least one string object was found in self for which fn returned true. | void fancy_string_array_sort | ( | fancy_string_array_t *const | self, |
| fancy_string_sort_t | fn, | ||
| void * | context | ||
| ) |
Sorts the array object's internal list's elements based on the rules established by the fn callback.
| self | A pointer to the fancy_string_array_t instance to be sorted. |
| fn | A pointer to the sorting function to be used. |
| context | An application-defined context object that gets passed to fn on each call. |
| void fancy_string_array_sort_values | ( | fancy_string_array_t *const | self | ) |
Sorts the array object's internal list's elements based on their internal values, in the most basic way possible; i.e., from the smallest to greatest, as one would expect, using individual bytes as a basis for comparison.
| self | A pointer to the fancy_string_array_t instance to be sorted. |
| fancy_string_array_t * fancy_string_array_sorted | ( | fancy_string_array_t const *const | self, |
| fancy_string_sort_t | fn, | ||
| void * | context | ||
| ) |
Creates a sorted copy of self .
| self | A pointer to the fancy_string_array_t instance to be cloned and then sorted. |
| fn | A pointer to the sorting function to be used. |
| context | An application-defined context object that gets passed to fn on each call. |
self . fn ). | fancy_string_array_t * fancy_string_array_sorted_values | ( | fancy_string_array_t const *const | self | ) |
Clones the array object and then sorts the clone's internal list's elements based on their internal values, in the most basic way possible; i.e., from the smallest to greatest, as one would expect, using individual bytes as a basis for comparison.
| self | A pointer to the fancy_string_array_t instance to be cloned and whose clone to be sorted. |
| fancy_string_array_t * fancy_string_array_splice | ( | fancy_string_array_t *const | self, |
| size_t | index, | ||
| ssize_t | delete_count, | ||
| fancy_string_array_t const *const | optional_new_strings | ||
| ) |
Splices the array object's internal list and returns the removed elements (if any) in a new array object.
| self | The array object to be spliced. |
| index | The position at which to splice. |
| delete_count | The number of items to be removed (and returned) from the array object's internal element list. If set to 0, no elements will be removed. If set to -1, everything starting at position index , up to the end, will be removed (and returned). |
| optional_new_strings | A pointer to an optional fancy_string_array_t instance containing elements to be inserted (in their respective order) at position index . This argument should be set to the NULL pointer if no elements need to be inserted. |
optional_new_strings is non-NULL and non-empty and the insertion position index is out of bounds, self will be padded with empty string objects up to one less than index , and the additional string objects will be added starting at position index as requested. If elements are present starting at position index , those elements, assuming that delete_count is set to 0, will be moved right by as many positions as there are elements in the optional_new_strings array object. | void fancy_string_array_splice_and_destroy | ( | fancy_string_array_t *const | self, |
| size_t | index, | ||
| ssize_t | delete_count, | ||
| fancy_string_array_t const *const | optional_new_strings | ||
| ) |
Splices the array object's internal list and destroys the removed elements (if any).
| self | The array object to be spliced. |
| index | The position at which to splice. |
| delete_count | The number of items to be removed (and destroyed) from the array object's internal element list. If set to 0, no elements will be removed. If set to -1, everything starting at position index , up to the end, will be removed (and destroyed). |
| optional_new_strings | A pointer to an optional fancy_string_array_t instance containing elements to be inserted (in their respective order) at position index . This argument should be set to the NULL pointer if no elements need to be inserted. |
optional_new_strings is non-NULL and non-empty and the insertion position index is out of bounds, self will be padded with empty string objects up to one less than index , and the additional string objects will be added starting at position index as requested. If elements are present starting at position index , those elements, assuming that delete_count is set to 0, will be moved right by as many positions as there are elements in the optional_new_strings array object. See the documentation for fancy_string_array_splice for an example on splicing. | fancy_string_array_t * fancy_string_array_spliced | ( | fancy_string_array_t const *const | self, |
| size_t | index, | ||
| ssize_t | delete_count, | ||
| fancy_string_array_t const *const | optional_new_strings | ||
| ) |
Clones self and calls fancy_string_array_splice_and_destroy on that clone.
| self | The array object to be cloned and whose clone is to be spliced. |
| index | The position at which to splice. |
| delete_count | The number of items to be removed (and destroyed) from the clone. If set to 0, no elements will be removed. If set to -1, everything starting at position index , up to the end, will be removed (and destroyed). |
| optional_new_strings | A pointer to an optional fancy_string_array_t instance containing elements to be inserted (in their respective order) at position index . This argument should be set to the NULL pointer if no elements need to be inserted. |
optional_new_strings is non-NULL and non-empty and the insertion position index is out of bounds, the clone of self will be padded with empty string objects up to one less than index , and the additional string objects will be added starting at position index as requested. If elements are present starting at position index , those elements, assuming that delete_count is set to 0, will be moved right by as many positions as there are elements in the optional_new_strings array object. See the documentation for fancy_string_array_splice for an example on splicing. | void fancy_string_clear | ( | fancy_string_t *const | self | ) |
Clears the internal string data (i.e., makes self an empty string object).
| self | A pointer to the fancy_string_t instance to be cleared (i.e., emptied). |
| fancy_string_t * fancy_string_clone | ( | fancy_string_t const *const | self | ) |
Creates a memory-independent copy of the fancy_string_t instance (i.e., self ).
| self | A pointer to the fancy_string_t instance to be cloned. |
self . | bool fancy_string_contains | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Checks whether the string object's data contains at least one occurrence of string 's internal value.
| self | A pointer to the fancy_string_t instance to be checked. |
| string | A pointer to another fancy_string_t instance whose internal value is searched inside self 's value. |
true) or not (false). | bool fancy_string_contains_value | ( | fancy_string_t const *const | self, |
| char const *const | value | ||
| ) |
Checks whether the string object's data contains at least one occurrence of value .
| self | A pointer to the fancy_string_t instance to be checked. |
| value | The value (i.e., a pointer to a null-terminated string) for which to check inside self . |
value was found (true) or not (false). | fancy_string_t * fancy_string_create | ( | char const *const | value | ) |
Instantiates a string object with its internal state specified by the value parameter.
| value | The initial state of the string object (i.e., a pointer to a null-terminated string). |
| fancy_string_t * fancy_string_create_empty | ( | void | ) |
Similarly to fancy_string_create(), instantiates a string object, but with its internal value set to be empty.
| fancy_string_t * fancy_string_create_repeat | ( | char const *const | value, |
| size_t | n_repeat | ||
| ) |
Similarly to fancy_string_create(), instantiates a string object, but repeats the initial value the specified number of times (i.e., n_repeat times).
| value | The initial state of the string object (i.e., a pointer to a null-terminated string). |
| n_repeat | The number of times to repeat the string object. |
| void fancy_string_destroy | ( | fancy_string_t *const | self | ) |
Destroys the string object; i.e., frees the memory that was allocated for the internal string data, as well as the memory allocated for the container itself.
| self | A pointer to the fancy_string_t instance to be destroyed. |
| bool fancy_string_ends_with | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Checks whether the string object's internal value ends with string 's internal value.
| self | A pointer to the fancy_string_t instance to be checked. |
| string | A Pointer to another fancy_string_t instance against whose internal value to check for "trailing equality". |
string 's internal value (true) or not (false). | bool fancy_string_ends_with_value | ( | fancy_string_t const *const | self, |
| char const *const | value | ||
| ) |
Checks whether the string object's internal value ends with value .
| self | A pointer to the fancy_string_t instance to be checked. |
| value | A value (i.e., a pointer to a null-terminated string) against which to check for "trailing equality". |
value (true) or not (false). | bool fancy_string_equals | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Checks whether the string object's internal value equals to string 's internal value.
| self | A pointer to the fancy_string_t instance for which to check for equality. |
| string | A pointer to another fancy_string_t instance against which to check for equality. |
true) or not (false). | bool fancy_string_equals_value | ( | fancy_string_t const *const | self, |
| char const *const | value | ||
| ) |
Checks whether the string object's internal value equals to value .
| self | A pointer to the fancy_string_t instance for which to check for equality. |
| value | The value (i.e., a pointer to a null-terminated string) against which to check for equality. |
true) or not (false). | fancy_string_t * fancy_string_from_copied_memory | ( | void const *const | pointer, |
| size_t | n | ||
| ) |
Instantiates a string object with initial internal state obtained by copying n bytes from pointer .
| pointer | A pointer to the memory to be copied (i.e., n bytes of it) and used as internal state for the new string object. |
| n | The number of bytes to be copied from the memory pointed to by pointer . |
sizeof(char*) * (n + 1) bytes and uses them to make a copy of pointer 's first n bytes using memcpy , and then adds the null character \0 to it, and passes that temporary null-terminated string to fancy_string_create to create the string object. Obviously, this method should only be used when a null-terminated string is not already available to be passed to fancy_string_create directly, or when only a specific segment of a string is needed. | fancy_string_t * fancy_string_from_stream | ( | FILE * | stream | ) |
Instantiates a string object and fills its internal state with the string data read from stream .
| stream | A pointer to readable stream (e.g., a file pointer that has been opened for reading). |
value has been opened for reading. stream if the latter has not been opened with read permission will crash the application. | fancy_string_t * fancy_string_from_stream_next_line | ( | FILE * | stream | ) |
Reads the next line from the stream and instantiates a string object with internal state set as the "line" that was read.
| stream | A pointer to a readable stream from which to get the next line (e.g., a file pointer that has been opened for reading). |
stream , or the NULL pointer if the passed stream argument was NULL or if getline(), which is used internally to read the next line, returned -1. stream if the latter has not been opened with read permission will crash the application. | ssize_t fancy_string_index_of | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Finds and returns the index of the first occurrence of string 's internal value in self 's internal value, if any.
| self | A pointer to the fancy_string_t instance for which to find the first matching index for string 's internal value. |
| string | A pointer to another fancy_string_t instance for whose internal value is being sought inside self 's internal data. |
-1 will be returned. | ssize_t fancy_string_index_of_value | ( | fancy_string_t const *const | self, |
| char const *const | value | ||
| ) |
Finds and returns the index of the first occurrence of value in the string object's internal value, if any.
| self | A pointer to the fancy_string_t instance for which to find the first matching index for value . |
| value | The value (i.e., a pointer to a null-terminated string) whose first occurrence is being sought inside the string object's data. |
-1 will be returned. | bool fancy_string_is_empty | ( | fancy_string_t const *const | self | ) |
Checks whether the string is empty.
| self | A pointer to the fancy_string_t instance to be checked for emptiness. |
true if the string is empty (else it is false). Populates its arguments with the library's version.
| major | A pointer used to store the library's major version number. |
| minor | A pointer used to store the library's minor version number. |
| revision | A pointer used to store the library's revision number. |
Prints (i.e., writes) the library's version to the specified stream.
| stream | The stream to which to write the library version (e.g. stdout ). |
| void fancy_string_line_break | ( | fancy_string_t *const | self, |
| bool | with_carriage_return | ||
| ) |
Appends a line break character (i.e., \\n) at the end of the object's internal string data.
| self | A pointer to the fancy_string_t instance at the end of which to add a line break character. |
| with_carriage_return | A boolean value indicating whether, in addition to the line break character \\n, a carriage return character (i.e., \\r) should also be added. If true, the two characters will be appended in the following order: \\r\\n. If false, only \\n will be appended. |
| void fancy_string_lowercase | ( | fancy_string_t *const | self | ) |
Applies a lowercase transformation to the string object's internal data.
| self | A pointer to the fancy_string_t instance whose internal data is to be lowercased. |
À will likely not be transformed to à. | fancy_string_t * fancy_string_lowercased | ( | fancy_string_t const *const | self | ) |
Creates a new string object whose internal data corresponds to a copy of self with a lowercase transformation performed on it.
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then lowercased. |
self 's internal data. À will likely not be transformed to à. A "static method" that can be used to "print" a summary of the library's memory usage.
| stream | A pointer to a valid readable stream to which the summary will be printed (i.e., written). |
A "static method" that retrieves and returns the amount of memory allocated by the library.
0. | void fancy_string_memory_usage_init | ( | fancy_string_memory_usage_mode_t | mode | ) |
If called, specifies the memory usage tracking mode to be used by the library.
| mode | A variable of type fancy_string_memory_usage_mode_t , which specifies the tracking mode to be used. |
| fancy_string_memory_usage_mode_t fancy_string_memory_usage_mode | ( | void | ) |
Retrieves and returns the current memory usage mode used by the library, for the current process.
| void fancy_string_pad_end | ( | fancy_string_t *const | self, |
| size_t | target_size, | ||
| char | value | ||
| ) |
Pads the right-hand side of the string with the specified character (i.e., value ).
| self | A pointer to the fancy_string_t instance whose internal data is to be right-padded. |
| target_size | The target size of the string after the padding. |
| value | The character to be used for the padding. |
| void fancy_string_pad_start | ( | fancy_string_t *const | self, |
| size_t | target_size, | ||
| char | value | ||
| ) |
Pads the left-hand side of the string with the specified character (i.e., value ).
| self | A pointer to the fancy_string_t instance whose internal data is to be left-padded. |
| target_size | The target size of the string after the padding. |
| value | The character to be used for the padding. |
| fancy_string_t * fancy_string_padded_end | ( | fancy_string_t const *const | self, |
| size_t | target_size, | ||
| char | value | ||
| ) |
Creates a string object whose right-hand side has been padded with the specified character (i.e., value).
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then right-padded. |
| target_size | The target size of the padded string object. |
| value | The character to be used for the padding. |
| fancy_string_t * fancy_string_padded_start | ( | fancy_string_t const *const | self, |
| size_t | target_size, | ||
| char | value | ||
| ) |
Creates a string object whose left-hand side has been padded with the specified character (i.e., value ).
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then left-padded. |
| target_size | The target size of the padded string object. |
| value | The character to be used for the padding. |
| void fancy_string_prepend | ( | fancy_string_t *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Prepends a string object's data (in this case string ) to the current string object's internal state (i.e., to self ).
| self | A pointer to the fancy_string_t instance to which to prepend. |
| string | A pointer to another fancy_string_t instance whose internal data is to be copied and prepended to self . |
| void fancy_string_prepend_value | ( | fancy_string_t *const | self, |
| char const *const | value | ||
| ) |
Prepends a (string) value to the current string object's internal state.
| self | A pointer to the fancy_string_t instance to which to prepend a copy of value . |
| value | The value (i.e., a pointer to a null-terminated string) to be prepended to the internal string data. |
| void fancy_string_print | ( | fancy_string_t const *const | self, |
| FILE * | stream, | ||
| bool | debug | ||
| ) |
Prints (i.e., writes) the string object's data to the specified stream .
| self | A pointer to the fancy_string_t instance to be printed. |
| stream | The stream to which to write (e.g., stdout ). |
| debug | Whether to use the debug format (true) or not (false). With the debug format, in addition to printing the data itself, information the container and the data size is also printed, while the standard format simply writes the string data as is. |
| fancy_string_regex_t * fancy_string_regex_create | ( | fancy_string_t const *const | string, |
| fancy_string_t const *const | pattern, | ||
| ssize_t | n_max_matches | ||
| ) |
Instantiates a regular expression object and returns a pointer to it. That object can then be interrogated using the various fancy_string_regex-prefixed methods exposed by this library.
| string | A pointer to a fancy_string_t instance containing the string data to be searched. |
| pattern | A pointer to a fancy_string_t instance containing the string data corresponding to the regular expression pattern for which to match. |
| n_max_matches | A value that can be used to specify a maximum number of matches allowed during the search. If set -1, the search will go on, from left to right, until no more matches are found. |
string or pattern is empty, this method will return the NULL pointer. The NULL pointer will also be returned if an error occurs while (internally) calling regcomp() or regexec(). string 's data is searched for pattern from left to right, until either n_max_matches is reached or no more matches are found. REG_EXTENDED flag, which means that the POSIX-Extended Regular Expressions syntax is used. Read more: POSIX Regular Expression | void fancy_string_regex_debug | ( | fancy_string_regex_t const *const | self, |
| FILE * | stream, | ||
| bool | verbose | ||
| ) |
Prints a summary of the self regular expression object to the specified stream (i.e., stream ).
| self | A pointer to the fancy_string_regex_t instance to be printed. |
| stream | A pointer to a valid "writable" stream (e.g., stdout ). |
| verbose | A boolean value indicating whether (true) or not (false) to print extra information. That extra information, if present, will be prefixed with the word "verbose" in the "printout". |
| void fancy_string_regex_destroy | ( | fancy_string_regex_t *const | self | ) |
Destroys the regular expression object.
| self | A pointer to the fancy_string_regex_t instance to be destroyed. |
| bool fancy_string_regex_has_match | ( | fancy_string_regex_t const *const | self | ) |
Checks whether there was at least one match in the regular expression object pointed to by self .
| self | A pointer to the fancy_string_regex_t instance for which to check whether at least one match was found. |
true) or not (false) at least one match was found for the current regular expression object. | size_t fancy_string_regex_match_count | ( | fancy_string_regex_t const *const | self | ) |
Returns the number of matches obtained for the regular expression object pointed to by self .
| self | A pointer to the fancy_string_regex_t instance for which to retrieve the number of matches found. |
self . | fancy_string_regex_match_info_t fancy_string_regex_match_info_for_index | ( | fancy_string_regex_t const *const | self, |
| size_t | index | ||
| ) |
Retrieves and returns the match information in a fancy_string_regex_t instance for the specified position (i.e., index ).
| self | A pointer to the fancy_string_regex_t instance for which the match info (i.e., fancy_string_regex_match_info_t) is requested. |
| index | The position (i.e., the index) of the match to be returned |
.index = -1, that means that the specified position (i.e, index ) was out of bounds, such that both .start and .end will be set to zero. If the index argument was valid, it will be returned in .index, and the .start and .end values will correspond to the location of the index -th match in the target string object (for which string object a copy can be requested using the fancy_string_regex_string method on self ). | fancy_string_array_t * fancy_string_regex_matches_to_strings | ( | fancy_string_regex_t const *const | self | ) |
Creates and returns an array object whose internal components correspond to the regular expression object's matches.
| self | A pointer to the fancy_string_regex_t instance whose matches are to be extracted and returned as an array object. |
| ssize_t fancy_string_regex_max_number_of_matches | ( | fancy_string_regex_t const *const | self | ) |
Retrieves and returns the n_max_matches value (i.e., the maximum number of matches allowed for the regular expression instance) that was used when instantiating the fancy_string_regex_t object (i.e., the object pointed to by self ).
| self | A pointer to the fancy_string_regex_t instance for which to check the specified n_max_matches. |
-1 means that there was no limit. | bool fancy_string_regex_max_number_of_matches_reached | ( | fancy_string_regex_t const *const | self | ) |
Checks, for self , whether a maximum number of matches was set and, if so, whether that number was reached.
| self | A pointer to a fancy_string_regex_t instance for which to check whether the maximum number of matches was reached (if specified). |
true) or not (false) the maximum number of matches (if specified) was reached. n_max_matches is set to -1, no limit will be set, and this will alway return false for the corresponding instance. | fancy_string_t * fancy_string_regex_pattern | ( | fancy_string_regex_t const *const | self | ) |
Retrieves and returns the regular expression object's pattern as a memory-independent string object.
| self | A pointer to a fancy_string_regex_t instance for which to retrieve the "regular expression" pattern. |
| fancy_string_t * fancy_string_regex_replaced_matches | ( | fancy_string_regex_t *const | self, |
| fancy_string_t * | new_string | ||
| ) |
Creates and returns a new string object whose internal string data is equivalent to the regular expression object's string object, except that the matches (if any) have been replaced with new_string .
| self | A pointer to a fancy_string_regex_t instance whose matches' values are replaced with new_string to create a new string object based on the original one. |
| new_string | A pointer to the fancy_string_t instance whose internal string data is to be used as replacement for that matches. |
new_string . | fancy_string_array_t * fancy_string_regex_split_at_matches | ( | fancy_string_regex_t const *const | self | ) |
Uses the matches as separators for splitting the regular expression object's string into an array object.
| self | A pointer to a fancy_string_regex_t instance whose internal string object is to be split into an array object. |
| fancy_string_t * fancy_string_regex_string | ( | fancy_string_regex_t const *const | self | ) |
Retrieves and returns the regular expression object's content string (i.e., the string to be searched for matches) as a memory-independent string object.
| self | A pointer to a fancy_string_regex_t instance for which to retrieve the "content string". |
| fancy_string_t * fancy_string_regex_string_for_match_at_index | ( | fancy_string_regex_t const *const | self, |
| size_t | index | ||
| ) |
Retrieves the index -th matched character sequence (if any), and returns it as a memory-independent string object.
| self | A pointer to the fancy_string_regex_t instance for which to retrieve a substring of the original string object for the match at position index . |
| index | The position of the match inside self , for which a substring is to be created and returned. |
index -th matched character sequence. If index is out of bounds, the NULL pointer will be returned. | fancy_string_t * fancy_string_regex_to_string_with_updated_matches | ( | fancy_string_regex_t const *const | self, |
| fancy_string_regex_updater_t | fn, | ||
| void * | context | ||
| ) |
Similar to, but more flexible than fancy_string_regex_replaced_matches(), this method can be used to generate a string object whose internal data is a copy of the regular expression object's original string, but with (potentially) modified substring values where matches were founds. The reason why this method is more flexible than fancy_string_regex_replaced_matches() is because it allows applying custom modification rules on a per-match basis (see the example).
| self | A pointer to the fancy_string_regex_t instance to be used to generate the new string object. |
| fn | A pointer to a function that conforms to the fancy_string_regex_updater_t signature, which will be called internally for each match in the regular expression object self . |
| context | A pointer to an application-defined context object, which gets passed to fn on each call. |
verbose argument is set to true, to generate the .verbose_string[calculated] debug output. | void fancy_string_replace | ( | fancy_string_t *const | self, |
| fancy_string_t const *const | old_substring, | ||
| fancy_string_t const *const | new_substring, | ||
| ssize_t | replace_n | ||
| ) |
Replaces the specified number of occurrences (i.e., replace_n ) of old_substring 's internal value with new_substring 's internal value in the string object's internal data.
| self | A pointer to the fancy_string_t instance whose internal data is to be modified. |
| old_substring | A pointer to another fancy_string_t instance containing the pattern to be found and replaced with new_substring 's value. |
| new_substring | A pointer to another fancy_string_t instance containing the value with which to replace occurrences of old_substring 's value. |
| replace_n | The maximum number of times, starting from the beginning of the string, to replace old_substring 's value. Specifying replace_n = -1 will result in all occurrences being replaced. |
| void fancy_string_replace_value | ( | fancy_string_t *const | self, |
| char const *const | old_value, | ||
| char const *const | new_value, | ||
| ssize_t | replace_n | ||
| ) |
Replaces the specified number of occurrences (i.e., replace_n ) of old_value with new_value in the string object's internal data.
| self | A pointer to the fancy_string_t instance whose internal data is to be modified. |
| old_value | A pointer to the pattern (i.e., a pointer to a null-terminated string) to be found and replaced with new_value . |
| new_value | A pointer to the value (i.e., a pointer to a null-terminated string) with which to replace occurrences of old_value . |
| replace_n | The maximum number of times, starting from the beginning of the string, to replace old_value . Specifying replace_n = -1 will result in all occurrences being replaced. |
| fancy_string_t * fancy_string_replaced | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | old_substring, | ||
| fancy_string_t const *const | new_substring, | ||
| ssize_t | replace_n | ||
| ) |
Creates a string object with the specified number of occurrences (i.e., replace_n ) of old_substring 's internal value replaced with new_substring 's internal value.
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then modified. |
| old_substring | A pointer to the pattern to be found and replaced with new_substring . |
| new_substring | A pointer to the value with which to replace occurrences of old_substring . |
| replace_n | The maximum number of times, starting from the beginning of the string, to replace old_substring . Specifying replace_n = -1 will result in all occurrences being replaced. |
replace_n 's occurrences of new_substring have been replaced with old_substring . | fancy_string_t * fancy_string_replaced_value | ( | fancy_string_t const *const | self, |
| char const *const | old_value, | ||
| char const *const | new_value, | ||
| ssize_t | replace_n | ||
| ) |
Creates a string object with the specified number of occurrences (i.e., replace_n ) of old_value replaced with new_value.
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then modified. |
| old_value | A pointer to the pattern (i.e., a pointer to a null-terminated string) to be found and replaced with new_value . |
| new_value | A pointer to the value (i.e., a pointer to a null-terminated string) with which to replace occurrences of old_value . |
| replace_n | The maximum number of times, starting from the beginning of the string, to replace old_value . Specifying replace_n = -1 will result in all occurrences being replaced. |
replace_n 's occurrences of new_value have been replaced with old_value. | size_t fancy_string_size | ( | fancy_string_t const *const | self | ) |
Returns the size of the object's internal string (conceptually the same as strlen() ).
| self | A pointer to the fancy_string_t instance for which the size is to be returned. |
| fancy_string_array_t * fancy_string_split | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | separator, | ||
| ssize_t | n_max_splits | ||
| ) |
Splits the string into an array (i.e., a list) of string objects based on the separator string object's internal value.
| self | A pointer to the fancy_string_t instance whose internal string is to be split. |
| separator | A pointer to the fancy_string_t instance whose internal data is to be used as the splitting pattern. |
| n_max_splits | The maximum number of times to split (i.e., the maximum number of matches to act upon). If this value set to -1, there will be as many splits as there are matches found. If set to 0, the method will simply return an array object with a single element containing a copy of the original string object. |
| fancy_string_array_t * fancy_string_split_by_value | ( | fancy_string_t const *const | self, |
| char const *const | separator, | ||
| ssize_t | n_max_splits | ||
| ) |
Splits the string into an array (i.e., a list) of string objects based on the separator .
| self | A pointer to the fancy_string_t instance whose internal string is to be split. |
| separator | A value (i.e., a pointer to a null-terminated string) that contains the pattern to be used for splitting. |
| n_max_splits | The maximum number of times to split (i.e., the maximum number of matches to act upon). If this value is set -1, there will be as many splits as there are matches found. If set to 0, the method will simply return an array object with a single element containing a copy of the original string object. |
| bool fancy_string_starts_with | ( | fancy_string_t const *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Checks whether the string object's internal value starts with string 's internal value.
| self | A pointer to the fancy_string_t instance to be checked. |
| string | A Pointer to another fancy_string_t instance against whose internal value to check for "leading equality". |
string 's internal value (true) or not (false). | bool fancy_string_starts_with_value | ( | fancy_string_t const *const | self, |
| char const *const | value | ||
| ) |
Checks whether the string object's internal value starts with value.
| self | A pointer to the fancy_string_t instance to be checked. |
| value | A value (i.e., a pointer to a null-terminated string) against which to check for "leading equality". |
value (true) or not (false). | fancy_string_t * fancy_string_substring | ( | fancy_string_t const *const | self, |
| ssize_t | start, | ||
| ssize_t | end | ||
| ) |
Creates a substring of a string object.
| self | A pointer to the fancy_string_t instance for which to create a substring. |
| start | The start index of the substring. If this value is set to -1, the start index will be 0. |
| end | The end index of the substring. If this value is set to -1, the end index will be n, which corresponds to self 's size. It should be noted that end is not included in the range. For instance, start = 0 and end = 5 will return of substring for the 0..4, not 0..5. |
start and end index values. For instance, if start is greater than end, the two values will be swapped with one another. Also, if end is out of bounds, the substring's upper bound will be set as n - 1. Lastly, if the specified range is completely out of bounds, an empty string object will be returned. | void fancy_string_trim | ( | fancy_string_t *const | self | ) |
Trims (i.e., remove all the white spaces from) both the right and left-hand sides of the string object's internal values.
| self | A pointer to the fancy_string_t instance to be trimmed. |
| void fancy_string_trim_left | ( | fancy_string_t *const | self | ) |
Trims (i.e., remove all the white spaces from) the left-hand side of the string object's internal value.
| self | A pointer to the fancy_string_t instance to be trimmed left. |
| void fancy_string_trim_right | ( | fancy_string_t *const | self | ) |
Trims (i.e., remove all the white spaces from) the right-hand side of the string object's internal value.
| self | A pointer to the fancy_string_t instance to be trimmed right. |
| fancy_string_t * fancy_string_trimmed | ( | fancy_string_t const *const | self | ) |
Creates a trimmed version of the string object (i.e., a version with all the leading and trailing white spaces removed).
| self | A pointer to the fancy_string_t instance for which to create a trimmed copy. |
self , except that it has been trimmed at both the right and the left. | fancy_string_t * fancy_string_trimmed_left | ( | fancy_string_t const *const | self | ) |
Creates a left-hand-trimmed version of the string object (i.e., a version with all the leading white spaces removed).
| self | A pointer to the fancy_string_t instance for which to create a left-trimmed copy. |
self , except that it has been trimmed at the left. | fancy_string_t * fancy_string_trimmed_right | ( | fancy_string_t const *const | self | ) |
Creates a right-hand-trimmed version of the string object (i.e., a version with all the trailing white spaces removed).
| self | A pointer to the fancy_string_t instance for which to create a right-trimmed copy. |
self , except that it has been trimmed at the right. | void fancy_string_update | ( | fancy_string_t *const | self, |
| fancy_string_t const *const | string | ||
| ) |
Updates the internal state of the string object using that of another string object (i.e., string ).
| self | A pointer to the fancy_string_t instance whose value needs updating. |
| string | A pointer to another fancy_string_t instance whose internal state is to be copied inside self . |
| void fancy_string_update_value | ( | fancy_string_t *const | self, |
| char const *const | value | ||
| ) |
Updates the internal state of the string object with the new string data (i.e., value ).
| self | A pointer to the fancy_string_t instance whose value needs updating. |
| value | The value (i.e., a pointer to a null-terminated string) with which to replace the string object's internal state. |
value , so if that value has been heap-allocated by the application, the application is responsible for freeing its memory when no longer needed. | void fancy_string_uppercase | ( | fancy_string_t *const | self | ) |
Applies an uppercase transformation to the string object's internal data.
| self | A pointer to the fancy_string_t instance whose internal data is to be uppercased. |
à will likely not be transformed to À. | fancy_string_t * fancy_string_uppercased | ( | fancy_string_t const *const | self | ) |
Creates a new string object whose internal data corresponds to a copy of self with an uppercase transformation performed on it.
| self | A pointer to the fancy_string_t instance whose internal data is to be copied and then uppercased. |
self 's internal data. à will likely not be transformed to À. | char * fancy_string_value | ( | fancy_string_t const *const | self | ) |
Returns a pointer to a heap-allocated copy of the string object's internal state.
| self | A pointer to the fancy_string_t instance for which a copy of the internal state is requested. |
1.9.6