BlitzMax/Modules/Miscellaneous/Banks

A bank object encapsulates a block of memory you can use to store arbitrary data.

Banks are useful for storing data that is of no fixed type - for example, the contents of a binary file.

To create a bank, use the CreateBank command.

To write data to a bank, use one of 'Poke' style commands, such as PokeByte.

To read data from a bank, use one of the 'Peek' style commands, such as PeekByte.

In addition, banks can be loaded or saved using LoadBank or SaveBank.

=Types=

TBank
Memory bank


 * Buf
 * Lock
 * Unlock
 * Size
 * Capacity
 * Resize
 * Read
 * Write
 * PeekByte
 * PokeByte
 * PeekShort
 * PokeShort
 * PeekInt
 * PokeInt
 * PeekLong
 * PokeLong
 * PeekFloat
 * PokeFloat
 * PeekDouble
 * PokeDouble
 * Save


 * Load
 * Create
 * CreateStatic

TBank: Methods
Method Buf:Byte Ptr

Description: Get a bank's memory pointer

Returns: A byte pointer to the memory block controlled by the bank

Information: Please use Lock and Unlock instead of this method.

Method Lock:Byte Ptr

Description: Lock a bank's memory block

Returns: A byte pointer to the memory block controlled by the bank

Information: While locked, a bank cannot be resized.

After you have finished with a bank's memory block, you must use Unlock to return it to the bank.

Method Unlock

Description: Unlock a bank's memory pointer

Information: After you have finished with a bank's memory block, you must use Unlock to return it to the bank.

Method Size

Description: Get a bank's size

Returns: The size, in bytes, of the memory block controlled by the bank

Method Capacity

Description: Get capacity of bank

Returns: The capacity, in bytes, of the bank's internal memory buffer

Method Resize( size )

Description: Resize a bank

Method Read( stream:TStream,offset,count )

Description: Read bytes from a stream into a bank

Method Write( stream:TStream,offset,count )

Description: Write bytes in a bank to a stream

Method PeekByte( offset )

Description: Peek a byte from a bank

Returns: The byte value at the specified byte offset within the bank

Method PokeByte( offset,value )

Description: Poke a byte into a bank

Method PeekShort( offset )

Description: Peek a short from a bank

Returns: The short value at the specified byte offset within the bank

Method PokeShort( offset,value )

Description: Poke a short into a bank

Method PeekInt( offset )

Description: Peek an int from a bank

Returns: The int value at the specified byte offset within the bank

Method PokeInt( offset,value )

Description: Poke an int into a bank

Method PeekLong:Long( offset )

Description: Peek a long from a bank

Returns: The long value at the specified byte offset within the bank

Method PokeLong( offset,value:Long )

Description: Poke a long value into a bank

Method PeekFloat#( offset )

Description: Peek a float from a bank

Returns: The float value at the specified byte offset within the bank

Method PokeFloat( offset,value# )

Description: Poke a float value into a bank

Method PeekDouble!( offset )

Description: Peek a double from a bank

Returns: The double value at the specified byte offset within the bank

Method PokeDouble( offset,value! )

Description: Poke a double value into a bank

Method Save( url:Object )

Description: Save a bank to a stream

Information: Return True if successful, otherwise False.

TBank: Functions
Function Load:TBank( url:Object )

Description: Load a bank from a stream

Returns: A new TBank object

Information: Returns a new TBank object if successful, otherwise Null.

Function Create:TBank( size )

Description: Create a bank

Returns: A new TBank object with an initial size of size

Function CreateStatic:TBank( buf:Byte Ptr,size )

Description: Create a bank from an existing block of memory

=Functions=

CreateBank
Function CreateBank:TBank( size=0 )

Description: Create a bank

Returns: A bank object with an initial size of size bytes

Information: CreateBank creates a Bank allocating a specified amount of memory that can be used for storage of binary data using the various Poke and Peek commands.

Comment: Banks are blocks of memory assigned to a TBank, they are assigned like this.

Global MyVar:TBank = CreateBank( SizeInBytes )

This will create a bank of SizeInBytes and store the pointer to it in MyVar.

Banks are brilliant for conversion work converting between types and compression techniques, for example. Function LongToStr:String( Value:Long ) Local TempBank:TBank = CreateBank( 8 ) ' On eight bytes for the long (ints are 4 bytes) Local TempString:String = "" PokeLong( TempBank,0,Value ) ' Poke Value into TempBank at offset 0, the first byte for the eight bytes of the long value For Li:Int = 0 To 7 TempString :+ Chr( PeekByte( TempBank,Li ) ) ' Read the bytes from the bank Next Return TempString End Function

This simple function converts a long int to an eight byte representation of it. This is good for networking systems, etc. so instead of sending 640000000000 it would send just eight bytes. There are other uses for banks, their uses are seemingly endless.

CreateStaticBank
Function CreateStaticBank:TBank( buf:Byte Ptr,size )

Description: Create a bank with existing data

Returns: A bank object that references an existing block of memory

Information: The memory referenced by a static bank is not released when the bank is deleted. A static bank cannot be resized.

LoadBank
Function LoadBank:TBank( url:Object )

Description: Load a bank

Returns: A bank containing the binary contents of url, or null if url could not be opened

Information: LoadBank reads the entire contents of a binary file from a specified url into a newly created bank with a size matching that of the file.

SaveBank
Function SaveBank( bank:TBank,url:Object )

Description: Save a bank

Returns: True if successful.

Information: SaveBank writes it's entire contents to a url. If the url is a file path a new file is created.

BankBuf
Function BankBuf:Byte Ptr( bank:TBank )

Description: Get bank's memory buffer

Returns: A byte pointer to the bank's internal memory buffer

Information: Please use LockBank and UnlockBank instead of this method.

LockBank
Function LockBank:Byte Ptr( bank:TBank )

Description: Lock a bank's memory block

Returns: A byte pointer to the memory block controlled by the bank.

Information: While locked, a bank cannot be resized.

After you have finished with a bank's memory block, you must use UnlockBank to return it to the bank.

UnlockBank
Function UnlockBank( bank:TBank )

Description: Unlock a bank's memory block

Information: After you have finished with a bank's memory block, you must use UnlockBank to return it to the bank.

BankSize
Function BankSize( bank:TBank )

Description: Get size of bank

Returns: The size, in bytes, of the bank's internal memory buffer

BankCapacity
Function BankCapacity( bank:TBank )

Description: Get capacity of bank

Returns: The capacity, in bytes, of the bank's internal memory buffer

Information: The capacity of a bank is the size limit before a bank must allocate more memory due to a resize. Bank capacity may be increased due to a call to ResizeBank by either 50% or the requested amount, whichever is greater. Capacity never decreases.

ResizeBank
Function ResizeBank( bank:TBank,size )

Description: Resize a bank

Information: ResizeBank modifies the size limit of a bank. This may cause memory to be allocated if the requested size is greater than the bank's current capacity, see BankCapacity for more information.

CopyBank
Function CopyBank( src_bank:TBank,src_offset,dst_bank:TBank,dst_offset,count )

Description: Copy bank contents

Information: CopyBank copies count bytes from src_offset in src_bank to dst_offset in dst_bank.

PeekByte
Function PeekByte( bank:TBank,offset )

Description: Peek a byte from a bank

Returns: The byte value at the specified byte offset within the bank

Information: A byte is an unsigned 8 bit value with a range of 0..255.

PokeByte
Function PokeByte( bank:TBank,offset,value )

Description: Poke a byte into a bank

PeekShort
Function PeekShort( bank:TBank,offset )

Description: Peek a short from a bank

Returns: The short value at the specified byte offset within the bank

Information: A short is an unsigned 16 bit (2 bytes) value with a range of 0..65535.

PokeShort
Function PokeShort( bank:TBank,offset,value )

Description: Poke a short into a bank

Information: An short is an unsigned 16 bit value that requires 2 bytes of storage.

PeekInt
Function PeekInt( bank:TBank,offset )

Description: Peek an int from a bank

Returns: The int value at the specified byte offset within the bank

Information: An int is a signed 32 bit value (4 bytes).

PokeInt
Function PokeInt( bank:TBank,offset,value )

Description: Poke an int into a bank

Information: An int is a signed 32 bit value that requires 4 bytes of storage.

PeekLong
Function PeekLong:Long( bank:TBank,offset )

Description: Peek a long integer from a bank

Returns: The long integer value at the specified byte offset within the bank

Information: A long is a 64 bit integer that requires 8 bytes of memory.

PokeLong
Function PokeLong( bank:TBank,offset,value:Long )

Description: Poke a long integer int into a bank

Information: A long is a 64 bit integer that requires 8 bytes of storage.

PeekFloat
Function PeekFloat#( bank:TBank,offset )

Description: Peek a float from a bank

Returns: The float value at the specified byte offset within the bank

Information: A float requires 4 bytes of storage

PokeFloat
Function PokeFloat( bank:TBank,offset,value# )

Description: Poke a float into a bank

Information: A float requires 4 bytes of storage

PeekDouble
Function PeekDouble!( bank:TBank,offset )

Description: Peek a double from a bank

Returns: The double value at the specified byte offset within the bank

Information: A double requires 8 bytes of storage

PokeDouble
Function PokeDouble( bank:TBank,offset,value! )

Description: Poke a double into a bank

Information: A double requires 8 bytes of storage

ReadBank
Function ReadBank( bank:TBank,stream:TStream,offset,count )

Description: Read bytes from a Stream to a Bank

Returns: The number of bytes successfully read from the Stream

WriteBank
Function WriteBank( bank:TBank,stream:TStream,offset,count )

Description: Write bytes from a Bank to a Stream

Returns: The number of bytes successfully written to the Stream