fileStreamWriter

fileStreamWriter

Overview

The fileStreamWriter class in the Athena library is designed for writing data to files. It extends the streamWriter base class and provides functionality for handling file-based streams with support for multiple sections, ensuring efficient and flexible data writing operations.

Methods

Constructor and Destructor

• fileStreamWriter(std::filesystem::path& path): Constructs a fileStreamWriter object, opening the file at the specified path for writing.
• ~fileStreamWriter(): Destructor that cleans up resources associated with the file stream.

Stream Management

• bool isStreamGood() const: Checks if the file stream is in a good state for writing operations.
• void setSectionPointerPosition(size_t index): Sets the current position to the specified section index. This allows for targeting specific sections in the stream for writing.
• void setStreamPosition(size_t index): Sets the overall position within the stream to the specified index. Useful for seeking to different parts of the stream.

Section Management

• void previousStreamSection(): Moves the current section pointer to the previous section. This method allows navigation through different sections of the stream.
• void nextStreamSection(): Moves the current section pointer to the next section. Use this to advance to subsequent sections in the stream.
• size_t getStreamSectionCount() const: Retrieves the total number of sections in the stream.

Data Writing

• void writeData(const char* data, size_t size): Writes raw data to the current section of the stream.
• template<typename T> void writeObject(const T& object): Writes a single object of type T to the current section. The object is serialized using the writeObject method of the buffer class.
• template<typename T> void writeArray(const std::vector<T>& vector): Writes an array (vector) of objects of type T to the current section. Each element is serialized using the writeArray method of the buffer class.
• compressedBuffer flush(): Finalizes the current section and flushes any remaining data to the file. Returns a compressedBuffer containing the compressed data.

Handling Non-Trivially Copyable Types

For types that are not trivially copyable (e.g., std::string), you need to provide a custom serialization function. The function should have the following signature:

template<typename T>
static void serialize(athena::buffer* buf, const T& obj);

the responsibility of COMPATIBILTY in this case falls upon the user not the library!

Examples

Basic Usage

#include <athena.h>

struct Data {
    int id;
    float value;
};

int main() 
{
    std::filesystem::path path = "./output.bin";
    athena::fileStreamWriter writer(path);

    std::vector<Data> dataArray = {{1, 1.1f}, {2, 2.2f}, {3, 3.3f}};

    writer.writeArray(dataArray);  // Write the array to the current section
    writer.nextStreamSection();     // Move to the next section
    writer.writeObject(Data{4, 4.4f});  // Write a single object to the new section

    writer.flush();  // Compress all the sections and write to disk
    return 0;
}

Using Sections

#include <athena.h>

struct Record 
{
    int id;
    float value;
};

int main() 
{
    std::filesystem::path path = "./data.bin";
    athena::fileStreamWriter writer(path);

    std::vector<Record> records1 = {{1, 1.1f}, {2, 2.2f}};
    std::vector<Record> records2 = {{3, 3.3f}, {4, 4.4f}};

    writer.writeArray(records1);   // Write first array of records
    writer.nextStreamSection();    // Move to next section
    writer.writeArray(records2);   // Write second array of records

    writer.setStreamPosition(0);   // Move to the start of the stream
    writer.setSectionPointerPosition(0); // Move to first byte of the section (write from here)
    writer.writeObject(Record{5, 5.5f});  // Add an additional record

    writer.flush();  // Compress all the sections and write to disk
    return 0;
}

Serializing non trivial objects

#include <athena.h>
#include <string>

// Define a struct with non-trivially copyable types
struct MyStruct 
{
    int id;
    float value;
    std::string name; // Non-trivially copyable

    // Serialization function for MyStruct
    static void serialize(athena::buffer* buf,const MyStruct& data) const {
        buf->writeData(reinterpret_cast<const char*>(&data.id), sizeof(data.id)); // Write integer
        buf->writeData(reinterpret_cast<const char*>(&data.value), sizeof(data.value)); // Write float

        size_t nameLength = data.name.size();
        buf->writeData(reinterpret_cast<const char*>(&nameLength), sizeof(nameLength)); // Write length of the string
        buf->writeData(data.name.data(), nameLength); // Write string data
    }
};

int main()
{
    // Define the path to the file
    std::filesystem::path path = "data.bin";

    // Create a fileStreamWriter
    athena::fileStreamWriter writer(path);

    // Create an instance of MyStruct
    MyStruct myData = {1, 3.14f, "example"};

    // Write the object to the file
    writer.writeObject(myData);

    // Flush and close the file
    writer.flush();
}

---

The fileStreamWriter class is an essential part of the Athena library's file handling capabilities, offering efficient and flexible options for writing binary data to complex, multi-section files.