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
[edit | edit source]TBank
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]CreateBank
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]Function BankSize( bank:TBank )
Description: Get size of bank
Returns: The size, in bytes, of the bank's internal memory buffer
BankCapacity
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]Function PokeByte( bank:TBank,offset,value )
Description: Poke a byte into a bank
PeekShort
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]Function PokeFloat( bank:TBank,offset,value# )
Description: Poke a float into a bank
Information: A float requires 4 bytes of storage
PeekDouble
[edit | edit source]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
[edit | edit source]Function PokeDouble( bank:TBank,offset,value! )
Description: Poke a double into a bank
Information: A double requires 8 bytes of storage
ReadBank
[edit | edit source]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
[edit | edit source]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