UT_StringStream.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_StringStream.h ( UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_StringStream__
#define __UT_StringStream__

#include "UT_API.h"
#include "UT_WorkBuffer.h"

#include <iostream>

/// An a string buffer based on UT_WorkBuffer. Supports both input and output.
/// Provides cleaner semantics than UT_OStrStream, which is based on the
/// obsolete std::strstream class. Unlike UT_OStrStream, it is not necessary
/// to manage the stream's memory externally, if it was dynamically allocated,
/// or add a null byte termination. 
/// For example, this code:
/// @code{.cpp}
/// UT_OStrStream        os;
/// SomeClass::save(os);  // write things to os.
/// os << std::ends;
/// fprintf(stderr, "Buffer: %s", os.str());
/// os.rdbuf()->freeze(false);
/// @endcode
/// Turns into:
//// @code{.cpp}
/// UT_OStringStream     os;
/// SomeClass::save(os);  // write things to os.
/// fprintf(stderr, "Buffer: %s", os.str());
/// @endcode
/// Note that the explicit requirement for null termination, and the call
/// to @c freeze to relinquish the buffer use, are both gone.
///
/// However, the downside is that you cannot pass explicit buffers to the 
/// stream. On the other hand, you should not be using fixed-sized buffers for
/// output streams in the first place.
///
/// There's also support for input and input/output buffers, using 
/// UT_IStringStream and UT_StringStream.

/// Class for the memory storage and stream buffering.
///
/// std::streambuf provides buffered reading and writing to an underlying
/// stream.  A UT_WorkBuffer is used for the underlying storage.  Like a file,
/// seeking past the end of the existing data is allowed.
///
/// The get buffer (reading) is defined by the eback(), gptr(), and egptr()
/// pointers.  These pointers are all nullptr iff the stream does not allow
/// reading.  myGPos >= 0 when seeked past the end of the existing data.  In
/// this situation, eback() == egptr() to prevent methods from pulling values
/// from the get buffer.
///
/// The put buffer (writing) is defined by the pbase(), pptr(), and epptr()
/// pointers.  These pointers are all nullptr iff the stream does not allow
/// writing.  myPPos >= 0 when seeked past the end of the existing data.  In
/// this situation, pbase() == epptr() to prevent methods from putting values
/// into the put buffer.
class UT_StringStreamBuffer : public std::streambuf
{
public:
    UT_StringStreamBuffer(
        std::ios_base::openmode mode = (std::ios_base::in | std::ios_base::out),
        const char *buf=nullptr,
        exint len=-1);

    const char *buffer() const { return myBuffer.buffer(); }
    exint length() const { return myBuffer.length(); }

    int64 getMemoryUsage(bool inclusive) const
    {
        int64 mem = myBuffer.getMemoryUsage(false);
        if(inclusive)
            mem += sizeof(*this);
        return mem;
    }

    // Resets the buffer to an empty state. Does not de-allocate existing
    // memory.
    void reset();

    // Returns a reference to the current string.
    const UT_WorkBuffer &str();
    void swap(UT_WorkBuffer &buf);
    void stealIntoString(UT_String &s);
    void stealIntoStringHolder(UT_StringHolder &s);

private:
    // iostream implementation helpers
    std::streambuf::pos_type seekoff(
        std::streambuf::off_type offset,
        std::ios_base::seekdir dir,
        std::ios_base::openmode mode) override;

    std::streambuf::pos_type seekpos(
        std::streambuf::pos_type pos,
        std::ios_base::openmode mode) override;

    // istream implementation helpers
    std::streambuf::int_type underflow() override;

    std::streamsize xsgetn(
        std::streambuf::char_type *dst,
        std::streamsize num) override;

    std::streamsize showmanyc() override;

    std::streambuf::int_type pbackfail(std::streambuf::int_type c) override;

    // ostream implementation helpers
    std::streambuf::int_type overflow(int_type c) override;

    std::streamsize xsputn(
        const std::streambuf::char_type *src,
        std::streamsize num) override;

    // get/put buffer management
    void init();
    void setg64(char *start, char *cur, char *end);
    void setp64(char *start, char *cur, char *end);
    void updategpos(exint pos);
    void updateppos(exint pos);

    void reserve(exint bytes);

    // Updates the underlying buffer with proper termination.
    void updateBufferEnd();

    UT_WorkBuffer myBuffer;
    exint myGPos;
    exint myPPos;
};

/// An input stream object that owns its own string buffer storage.  
class UT_IStringStream : public std::istream
{
public:
    /// Populate the input stream with an existing raw character buffer. 
    /// The contents of the buffer are copied into the internal storage.
    /// The input position start at the beginning of the buffer.
    UT_IStringStream(const char *buf=nullptr, exint len=-1)
        : myBuffer(std::ios_base::in, buf, len)
        , std::istream(&myBuffer) {}

    /// Returns the underlying stream buffer object.
    UT_StringStreamBuffer *rdbuf() const { return SYSconst_cast(&myBuffer); }

private:
    UT_StringStreamBuffer myBuffer;
};

/// An output stream object that owns its own string buffer storage.  
class UT_OStringStream : public std::ostream
{
public:
    /// Start with an empty string buffer with a given size reservation, if it
    /// is known in advance how much data will be written out. 
    UT_OStringStream(exint reserved_size=-1)
        : myBuffer(std::ios_base::out, nullptr, reserved_size)
        , std::ostream(&myBuffer) {}

    int64 getMemoryUsage(bool inclusive) const
    {
        int64 mem = myBuffer.getMemoryUsage(false);
        if(inclusive)
            mem += sizeof(*this);
        return mem;
    }

    /// Returns the underlying stream buffer object.
    UT_StringStreamBuffer *rdbuf() const { return SYSconst_cast(&myBuffer); }

    /// Returns a read-only reference to the underlying UT_WorkBuffer. 
    const UT_WorkBuffer &str() { return myBuffer.str(); }

    /// Resets the input stream and clears all existing input data.
    void reset() { myBuffer.reset(); }

private:
    UT_StringStreamBuffer myBuffer;
};

/// An bi-directional stream object that owns its own string buffer storage.  
class UT_StringStream : public std::iostream
{
public:
    /// Start with an empty string buffer with a given size reservation, if it
    /// is known in advance how much data will be written out. The input stream
    /// will still be empty.
    UT_StringStream(exint reserved_size=-1)
        : myBuffer(std::ios_base::in | std::ios_base::out, nullptr, reserved_size)
        , std::iostream(&myBuffer) {}

    /// Returns the underlying stream buffer object.
    UT_StringStreamBuffer *rdbuf() const { return SYSconst_cast(&myBuffer); }

    /// Returns a read-only reference to the underlying UT_WorkBuffer. 
    const UT_WorkBuffer &str() { return myBuffer.str(); }

    /// Resets the input stream and clears all existing input data.
    void reset() { myBuffer.reset(); }

private:
    UT_StringStreamBuffer myBuffer;
};

// Implementation file
#include "UT_StringStreamImpl.h"

#endif //__UT_StringStream__