diff --git a/source/coral/files.cpp b/source/coral/files.cpp index 1d059b6..588ff00 100644 --- a/source/coral/files.cpp +++ b/source/coral/files.cpp @@ -4,7 +4,7 @@ import coral; export namespace coral { /** - * Platform-generalized identifier for a resource in a [file_store]. + * Platform-generalized identifier for a resource in a [fs]. */ struct path { /** @@ -86,6 +86,8 @@ export namespace coral { * Returns a new [path] composed of the current path joined with `text`. * * *Note:* should the new path exceed [max] bytes in size, an empty [path] is returned instead. + * + * *Note:* should the new path exceed [max] bytes in size, an empty [path] is returned instead. */ constexpr path joined(slice const & text) const { if (text.length > this->buffer[max]) return path{}; @@ -104,15 +106,37 @@ export namespace coral { char buffer[max + 1]{0}; }; + /** + * [reader] that has a known range of data and may attempt to traverse it freely. + */ struct file_reader : public reader { + /** + * Attempts to seek to the position in the file defined by `offset`, returning the literal absolute position + * that was actually sought to or a [io_error] if the operation failed for whatever reason. + */ virtual expected seek(u64 offset) = 0; + /** + * Attempts to get the current cursor position in the file, returning the literal absolute position of it or a + * [io_error] if the operation failed for whatever reason. + */ virtual expected tell() = 0; }; + /** + * [writer] that has a known range of data and may attempt to traverse it freely. + */ struct file_writer : public writer { + /** + * Attempts to seek to the position in the file defined by `offset`, returning the literal absolute position + * that was actually sought to or a [io_error] if the operation failed for whatever reason. + */ virtual expected seek(u64 offset) = 0; + /** + * Attempts to get the current cursor position in the file, returning the literal absolute position of it or a + * [io_error] if the operation failed for whatever reason. + */ virtual expected tell() = 0; }; diff --git a/source/coral/io.cpp b/source/coral/io.cpp index 1ae6019..11221e8 100644 --- a/source/coral/io.cpp +++ b/source/coral/io.cpp @@ -4,8 +4,8 @@ import coral; export namespace coral { /** - * Multiplexing byte-based ring buffer of `capacity` size that may be used for memory-backed - * I/O operations and lightweight data construction. + * Multiplexing byte-based ring buffer of `capacity` size that may be used for memory-backed I/O operations and + * lightweight data construction. */ template struct fixed_buffer : public writer, public reader { fixed_buffer() = default; @@ -13,8 +13,8 @@ export namespace coral { /** * Returns a mutable [slice] ranging from the head to the last-filled element. * - * *Note*: The lifetime and validity of the returned slice is only guaranteed for as long - * as the source [fixed_buffer] is not mutated or out-of-scope. + * *Note*: The lifetime and validity of the returned slice is only guaranteed for as long as the source + * [fixed_buffer] is not mutated or out-of-scope. */ slice as_slice() const { return {0, this->filled}; @@ -56,8 +56,8 @@ export namespace coral { } /** - * Attempts to write the single value `data` into the buffer, returning `true` if - * successful, otherwise `false` if the buffer is full. + * Attempts to write the single value `data` into the buffer, returning `true` if successful, otherwise `false` + * if the buffer is full. */ bool put(u8 data) { if (this->is_full()) return false; @@ -70,8 +70,7 @@ export namespace coral { } /** - * Reads whatever data is in the buffer into `data`, returning the number of bytes read - * from the buffer. + * Reads whatever data is in the buffer into `data`, returning the number of bytes read from the buffer. */ expected read(slice const & data) override { slice const readable_data{this->data, min(this->filled, data.length)}; @@ -87,9 +86,8 @@ export namespace coral { } /** - * Attempts to write `data` to the buffer, returning the number of bytes written or - * [io_error::unavailable] if it has been completely filled and no more bytes can be - * written. + * Attempts to write `data` to the buffer, returning the number of bytes written or [io_error::unavailable] if + * it has been completely filled and no more bytes can be written. */ expected write(slice const & data) override { if (this->is_full()) return io_error::unavailable; @@ -119,11 +117,11 @@ export namespace coral { /** * Streams the data from `input` to `output`, using `buffer` as temporary transfer space. * - * The returned [expected] can be used to introspect if `input` or `output` encountered any - * issues during streaming, otherwise it will contain the number of bytes streamed. + * The returned [expected] can be used to introspect if `input` or `output` encountered any issues during streaming, + * otherwise it will contain the number of bytes streamed. * - * *Note*: if `buffer` has a length of `0`, no data will be streamed as there is nowhere to - * temporarily place data during streaming. + * *Note*: if `buffer` has a length of `0`, no data will be streamed as there is nowhere to temporarily place data + * during streaming. */ expected stream(writer & output, reader & input, slice const & buffer) { usize total_bytes_written = 0; @@ -172,8 +170,8 @@ export namespace coral { /** * Attempts to format and print `value` as an unsigned integer out to `output`. * - * The returned [expected] can be used to introspect if `output` encountered any issues during - * printing, otherwise it will contain the number of characters used to print `value` as text. + * The returned [expected] can be used to introspect if `output` encountered any issues during printing, otherwise + * it will contain the number of characters used to print `value` as text. */ expected print_unsigned(writer & output, u64 value) { if (value == 0) return output.write(slice{"0"}.as_bytes()); diff --git a/source/coral/stack.cpp b/source/coral/stack.cpp index 50b74dd..12707ad 100644 --- a/source/coral/stack.cpp +++ b/source/coral/stack.cpp @@ -9,8 +9,7 @@ export namespace coral { * * [push_result::ok] indicates that an push operation was successful. * - * [push_result::out_of_memory] alerts that the memory required to perform the push operation - * failed. + * [push_result::out_of_memory] alerts that the memory required to perform the push operation failed. */ enum class [[nodiscard]] push_result { ok, @@ -20,8 +19,8 @@ export namespace coral { /** * Base type for all stack types. * - * Sequences are any data structure which owns a linear, non-unique set of elements which may - * be queried and/or mutated. + * Sequences are any data structure which owns a linear, non-unique set of elements which may be queried and/or + * mutated. */ template struct stack { virtual ~stack() {}; @@ -29,8 +28,8 @@ export namespace coral { /** * Returns a read-only [slice] of the current range values. * - * *Note*: the behavior of retaining the returned value past the scope of the source - * [stack] or any subsequent modifications to it is implementation-defined. + * *Note*: the behavior of retaining the returned value past the scope of the source [stack] or any subsequent + * modifications to it is implementation-defined. */ virtual slice as_slice() const = 0; @@ -39,24 +38,21 @@ export namespace coral { * * The returned [push_result] indicates whether the operation was successful or not. * - * If the returned [push_result] is anything but [push_result::ok], the [stack] will be - * left in an implementation-defined state. + * If the returned [push_result] is anything but [push_result::ok], the [stack] will be left in an + * implementation-defined state. */ virtual push_result push_all(slice const & source_elements) = 0; }; /** - * Last-in-first-out contiguous sequence of `element` values optimized for small numbers of - * small-sized elements. + * Last-in-first-out contiguous sequence of `element` values optimized for small numbers of small-sized elements. * - * [small_stack] types will default to using an inline array of `init_capacity` at first. After - * all local storage has been exhausted, the [small_stack] will switch to a dynamic buffer. - * Because of this, it is recommended to use larger `init_capacity` values for data which has a - * known or approximate upper bound at compile-time. Otherwise, the `init_capacity` value may - * be left at its default. + * [small_stack] types will default to using an inline array of `init_capacity` at first. After all local storage + * has been exhausted, the [small_stack] will switch to a dynamic buffer. Because of this, it is recommended to use + * larger `init_capacity` values for data which has a known or approximate upper bound at compile-time. Otherwise, + * the `init_capacity` value may be left at its default. * - * *Note*: the [allocator] referenced in the stack must remain valid for the duration of the - * stack lifetime. + * *Note*: the [allocator] referenced in the stack must remain valid for the duration of the stack lifetime. */ template struct small_stack : public stack { small_stack(allocator * dynamic_allocator) { @@ -74,8 +70,8 @@ export namespace coral { /** * Returns a read-only [slice] of the current stack values. * - * *Note*: the returned slice should be considered invalid if any mutable operation is - * performed on the source [stack] or it is no longer in scope. + * *Note*: the returned slice should be considered invalid if any mutable operation is performed on the source + * [stack] or it is no longer in scope. */ slice as_slice() const override { return this->elements.sliced(0, this->filled); @@ -93,8 +89,8 @@ export namespace coral { * * The returned [push_result] indicates whether the operation was successful or not. * - * If the returned [push_result] is anything but [push_result::ok], the stack will be - * be left in an empty but valid state. + * If the returned [push_result] is anything but [push_result::ok], the stack will be be left in an empty but + * valid state. * * *Note* that [push_all] is recommended when appending many values at once. */ @@ -116,8 +112,8 @@ export namespace coral { * * The returned [push_result] indicates whether the operation was successful or not. * - * If the returned [push_result] is anything but [push_result::ok], the stack will be left - * in an empty but valid state. + * If the returned [push_result] is anything but [push_result::ok], the stack will be left in an empty but valid + * state. * * *Note* that [push] is recommended when appending singular values. */ @@ -139,16 +135,15 @@ export namespace coral { } /** - * Attempts to reserve `capacity` number of elements additional space on the stack, forcing - * it to use dynamic memory _even_ if it hasn't exhausted the local buffer yet. + * Attempts to reserve `capacity` number of elements additional space on the stack, forcing it to use dynamic + * memory _even_ if it hasn't exhausted the local buffer yet. * * The returned [push_result] indicates whether the operation was successful or not. * - * If the returned [push_result] is anything but [push_result::ok], the stack will be left - * in an empty but valid state. + * If the returned [push_result] is anything but [push_result::ok], the stack will be left in an empty but valid + * state. * - * *Note* that manual invocation is not recommended if the [stack] has a large - * `initial_capacity` argument. + * *Note* that manual invocation is not recommended if the [stack] has a large `init_capacity` argument. */ push_result reserve(usize capacity) { usize const requested_capacity = this->filled + capacity; @@ -236,8 +231,8 @@ export namespace coral { } /** - * Attempts to write `buffer` to the target stack, returning the number of bytes written or - * an [io_error] if it failed to commit `buffer` to the stack memory. + * Attempts to write `buffer` to the target stack, returning the number of bytes written or an [io_error] if it + * failed to commit `buffer` to the stack memory. */ expected write(slice const & buffer) override { switch (this->stack->push_all(buffer)) {