#ifndef INCLUDED_C_UTF8_FILE_H
#define INCLUDED_C_UTF8_FILE_H

#ifndef INCLUDED_C_STRINGBUFFER_H
#include <c_StringBuffer.h>
#endif /*INCLUDED_C_STRINGBUFFER_H*/

#ifndef INCLUDED_C_UTF8_H
#include <c_utf8.h>
#endif /*INCLUDED_C_UTF8_H*/

#ifndef INCLUDED_STDIO_H
#define INCLUDED_STDIO_H
#include <stdio.h>
#endif /*INCLUDED_STDIO_H*/




/* ------------------------------------------------------------------------------------------------------------------ */
/*  */

/**
 * @brief Reads the entire contents of a UTF-8 text file into a string buffer structure.
 *        Automatically handles, validates, and skips the UTF-8 BOM marker if present.
 * @param filepath Path to the target source file on disk.
 * @param out_sb   Pointer to a pre-initialized c_StringBuffer_t container to collect file data.
 * @return c_err_t C_ERR_OK on complete success, C_ERR_PARAM on invalid inputs, or C_ERR_FAIL if file access throws errors.
 */
c_err_t c_utf8_file_read(const char* filepath, c_StringBuffer_t* out_sb);

/**
 * @brief Writes data from a string buffer out to a disk file using a UTF-8 text layout stream.
 * @param filepath  Path to the destination file on disk.
 * @param sb        Pointer to the source string buffer containing data.
 * @param write_bom If set to C_TRUE, explicitly prefixes the file layout with the 3-byte UTF-8 BOM marker.
 * @return c_err_t  C_ERR_OK on complete success, C_ERR_PARAM on invalid inputs, or C_ERR_FAIL on disk write errors.
 */
c_err_t c_utf8_file_write(const char* filepath, c_StringBuffer_t* sb, c_bool_t write_bom);

/**
 * @brief Appends text from a string buffer to a disk file.
 *        If the target file does not exist, it initializes it (with an optional BOM marker).
 * @param filepath  Path to the destination file on disk.
 * @param sb        Pointer to the source string buffer containing the append payload.
 * @param write_bom If set to C_TRUE and the file is new, prefixes the stream with the 3-byte UTF-8 BOM.
 * @return c_err_t  C_ERR_OK on complete success, C_ERR_PARAM on invalid inputs, or C_ERR_FAIL on disk write errors.
 */
c_err_t c_utf8_file_append(const char* filepath, c_StringBuffer_t* sb, c_bool_t write_bom);

/**
 * @brief Reads a single line of text from an open file stream into a string buffer (Dynamic fgets).
 *        Automatically handles standard '\n' and '\r\n' line endings.
 * @param file      An active file stream pointer opened in binary read ("rb") mode.
 * @param out_line  Pointer to a pre-initialized c_StringBuffer_t container to collect the line string.
 * @return c_err_t  C_ERR_OK on successful line read, C_ERR_FAIL when reaching EOF with no data, or parameter errors.
 */
c_err_t c_utf8_file_readline(FILE* file, c_StringBuffer_t* out_line);


#endif /*INCLUDED_C_UTF8_FILE_H*/