CSPP-coursework/final/dynstr.h

#ifndef DYNSTR_H
#define DYNSTR_H
#include <stdio.h>
#include <stdint.h>

/** 
 * Custom String type that stores an array of characters
*/
typedef struct String {
    uint32_t size, capacity;
    char* data;
} String_t;

/**
 * Creates a new string with the specified initial capacity.
 * The string will be empty but can hold up to capacity characters
 * without requiring reallocation.
 * 
 * @param capacity Initial capacity in bytes
 * @return A new String_t structure with allocated memory
 */
String_t str_with_capacity(int capacity);

/**
 * Creates a new string from a null-terminated character array.
 * 
 * @param string Null-terminated source string
 * @return A new String_t containing a copy of the input string
 */
String_t str_from_chars(char* string);

/**
 * Creates a new string from a character array slice.
 * Allocates new memory and copies the specified number of characters.
 * 
 * @param string Source character array
 * @param len Number of characters to copy
 * @return A new String_t containing the copied characters
 */
String_t str_from_slice(char* string, int len);

/**
 * Merges two strings into a new string.
 * The resulting string contains s1's contents followed by s2's contents.
 * 
 * @param s1 Pointer to the first String_t
 * @param s2 Pointer to the second String_t
 * @return A new String_t containing the merged contents
 */
String_t str_merge(String_t* s1, String_t* s2);

/**
 * Creates a new string by reading from a file.
 * Reads the file line by line and concatenates all lines.
 * 
 * @param file Pointer to an open FILE
 * @return A new String_t containing the file's contents
 */
String_t str_from_file(FILE* file);

/**
 * Creates a new empty string with minimal capacity.
 * 
 * @return A new empty String_t with capacity of 1 byte
 */
String_t str_new();

/** 
 * Returns a clone of the string.
 * This allocates new memory that must be freed
 * @param self Pointer to the String_t to clone
*/
String_t str_clone(String_t* self);

String_t* str_clone_all(String_t* strings, int len);

/**
 * Creates a new string containing a slice of an existing string.
 * The slice includes characters from start index up to (but not including) end index.
 * 
 * @param s Pointer to the source String_t
 * @param start Starting index (inclusive)
 * @param end Ending index (exclusive)
 * @return A new String_t containing the specified slice
 */
String_t str_slice(String_t* s, int start, int end);

/**
 * Splits a string into lines based on newline characters.
 * Convenience wrapper around str_split that uses '\n' as delimiter.
 * 
 * @param self Pointer to the String_t to split
 * @param numlines Pointer to store the number of resulting lines
 * @return Array of String_t structures, one per line
 */
String_t* str_lines(String_t* self, int* numlines);

/**
 * Splits a string into an array of strings based on a delimiter.
 * Each occurrence of the delimiter creates a new string.
 * 
 * @param self Pointer to the String_t to split
 * @param res_len Pointer to store the number of resulting strings
 * @param c Delimiter character
 * @return Array of String_t structures, must be freed by caller
 */
String_t* str_split(String_t* self, int* res_len, char c);

/**
 * Removes and returns the last character in the string.
 * 
 * @param self Pointer to the String_t to modify
 * @return The removed character, or '\0' if string is empty
 */
char str_pop(String_t* s);

/**
 * Returns a pointer to the underlying character array.
 * Note: The returned pointer is still owned by the String_t structure.
 * 
 * @param s Pointer to the String_t structure
 * @return Pointer to the null-terminated character array
 */
char* to_chars(String_t* s);

/**
 * Writes the string's contents to a file.
 * Appends a newline character after writing the string.
 * 
 * @param self Pointer to the String_t to write
 * @param file Pointer to an open FILE
 * @return 0 on success, -1 on failure
 */
int str_to_file(String_t* self, FILE* file);

/**
 * Appends a null-terminated string to the end of the string.
 * Automatically reallocates if more capacity is needed.
 * 
 * @param self Pointer to the String_t to modify
 * @param c Null-terminated string to append
 * @return 0 on success
 */
int str_push_str(String_t* string, char* other);

/**
 * Deallocates the memory used by a string.
 * Must be called when the string is no longer needed to prevent memory leaks.
 * 
 * @param self Pointer to the String_t to deallocate
 * @return 0 on success
 */
int str_dealloc(String_t* s);

/**
 * Returns the current length of the string.
 * 
 * @param s Pointer to the String_t structure
 * @return The number of characters in the string
 */
int str_len(String_t* s);

/**
 * Inserts a character at the specified index.
 * Shifts existing characters right to make room.
 * Automatically reallocates if more capacity is needed.
 * 
 * @param self Pointer to the String_t to modify
 * @param index Position to insert the character
 * @param c Character to insert
 * @return 0 on success, -1 if index is out of bounds
 */
void str_insert(String_t* s, int index, char c);

/**
 * Removes the character at the specified index.
 * Shifts remaining characters left to fill the gap.
 * 
 * @param self Pointer to the String_t to modify
 * @param index Position of character to remove
 * @return 0 on success, -1 if index is out of bounds
 */
void str_remove(String_t* s, int index);

/**
 * Appends a single character to the end of the string.
 * Automatically reallocates if more capacity is needed.
 * 
 * @param self Pointer to the String_t to modify
 * @param c Character to append
 * @return 0 on success
 */
void str_push(String_t* s, char c);

#endif