diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/serd/serd.h | 51 |
1 files changed, 27 insertions, 24 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h index b70500c1..d606f4bb 100644 --- a/include/serd/serd.h +++ b/include/serd/serd.h @@ -311,7 +311,7 @@ serd_strncasecmp(const char* SERD_NONNULL s1, Source function for raw string input. Identical semantics to `fread`, but may set errno for more informative error - reporting than supported by SerdStreamErrorFunc. + reporting than supported by #SerdErrorFunc. @param buf Output buffer. @param size Size of a single element of data in bytes (always 1). @@ -328,7 +328,7 @@ typedef size_t (*SerdReadFunc)(void* SERD_NONNULL buf, Sink function for raw string output. Identical semantics to `fwrite`, but may set errno for more informative - error reporting than supported by SerdStreamErrorFunc. + error reporting than supported by #SerdErrorFunc. @param buf Input buffer. @param size Size of a single element of data in bytes (always 1). @@ -342,22 +342,25 @@ typedef size_t (*SerdWriteFunc)(const void* SERD_NONNULL buf, void* SERD_NONNULL stream); /** - Function to detect I/O stream errors. + Function for detecting I/O stream errors. - Identical semantics to `ferror`. + This has identical semantics to `ferror`. @return Non-zero if `stream` has encountered an error. */ -typedef int (*SerdStreamErrorFunc)(void* SERD_NONNULL stream); +typedef int (*SerdErrorFunc)(void* SERD_NONNULL stream); /** - Function to close an I/O stream. + Function for closing an I/O stream. - Identical semantics to `fclose`. + This has identical semantics to `fclose`. Note that when writing, this may + flush the stream which can cause errors, including errors caused by previous + writes that appeared successful at the time. Therefore it is necessary to + check the return value of this function to properly detect write errors. @return Non-zero if `stream` has encountered an error. */ -typedef int (*SerdStreamCloseFunc)(void* SERD_NONNULL stream); +typedef int (*SerdCloseFunc)(void* SERD_NONNULL stream); /** @} @@ -2197,10 +2200,10 @@ serd_node_to_syntax(const SerdNode* SERD_NONNULL node, /// An input stream that produces bytes typedef struct { - void* SERD_NULLABLE stream; ///< Opaque parameter for functions - SerdReadFunc SERD_NULLABLE read; ///< Read bytes to input - SerdStreamErrorFunc SERD_NONNULL error; ///< Stream error accessor - SerdStreamCloseFunc SERD_NULLABLE close; ///< Close input + void* SERD_NULLABLE stream; ///< Opaque parameter for functions + SerdReadFunc SERD_NULLABLE read; ///< Read bytes to input + SerdErrorFunc SERD_NONNULL error; ///< Stream error accessor + SerdCloseFunc SERD_NULLABLE close; ///< Close input } SerdInputStream; /** @@ -2215,10 +2218,10 @@ typedef struct { */ SERD_CONST_API SerdInputStream -serd_open_input_stream(SerdReadFunc SERD_NONNULL read_func, - SerdStreamErrorFunc SERD_NONNULL error_func, - SerdStreamCloseFunc SERD_NULLABLE close_func, - void* SERD_NULLABLE stream); +serd_open_input_stream(SerdReadFunc SERD_NONNULL read_func, + SerdErrorFunc SERD_NONNULL error_func, + SerdCloseFunc SERD_NULLABLE close_func, + void* SERD_NULLABLE stream); /** Open a stream that reads from a string. @@ -2410,8 +2413,8 @@ serd_reader_free(SerdReader* SERD_NULLABLE reader); @defgroup serd_buffer Buffer The #SerdBuffer type represents a writable area of memory with a known size. - An implementation of #SerdWriteFunc, #SerdStreamErrorFunc, and - #SerdStreamCloseFunc are provided which allow output to be written to a + An implementation of #SerdWriteFunc, #SerdErrorFunc, and + #SerdCloseFunc are provided which allow output to be written to a buffer in memory instead of to a file as with `fwrite`, `ferror`, and `fclose`. @@ -2464,9 +2467,9 @@ serd_buffer_close(void* SERD_NONNULL stream); /// An output stream that receives bytes typedef struct { - void* SERD_NULLABLE stream; ///< Opaque parameter for functions - SerdWriteFunc SERD_NULLABLE write; ///< Write bytes to output - SerdStreamCloseFunc SERD_NULLABLE close; ///< Close output + void* SERD_NULLABLE stream; ///< Opaque parameter for functions + SerdWriteFunc SERD_NULLABLE write; ///< Write bytes to output + SerdCloseFunc SERD_NULLABLE close; ///< Close output } SerdOutputStream; /** @@ -2480,9 +2483,9 @@ typedef struct { */ SERD_CONST_API SerdOutputStream -serd_open_output_stream(SerdWriteFunc SERD_NONNULL write_func, - SerdStreamCloseFunc SERD_NULLABLE close_func, - void* SERD_NULLABLE stream); +serd_open_output_stream(SerdWriteFunc SERD_NONNULL write_func, + SerdCloseFunc SERD_NULLABLE close_func, + void* SERD_NULLABLE stream); /** Open a stream that writes to a buffer. |