Archive

An Archive is used to serialise a variable to an IOutputStream. See Stream Interfaces.

The use of streams and an Archive is deprecatated. Instead, the preferred approach is to use an OutputArchive which works directly with contiguous buffers in memory. That provides better performance, and reduces the amount of code that can throw exceptions - see the interleaving computation and I/O Anti-pattern.

class Archive
{
public:
    explicit Archive(IOutputStream* oStream);
    ~Archive();
    
    // Warning: this can defeat information recorded about the number of bytes written
    // to the stream.
    IOutputStream* GetOutputStream();

    octet_t* BeginWrite(ssize_t reserveSize);
    void EndWrite(octet_t* pos);
    
    template <typename T> void SerialisePod(const T& t);
    
    // Write the given buffer to the archive
    void WriteBuffer(const void* buffer, ssize_t numBytes);

    // Returns number of bytes transferred
    ssize_t WriteStream(IInputStream* src);

    // Copy the given number of bytes from the src to the archive.  Returns the actual number of bytes
    // copied (if met EOF on the src)
    ssize_t WriteStream(IInputStream* src, ssize_t numBytes);
    
    ssize_t NumBufferedWrites() const;
    void ClearWriteBuffer();
    void ClearWriteBufferAndNumBytesWritten();

    void Flush();
    
    // Provides the number of bytes that have been written to the underlying stream using
    // the archive, which may be less than the number of bytes written to the archive due
    // to write buffering.
    int64 GetNumBytesWrittenToStream() const;

    // Get the number of bytes that have been written to this Archive.
    int64 GetNumBytesWritten() const;
};

template<typename T>
Archive& operator<<(Archive& ar, const T& x);

void Serialise(Archive& ar, bool x);
void Serialise(Archive& ar, char x);
void Serialise(Archive& ar, signed char x);
void Serialise(Archive& ar, unsigned char x);
void Serialise(Archive& ar, char16_t x);
void Serialise(Archive& ar, char32_t x);
void Serialise(Archive& ar, wchar_t x);
void Serialise(Archive& ar, short x);
void Serialise(Archive& ar, unsigned short x);
void Serialise(Archive& ar, int x);
void Serialise(Archive& ar, unsigned int x);
void Serialise(Archive& ar, long x);
void Serialise(Archive& ar, unsigned long x);
void Serialise(Archive& ar, long long x);
void Serialise(Archive& ar, unsigned long long x);
void Serialise(Archive& ar, float x);
void Serialise(Archive& ar, double x);
void Serialise(Archive& ar, long double x);