Class for IO to a memory buffer. More...

#include <MemoryIO.h>

Inheritance diagram for casa::MemoryIO:

Public Member Functions
	MemoryIO (uInt64 initialSize=65536, uInt64 expandSize=32768)
	Construct a dynamic object with the given initial length.
	MemoryIO (const void *buffer, uInt64 size)
	Construct from a buffer with the given length.
	MemoryIO (void *buffer, uInt64 size, ByteIO::OpenOption, uInt64 expandSize=0, Bool canDelete=False)
	Construct from the given buffer with the given length.
	~MemoryIO ()
	Delete the Memory object.
virtual void	write (uInt size, const void *buf)
	Write the number of bytes.
virtual Int	read (uInt size, void *buf, Bool throwException=True)
	Read `size` bytes from the memory buffer.
void	clear ()
	Clear the buffer; i.e.
const uChar *	getBuffer () const
	Get the buffer containing the data.
virtual Int64	length ()
	Get the length of the data in the buffer.
uInt64	allocated () const
	Get the allocated length of the buffer.
uInt64	expandSize () const
	Get the expand size (0 = not expandable).
virtual Bool	isReadable () const
	Is the IO stream readable?
virtual Bool	isWritable () const
	Is the IO stream writable?
virtual Bool	isSeekable () const
	Is the IO stream seekable?
uChar *	setBuffer (uInt64 length)
	resize the internal buffer (if necessary) so that it is big enough to hold the specified number of bytes.
void	setUsed (uInt64 bytesUsed)
	tell the MemoryIO object how much of its internal buffer is valid data.
Private Member Functions
	MemoryIO (const MemoryIO &that)
MemoryIO &	operator= (const MemoryIO &that)
virtual Int64	doSeek (Int64 offset, ByteIO::SeekOption)
	Reset the position pointer to the given value.
Bool	expand (uInt64 minSize)
Private Attributes
uChar *	itsBuffer
Int64	itsAlloc
Int64	itsExpandSize
Int64	itsUsed
Int64	itsPosition
Bool	itsReadable
Bool	itsWritable
Bool	itsCanDelete

Detailed Description

Class for IO to a memory buffer.

Intended use:

Public interface

 <h3>Review Status</h3><dl><dt>Reviewed By:<dd>Friso Olnon<dt>Date Reviewed:<dd>1996/11/06<dt>Test programs:<dd>tByteIO</dl>

Prerequisite

ByteIO

Synopsis

This class is doing IO in a buffer in memory. It is part of the entire IO framework. It can for instance be used to store data in canonical format in a memory string and obtain it later.

The memory buffer can be dynamic, so it will be expanded when needed. This is done by allocating a larger buffer, copy the contents and throw the old buffer away.
The memory buffer can also be static to be sure that the pointer to the buffer will not change. The expand size determines if the memory buffer is static or dynamic. An expand size zero indicates a static buffer.

The memory buffer is seekable and readable. It depends on the constructor whether it is writable.

There are several ways in which the buffer can be created/passed:

Dynamic by passing an initial size and an expand size. However, an expand size zero can be used to assure that no more data is written than fits in the initial buffer (so once the buffer is created it gets static). In this way the buffer is readable and writable.
Static by passing a const buffer and its length. In this way the buffer is not writable.
Dynamic or static by passing a non-const buffer, its length, and an expand size (zero = static, >0 = dynamic) . The OpenOption indicates whether the buffer will be writable. Only for ByteIO::Old it will not be writable. The OpenOption also determines the initial seek position. Usually it is 0, but for ByteIO::Append it is the end of the buffer.

The user can obtain a pointer to the buffer to extract the stored data from it. The length of the data can also be obtained.

Usually this class will be used in combination with, say, CanonicalIO and AipsIO.

Example

       // Create dynamic (expandable) memory buffer of length 100.
       // Use that as the sink of RawIO in AipsIO.
       MemoryIO membuf (100);
       RawIO rawio (&membuf);
       AipsIO stream (&rawio);
       // Write values.
       stream << (Int)10;
       stream << True;
       // Seek to beginning of buffer and read data in.
       stream.setpos (0);
       Int vali;
       Bool valb;
       stream >> vali >> valb;
   
       // One can obtain the buffer and its length and use it later.
       // (e.g. to write it in a non-AipsIO file).
       uChar* bufptr = membuf.getBuffer();
       uInt64 length = membuf.length();
   
       // It can also used to construct another MemoryIO object from it.
       // The following memory buffer is static and readonly.
       MemoryIO membuf2 (bufptr, length);
       membuf2.read (sizeof(vali), vali);
       membuf2.read (sizeof(valb), valb);

Motivation

Make it possible to do IO in a memory buffer. The first implementation used strstreambuf from the iostream package. However, that did not allow seeking and it was hard to get the length.

Definition at line 124 of file MemoryIO.h.

Constructor & Destructor Documentation

casa::MemoryIO::MemoryIO	(	uInt64	initialSize = `65536`,
		uInt64	expandSize = `32768`
	)		`[explicit]`

Construct a dynamic object with the given initial length.

casa::MemoryIO::MemoryIO	(	const void *	buffer,
		uInt64	size
	)

Construct from a buffer with the given length.

The buffer is readonly and cannot be expanded.

casa::MemoryIO::MemoryIO	(	void *	buffer,
		uInt64	size,
		ByteIO::OpenOption	,
		uInt64	expandSize = `0`,
		Bool	canDelete = `False`
	)

Construct from the given buffer with the given length.

The Byte::Option determines how the buffer will be used. The seek pointer is set to the beginning of the buffer, unless told otherwise below.

New, NewNoReplace and Scratch: The buffer is empty and is read/write.
Old: The buffer contains size bytes and is readonly.
Update, Delete: The buffer contains size bytes and is read/write.
Append: The buffer contains size bytes and is read/write. The seek pointer is set to the end of the buffer.

When the buffer is writable, it will be expanded if needed. This means that buffer does not point to the data anymore. However, when expandSize==0, the buffer cannot be expanded and the pointer is always valid.
When canDelete is True, buffer expansion means that the old buffer gets deleted.

casa::MemoryIO::~MemoryIO ( )

Delete the Memory object.

The data buffer is not deleted when constructed with the constructor taking a buffer pointer.

casa::MemoryIO::MemoryIO ( const MemoryIO & that ) [private]

Member Function Documentation

uInt64 casa::MemoryIO::allocated ( ) const [inline]

Get the allocated length of the buffer.

Definition at line 263 of file MemoryIO.h.

References itsAlloc.

void casa::MemoryIO::clear ( ) [inline]

Clear the buffer; i.e.

set the data length and seek pointer to zero.

Definition at line 255 of file MemoryIO.h.

References itsPosition, and itsUsed.

virtual Int64 casa::MemoryIO::doSeek	(	Int64	offset,
		ByteIO::SeekOption
	)		`[private, virtual]`

Reset the position pointer to the given value.

It returns the new position. An exception is thrown when seeking before the start of the buffer or when seeking past the end of a readonly buffer. When seeking past the end of a writable buffer, the required amount of bytes is added and initialized to zero.

Implements casa::ByteIO.

Bool casa::MemoryIO::expand ( uInt64 minSize ) [private]

uInt64 casa::MemoryIO::expandSize ( ) const [inline]

Get the expand size (0 = not expandable).

Definition at line 267 of file MemoryIO.h.

References itsExpandSize.

const uChar * casa::MemoryIO::getBuffer ( ) const [inline]

Get the buffer containing the data.

The length of the data in the buffer can be obtained using the length() function.

Definition at line 259 of file MemoryIO.h.

References itsBuffer.

virtual Bool casa::MemoryIO::isReadable ( ) const [virtual]

Is the IO stream readable?

Implements casa::ByteIO.

virtual Bool casa::MemoryIO::isSeekable ( ) const [virtual]

Is the IO stream seekable?

Implements casa::ByteIO.

virtual Bool casa::MemoryIO::isWritable ( ) const [virtual]

Is the IO stream writable?

Implements casa::ByteIO.

virtual Int64 casa::MemoryIO::length ( ) [virtual]

Get the length of the data in the buffer.

Implements casa::ByteIO.

MemoryIO& casa::MemoryIO::operator= ( const MemoryIO & that ) [private]

virtual Int casa::MemoryIO::read	(	uInt	size,
		void *	buf,
		Bool	throwException = `True`
	)		`[virtual]`

Read size bytes from the memory buffer.

Returns the number of bytes actually read. Will throw an Exception (AipsError) if the requested number of bytes could not be read unless throwException is set to False. Will always throw an exception if the buffer is not readable or the buffer pointer is at an invalid position.

Implements casa::ByteIO.

uChar* casa::MemoryIO::setBuffer ( uInt64 length )

resize the internal buffer (if necessary) so that it is big enough to hold the specified number of bytes.

Returns a non-const pointer to the buffer that can be used to write up to the specified number of bytes into the buffer. If less data is written into the buffer then the setUsed member funtion should be used to indicate how much of the buffer is valid. Throws an exception if the MemoryIO object is not writable or if it needs to increase the size of the internal buffer and the MemoryIO object is not expandable.
Warning: You should not use the supplied pointer to write more than length data points to the buffer

void casa::MemoryIO::setUsed ( uInt64 bytesUsed )

tell the MemoryIO object how much of its internal buffer is valid data.

You only need to use this function if you are directly writing to the buffer using the pointer returned by the non-const getBuffer function. This function throws an exception if the number of bytes used is greater than the number allocated or if the MemoryIO object is not writeable.