fancy_string.h

Go to the documentation of this file.

/*
    Copyright (c) 2023 BB-301 <fw3dg3@gmail.com>
 
    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the “Software”), to deal in the Software without restriction,
    including without limitation the rights to use, copy, modify, merge,
    publish, distribute, sublicense, and/or sell copies of the Software,
    and to permit persons to whom the Software is furnished to do so,
    subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.
*/
 
#ifndef __FANCY_STRING_H__
#define __FANCY_STRING_H__
 
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include <sys/types.h>
 
// -----------------------------------------------
//                  OPAQUE TYPES
// -----------------------------------------------
 
typedef struct fancy_string_s fancy_string_t;
 
typedef struct fancy_string_array_s fancy_string_array_t;
 
typedef struct fancy_string_regex_s fancy_string_regex_t;
 
typedef struct fancy_string_regex_match_info_s
{
    ssize_t index;
    size_t start;
    size_t end;
} fancy_string_regex_match_info_t;
 
typedef 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
} fancy_string_memory_usage_mode_t;
 
// -----------------------------------------------
//                     MISC
// -----------------------------------------------
 
void fancy_string_library_version(uint16_t *major, uint16_t *minor, uint16_t *revision);
 
void fancy_string_library_version_print(FILE *stream);
 
size_t fancy_string_memory_usage_get(void);
 
void fancy_string_memory_usage_debug(FILE *stream);
 
void fancy_string_memory_usage_init(fancy_string_memory_usage_mode_t mode);
 
fancy_string_memory_usage_mode_t fancy_string_memory_usage_mode(void);
 
// -----------------------------------------------
//                 STRING (methods)
// -----------------------------------------------
 
fancy_string_t *fancy_string_create(char const *const value);
 
fancy_string_t *fancy_string_from_copied_memory(void const *const pointer, size_t n);
 
fancy_string_t *fancy_string_from_stream(FILE *stream);
 
fancy_string_t *fancy_string_from_stream_next_line(FILE *stream);
 
fancy_string_t *fancy_string_create_repeat(char const *const value, size_t n_repeat);
 
fancy_string_t *fancy_string_create_empty(void);
 
fancy_string_t *fancy_string_clone(fancy_string_t const *const self);
 
void fancy_string_destroy(fancy_string_t *const self);
 
void fancy_string_print(fancy_string_t const *const self, FILE *stream, bool debug);
 
size_t fancy_string_size(fancy_string_t const *const self);
 
bool fancy_string_is_empty(fancy_string_t const *const self);
 
void fancy_string_clear(fancy_string_t *const self);
 
void fancy_string_update_value(fancy_string_t *const self, char const *const value);
 
void fancy_string_update(fancy_string_t *const self, fancy_string_t const *const string);
 
char *fancy_string_value(fancy_string_t const *const self);
 
void fancy_string_append_value(fancy_string_t *const self, char const *const value);
 
void fancy_string_append(fancy_string_t *const self, fancy_string_t const *const string);
 
void fancy_string_prepend_value(fancy_string_t *const self, char const *const value);
 
void fancy_string_prepend(fancy_string_t *const self, fancy_string_t const *const string);
 
bool fancy_string_equals_value(fancy_string_t const *const self, char const *const value);
 
bool fancy_string_equals(fancy_string_t const *const self, fancy_string_t const *const string);
 
bool fancy_string_starts_with_value(fancy_string_t const *const self, char const *const value);
 
bool fancy_string_starts_with(fancy_string_t const *const self, fancy_string_t const *const string);
 
bool fancy_string_ends_with_value(fancy_string_t const *const self, char const *const value);
 
bool fancy_string_ends_with(fancy_string_t const *const self, fancy_string_t const *const string);
 
ssize_t fancy_string_index_of_value(fancy_string_t const *const self, char const *const value);
 
ssize_t fancy_string_index_of(fancy_string_t const *const self, fancy_string_t const *const string);
 
bool fancy_string_contains_value(fancy_string_t const *const self, char const *const value);
 
bool fancy_string_contains(fancy_string_t const *const self, fancy_string_t const *const string);
 
fancy_string_t *fancy_string_substring(fancy_string_t const *const self, ssize_t start, ssize_t end);
 
void fancy_string_trim_left(fancy_string_t *const self);
 
fancy_string_t *fancy_string_trimmed_left(fancy_string_t const *const self);
 
void fancy_string_trim_right(fancy_string_t *const self);
 
fancy_string_t *fancy_string_trimmed_right(fancy_string_t const *const self);
 
void fancy_string_trim(fancy_string_t *const self);
 
fancy_string_t *fancy_string_trimmed(fancy_string_t const *const self);
 
fancy_string_array_t *fancy_string_split_by_value(fancy_string_t const *const self, char const *const separator, ssize_t n_max_splits);
 
fancy_string_array_t *fancy_string_split(fancy_string_t const *const self, fancy_string_t const *const separator, ssize_t n_max_splits);
 
void fancy_string_pad_start(fancy_string_t *const self, size_t target_size, char value);
 
fancy_string_t *fancy_string_padded_start(fancy_string_t const *const self, size_t target_size, char value);
 
void fancy_string_pad_end(fancy_string_t *const self, size_t target_size, char value);
 
fancy_string_t *fancy_string_padded_end(fancy_string_t const *const self, size_t target_size, char value);
 
void fancy_string_replace_value(fancy_string_t *const self, char const *const old_value, char const *const new_value, ssize_t replace_n);
 
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);
 
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);
 
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);
 
void fancy_string_lowercase(fancy_string_t *const self);
 
fancy_string_t *fancy_string_lowercased(fancy_string_t const *const self);
 
void fancy_string_uppercase(fancy_string_t *const self);
 
fancy_string_t *fancy_string_uppercased(fancy_string_t const *const self);
 
void fancy_string_line_break(fancy_string_t *const self, bool with_carriage_return);
 
// -----------------------------------------------
//                  REGEX (methods)
// -----------------------------------------------
 
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);
 
void fancy_string_regex_destroy(fancy_string_regex_t *const self);
 
void fancy_string_regex_debug(fancy_string_regex_t const *const self, FILE *stream, bool verbose);
 
fancy_string_array_t *fancy_string_regex_matches_to_strings(fancy_string_regex_t const *const self);
 
fancy_string_t *fancy_string_regex_replaced_matches(fancy_string_regex_t *const self, fancy_string_t *new_string);
 
fancy_string_array_t *fancy_string_regex_split_at_matches(fancy_string_regex_t const *const self);
 
size_t fancy_string_regex_match_count(fancy_string_regex_t const *const self);
 
bool fancy_string_regex_has_match(fancy_string_regex_t const *const self);
 
ssize_t fancy_string_regex_max_number_of_matches(fancy_string_regex_t const *const self);
 
bool fancy_string_regex_max_number_of_matches_reached(fancy_string_regex_t const *const self);
 
fancy_string_t *fancy_string_regex_string(fancy_string_regex_t const *const self);
 
fancy_string_t *fancy_string_regex_pattern(fancy_string_regex_t const *const self);
 
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);
 
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);
 
fancy_string_regex_match_info_t fancy_string_regex_match_info_for_index(fancy_string_regex_t const *const self, size_t index);
 
fancy_string_t *fancy_string_regex_string_for_match_at_index(fancy_string_regex_t const *const self, size_t index);
 
// -----------------------------------------------
//                  ARRAY (methods)
// -----------------------------------------------
 
fancy_string_array_t *fancy_string_array_create(void);
 
fancy_string_array_t *fancy_string_array_create_with_values(char const *const first_value, ...);
 
fancy_string_array_t *fancy_string_array_clone(fancy_string_array_t const *const self);
 
void fancy_string_array_append(fancy_string_array_t *const self, fancy_string_array_t const *const array);
 
void fancy_string_array_append_and_destroy(fancy_string_array_t *const self, fancy_string_array_t *array);
 
void fancy_string_array_destroy(fancy_string_array_t *const self);
 
void fancy_string_array_print(fancy_string_array_t const *const self, FILE *stream, bool debug);
 
void fancy_string_array_clear(fancy_string_array_t *const self);
 
size_t fancy_string_array_size(fancy_string_array_t const *const self);
 
bool fancy_string_array_is_empty(fancy_string_array_t const *const self);
 
void fancy_string_array_push_value(fancy_string_array_t *const self, char const *const value);
 
void fancy_string_array_push_values(fancy_string_array_t *const self, char const *const first_value, ...);
 
void fancy_string_array_push(fancy_string_array_t *const self, fancy_string_t const *const string);
 
fancy_string_t *fancy_string_array_get(fancy_string_array_t const *const self, size_t index);
 
char *fancy_string_array_get_value(fancy_string_array_t const *const self, size_t index);
 
fancy_string_t *fancy_string_array_remove(fancy_string_array_t *const self, size_t index);
 
void fancy_string_array_remove_and_destroy(fancy_string_array_t *const self, size_t index);
 
fancy_string_t *fancy_string_array_pop(fancy_string_array_t *const self);
 
void fancy_string_array_pop_and_destroy(fancy_string_array_t *const self);
 
fancy_string_t *fancy_string_array_shift(fancy_string_array_t *const self);
 
void fancy_string_array_shift_and_destroy(fancy_string_array_t *const self);
 
void fancy_string_array_insert_value(fancy_string_array_t *const self, char const *const value, size_t index);
 
void fancy_string_array_insert(fancy_string_array_t *const self, fancy_string_t const *const string, size_t index);
 
fancy_string_t *fancy_string_array_first(fancy_string_array_t const *const self);
 
char *fancy_string_array_first_value(fancy_string_array_t const *const self);
 
fancy_string_t *fancy_string_array_last(fancy_string_array_t const *const self);
 
char *fancy_string_array_last_value(fancy_string_array_t const *const self);
 
fancy_string_t *fancy_string_array_join_by_value(fancy_string_array_t const *const self, char const *const separator);
 
fancy_string_t *fancy_string_array_join(fancy_string_array_t const *const self, fancy_string_t const *const separator);
 
void fancy_string_array_reverse(fancy_string_array_t *const self);
 
fancy_string_array_t *fancy_string_array_reversed(fancy_string_array_t const *const self);
 
typedef void (*fancy_string_for_each_t)(fancy_string_t *const string, size_t index, fancy_string_array_t const *const array, void *context);
 
void fancy_string_array_for_each(fancy_string_array_t *const self, fancy_string_for_each_t fn, void *context);
 
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);
 
fancy_string_array_t *fancy_string_array_mapped(fancy_string_array_t const *const self, fancy_string_mapped_t fn, void *context);
 
typedef bool (*fancy_string_sort_t)(fancy_string_t const *const string_1, fancy_string_t const *const string_2, void *context);
 
void fancy_string_array_sort(fancy_string_array_t *const self, fancy_string_sort_t fn, void *context);
 
fancy_string_array_t *fancy_string_array_sorted(fancy_string_array_t const *const self, fancy_string_sort_t fn, void *context);
 
void fancy_string_array_sort_values(fancy_string_array_t *const self);
 
fancy_string_array_t *fancy_string_array_sorted_values(fancy_string_array_t const *const self);
 
typedef bool (*fancy_string_filter_t)(fancy_string_t const *const string, size_t index, fancy_string_array_t const *const array, void *context);
 
void fancy_string_array_filter(fancy_string_array_t *const self, fancy_string_filter_t fn, void *context);
 
fancy_string_array_t *fancy_string_array_filtered(fancy_string_array_t const *const self, fancy_string_filter_t fn, void *context);
 
fancy_string_array_t *fancy_string_array_sliced(fancy_string_array_t const *const self, ssize_t start, ssize_t end);
 
void fancy_string_array_slice_and_destroy(fancy_string_array_t *const self, ssize_t start, ssize_t end);
 
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);
 
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);
 
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);
 
typedef bool (*fancy_string_find_t)(fancy_string_t const *const string, size_t index, fancy_string_array_t const *const array, void *context);
 
ssize_t fancy_string_array_find_index(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
fancy_string_t *fancy_string_array_find(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
ssize_t fancy_string_array_find_last_index(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
fancy_string_t *fancy_string_array_find_last(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
bool fancy_string_array_some(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
bool fancy_string_array_none(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
bool fancy_string_array_every(fancy_string_array_t const *const self, fancy_string_find_t fn, void *context);
 
ssize_t fancy_string_array_index_of(fancy_string_array_t const *const self, fancy_string_t const *const string);
 
ssize_t fancy_string_array_index_of_value(fancy_string_array_t const *const self, char const *const value);
 
ssize_t fancy_string_array_last_index_of(fancy_string_array_t const *const self, fancy_string_t const *const string);
 
ssize_t fancy_string_array_last_index_of_value(fancy_string_array_t const *const self, char const *const value);
 
bool fancy_string_array_includes(fancy_string_array_t const *const self, fancy_string_t const *const string);
 
bool fancy_string_array_includes_value(fancy_string_array_t const *const self, char const *const value);
 
#endif