开始设计

cKit/Foundation/c_utf8_file.h

@@ -0,0 +1,61 @@
+#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*/