RAMstream

RAMstream 1.2

RAMstream provides a binarystream in RAM. It works as fast as a Memoryblock, but it has the flexibility of a Binarystream

Its size can be changed when needed
You can know its length
You have write and read methods for strings

Download class and sample project
http://www.belle-nuit.com/download/ramstream.sit.hqx

RAMStream works with REALBasic 2.1 or later. It is self-contained and works with both 68k and PowerPC. It should work on Windows, but it hasn't been tested for. However, numbers are always written and read in big endian, like the MemoryBlock does.

You will find a sample application of RAMStreams in the UndoEngine class.

Important changement from 1.1 to 1.2: When you resize the memoryblock or when you write beyond its length, a new memoryblock of the new size is created to store the RAMstreams content. In low memory situations, the creation of the new memoryblock could fail (return nil) and the class would give you a nil object exception without you being able to save the content of the RAMstream.

The new memory handling makes your code savier:

If a Resize method (or a Write method calling Resize), the instance turns into error mode and becomes Read-only.
You can check the occurance of this error with the Error function.
If the RAMstream is read-only, you can still read the memoryblock's content, but you cannot write to it any more.

However, you can clean up your memory by freeing other objects and try to Resize the RAMstream again manually. If you succeed, the instance leaves error mode.
This new protection has an important consequence. If you write to the RAMstream and are in doubt of low memory situation, you may want to check it's error state to assure that is has really written to the RAMstream.

Important changement from 1.0 to 1.1 or 1.2: The position is not a property anymore, but a Function for reading and a Sub for setting. If you have used the position-property in assignments before, you have to change your code from "r.position=pos" to "r.position(pos)".

Methods

Function RAMstream(size as integer, [chunk as integer])

Set the size to a size you are more or less sure to use. The RAMstream will be resized automatically, when you write over the defined size.The optional chunk parameter sets the minimal increase every time the RAMstream is going to be resized. You may set a chunk size, if your RAMstream is likely to increase regularly.

Function Resize(size as integer)

Manual resize of the RAMstream.

Function EOF() As boolean

Function Error() As boolean

If the Resize method or any of the write methods which call implicitely a Resize fail because of lack of application memory, the instance turns read only to protect its memory content and you from a nil object exception. The Error function returns true, if a resize method failed. You may check for error before writing to the memoryblock.

Function Length() as boolean

Function Position() as integer

Sub Position(pos as integer)

Gets/sets the position in the RAMstream. The position is not a property anymore, but a Function for reading and a Sub for setting. If you have used in version 1.0 the position-property in assignments before, you have to change your code from "r.position=pos" to "r.position(pos)".

If you set the position less than 0, it will be set to 0 on your next Read or Write statement. If you set it bigger than Length-1, it will be set to Length when you write and you will get an error when you try to read (OutOfBoundsException).

Function Read(count as integer) as string

Function ReadAll() as string

Returns the whole RAMstream as a string. ReadAll does not change the position.

Function ReadBoolean() as boolean

A Boolean is 1 byte long.

Function ReadByte() as integer

Function ReadColor() as color

A Color is 4 byte long.

Function ReadLong() as integer

Function ReadLongString() as string

A long string is a REALbasic string which knows its size. It has an integer as header and the text itself as footer. A LongString is 4+len(string) bytes long.

Function ReadPString() as string

Function ReadSingle() as integer

Function ReadPString() as string

Function ReadShort() as integer

The Read-Functions create a Out-of-Bounds-Expception if you read over the size of the RAMStream.

Method Write(data as string)

Method WriteBoolean(value as boolean)

Method WriteByte(value as integer)

Method WriteColor(value as color)

Method WriteLong(value as integer)

Method WriteLongString(text as string)

Method WriteSingle(value as double)

Method WritePString(text as string)

Method WriteShort(value as integer)

Function About() as string

Returns an about-string of the class.

Function Methods() as string

Returns a string with the definitions of the methods.

Function Properties() as string

Returns a string with the definitions of the properties.

Function Version() as string

Returns the current version of the class.

Properties

The class has no public properties. The position-property ion version 1.0 has become a method.

Technical comments

The class uses an internal memoryblock. When there is a need for resizing, a new memoryblock is created and the data of the old memoryblock is copied to the new memoryblock.

At this moment, there is no ReadDouble and WriteDouble, as the memoryblock does not provide one.

The class is not double-byte savy.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Comments please to matti@belle-nuit.com

The latest version is available at http//www.belle-nuit.com/

History

8.6.00 RAMStream 1.2: Add Error-method ans protection (read-only). Released as open source.

6.5.00 RAMStream 1.1: Add methods to read and write Booleans, Colors and LongStrings. Add a ReadAll method. Added the omitted ReadPstring. Position is now a method and not a property any more.

22.4.00 Release RAMstream 1.0