You should not use the supplied pointer to write
more than length data points to the buffer
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:
Usually this class will be used in combination with, say, CanonicalIO and AipsIO.
// 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);
Construct from a buffer with the given length. The buffer is readonly and cannot be expanded.
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.
Delete the Memory object. The data buffer is not deleted when constructed with the constructor taking a buffer pointer.
Write the number of bytes. When needed it expands the buffer. An exception is thrown when the buffer is not writable or when buffer expansion fails or is not possible.
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.
Clear the buffer; i.e. set the data length and seek pointer to zero.
Get the buffer containing the data.
The length of the data in the buffer can be obtained using the
length() function.
Get the length of the data in the buffer.
Get the allocated length of the buffer.
Get the expand size (0 = not expandable).
Is the IO stream readable?
Is the IO stream writable?
Is the IO stream seekable?
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.
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.
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.