xrb_bitcache.hpp

// ///////////////////////////////////////////////////////////////////////////
// xrb_bitcache.hpp by Victor Dods, created 2005/05/19
// ///////////////////////////////////////////////////////////////////////////
// Unless a different license was explicitly granted in writing by the
// copyright holder (Victor Dods), this software is freely distributable under
// the terms of the GNU General Public License, version 2.  Any works deriving
// from this work must also be released under the GNU GPL.  See the included
// file LICENSE for details.
// ///////////////////////////////////////////////////////////////////////////

#if !defined(_XRB_BITCACHE_HPP_)
#define _XRB_BITCACHE_HPP_

#include "xrb.hpp"

#include "xrb_endian.hpp"
#include "xrb_enums.hpp"

namespace Xrb
{

// for doing bit-packed caching in memory with abstract buffer flushing/renewing
class BitCache
{
public:

    BitCache (Uint32 cache_size_in_bytes, Endian::Endianness endianness);
    virtual ~BitCache ();

    // ///////////////////////////////////////////////////////////////////////
    // state accessors
    // ///////////////////////////////////////////////////////////////////////

    inline Endian::Endianness GetEndianness () const
    {
        return m_endianness;
    }
    inline bool IsOpen () const
    {
        return m_is_open;
    }
    inline IODirection GetIODirection () const
    {
        return m_io_direction;
    }
    bool IsAtEnd () const;
    bool HasFewerThan8BitsLeft () const;
    inline IOError Error () const
    {
        return m_error;
    }

    Uint32 ReadUnsignedBits (Uint32 bit_count);
    void WriteUnsignedBits (Uint32 value, Uint32 bit_count);

    Sint32 ReadSignedBits (Uint32 bit_count);
    void WriteSignedBits (Sint32 value, Uint32 bit_count);

    bool ReadBool ();
    void WriteBool (bool value);

    void Read1ByteWordFromCache (void *destination);
    void Write1ByteWordToCache (void *source);

    void Read2ByteWordFromCache (void *destination);
    void Write2ByteWordToCache (void *source);

    void Read4ByteWordFromCache (void *destination);
    void Write4ByteWordToCache (void *source);

    void Read8ByteWordFromCache (void *destination);
    void Write8ByteWordToCache (void *source);

    void ReadBytes (Uint8 *destination, Uint32 destination_size);
    void WriteBytes (Uint8 const *source, Uint32 source_size);

    Uint32 ReadBufferString (char *destination, Uint32 destination_length);
    // this might need a "bool write_null_char" parameter.
    Uint32 WriteBufferString (char const *source, Uint32 source_length);

    // this makes virtual calls and may not be used in the destructor.
    void FlushWriteCache ();

protected:

    inline void SetError (IOError error) const { m_error = error; }

    // ///////////////////////////////////////////////////////////////////////
    // procedures
    // ///////////////////////////////////////////////////////////////////////

    inline void IncrementCacheByteIndex (Uint32 requested_byte_count)
    {
        ASSERT1(IsCacheBitIndexOnByteBoundary());
        ASSERT1(CacheByteIndex() + requested_byte_count
                <=
                m_next_available_cache_byte_index);
        m_cache_bit_index += requested_byte_count << 3;
    }
    inline void IncrementCacheBitIndex (Uint32 requested_bit_count)
    {
        ASSERT1(m_cache_bit_index + requested_bit_count
                <=
                NextAvailableCacheBitIndex());
        m_cache_bit_index += requested_bit_count;
    }

    inline void EnsureCacheIsOnByteBoundary ()
    {
        // round up to the nearest multiple of 8
        m_cache_bit_index = ((m_cache_bit_index + 7) >> 3) << 3;
    }

    void EnsureReadCacheHasEnoughBitsAvailable (Uint32 requested_bit_count) const;
    void EnsureReadCacheHasEnoughBytesAvailable (Uint32 requested_byte_count) const;

    void EnsureWriteCacheHasEnoughBitsAvailable (Uint32 requested_bit_count) const;
    void EnsureWriteCacheHasEnoughBytesAvailable (Uint32 requested_byte_count) const;

    void OpenForReading ();
    void OpenForWriting ();

    // this makes virtual calls and may not be used in the destructor.
    void Close ();

    virtual Uint32 FlushBytes (
        Uint8 const *bytes_to_flush,
        Uint32 number_of_bytes_to_flush) const = 0;
    virtual Uint32 RenewBytes (
        Uint8 *bytes_to_renew,
        Uint32 number_of_bytes_to_renew) const = 0;

private:

    // ///////////////////////////////////////////////////////////////////////
    // private accessors
    // ///////////////////////////////////////////////////////////////////////

    inline bool IsCacheEmpty () const
    {
        return m_cache_bit_index == 0;
    }
    inline bool IsCacheBitIndexOnByteBoundary () const
    {
        return (m_cache_bit_index & 7) == 0;
    }
    // this is m_cache_bit_index divided by 8, rounded up.
    inline Uint32 UsedCacheByteCount () const
    {
        return (m_cache_bit_index + 7) >> 3;
    }
    inline Uint32 CacheByteIndex () const
    {
        return m_cache_bit_index >> 3;
    }
    inline Uint32 NextAvailableCacheBitIndex () const
    {
        return m_next_available_cache_byte_index << 3;
    }

    // ///////////////////////////////////////////////////////////////////////
    // private modifiers
    // ///////////////////////////////////////////////////////////////////////

    inline void SetIsOpen (bool is_open) { m_is_open = is_open; }
    inline void SetIODirection (IODirection io_direction)
    {
        m_io_direction = io_direction;
    }

    Endian::Endianness m_endianness;
    bool m_is_open;
    IODirection m_io_direction;
    mutable IOError m_error;

    Uint32 const m_working_cache_size_in_bytes;
    Uint32 const m_working_cache_size_in_bits;
    Uint32 const m_actual_cache_size_in_bytes;
    Uint32 const m_actual_cache_size_in_bits;
    mutable Uint8 *m_cache;
    mutable Uint32 m_cache_bit_index;
    mutable Uint32 m_next_available_cache_byte_index;
}; // end of class BitCache

} // end of namespace Xrb

#endif // !defined(_XRB_BITCACHE_HPP_)

---