BRL.Bank
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
Type | Description |
---|---|
TBank | Memory bank |
Functions
Function CreateBank:TBank( size:Int=0 )
Create a bank
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.
Returns
A bank object with an initial size of size bytes
Example
SuperStrict
Local myBank:TBank = CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function CreateStaticBank:TBank( buf:Byte Ptr,size:Int )
Create a bank with existing data
The memory referenced by a static bank is not released when the bank is deleted. A static bank cannot be resized.
Returns
A bank object that references an existing block of memory
Function LoadBank:TBank( url:Object )
Load a bank
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.
Returns
A bank containing the binary contents of url, or null if url could not be opened
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int=0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
SaveBank myBank,"mybank.dat"
Local myNextBank:TBank=LoadBank("mybank.dat")
For Local t:Int = 0 Until BankSize(myNextBank)
Print PeekByte(myNextBank,t)
Next
Function SaveBank:Int( bank:TBank,url:Object )
Save a bank
SaveBank writes it's entire contents to a url. If the url is a file path a new file is created.
Returns
True if successful.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
SaveBank MyBank,"mybank.dat"
Function BankBuf:Byte Ptr( bank:TBank )
Get bank's memory buffer
Please use LockBank and UnlockBank instead of this method.
Returns
A byte pointer to the bank's internal memory buffer
Example
SuperStrict
Local bank:TBank = CreateBank(100)
PokeByte bank, 10, 255
Local bptr:Byte Ptr = BankBuf(bank)
Print PeekByte(bank , 10)
Print bptr[10]
Function LockBank:Byte Ptr( bank:TBank )
Lock a bank's memory block
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.
Returns
A byte pointer to the memory block controlled by the bank.
Function UnlockBank( bank:TBank )
Unlock a bank's memory block
After you have finished with a bank's memory block, you must use UnlockBank to return it to the bank.
Function BankSize:Long( bank:TBank )
Get size of bank
Returns
The size, in bytes, of the bank's internal memory buffer
Example
SuperStrict
Local bank:TBank = CreateBank( Int(10 + Rnd(40)) )
Print "size of the bank is: "+BankSize(bank)
Function BankCapacity:Long( bank:TBank )
Get capacity of bank
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.
Returns
The capacity, in bytes, of the bank's internal memory buffer
Example
SuperStrict
Local bank:TBank = CreateBank( Int(20 + Rnd(40)) )
Print "size of the bank is: "+BankSize(bank)
Print "capacity of the bank is: "+BankCapacity(bank)
Function ResizeBank( bank:TBank,size:Size_T )
Resize a bank
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.
Function CopyBank( src_bank:TBank,src_offset:Size_T,dst_bank:TBank,dst_offset:Size_T,count:Size_T )
Copy bank contents
CopyBank copies count bytes from src_offset in src_bank to dst_offset in dst_bank.
Example
SuperStrict
Local bank:TBank = CreateBank(100)
For Local i:Int = 0 Until 100
PokeByte bank, i ,i
Next
Print "Original Bank Values..."
For Local i:Int = 0 To 10
Print PeekByte(bank , 50 + i)
Next
Local copiedbank:TBank = CreateBank(100)
CopyBank(bank, 50, copiedBank, 0, 10+1)
Print "Copied Bank Values..."
For Local i:Int = 0 To 10
Print PeekByte(CopiedBank , i)
Next
Function PeekByte:Int( bank:TBank,offset:Int )
Peek a byte from a bank
A byte is an unsigned 8 bit value with a range of 0..255.
Returns
The byte value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Next
Print PeekByte(myBank,0)
Print PeekByte(myBank,1)
End
Function PeekByte:Int( bank:TBank,offset:Size_T )
Peek a byte from a bank
A byte is an unsigned 8 bit value with a range of 0..255.
Returns
The byte value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Next
Print PeekByte(myBank,0)
Print PeekByte(myBank,1)
End
Function PokeByte( bank:TBank,offset:Int,value:Int )
Poke a byte into a bank
Example 1
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeByte myBank,0,123
PokeByte myBank,15,234
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Example 2
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeByte myBank,0,$11
PokeShort myBank,1,$1122 ' new address = 0+1=[1]
PokeInt myBank,3,$11223344 ' new address = [1]+2=(3)
PokeLong myBank,7,$1122334455667788 ' new address = (3)+4=7
Function PokeByte( bank:TBank,offset:Size_T,value:Int )
Poke a byte into a bank
Example 1
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeByte myBank,0,123
PokeByte myBank,15,234
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Example 2
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeByte myBank,0,$11
PokeShort myBank,1,$1122 ' new address = 0+1=[1]
PokeInt myBank,3,$11223344 ' new address = [1]+2=(3)
PokeLong myBank,7,$1122334455667788 ' new address = (3)+4=7
Function PeekShort:Int( bank:TBank,offset:Int )
Reads an unsigned short value (2 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A short value should not be read from the last possible byte address of the bank.
Returns
The short value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekShort(myBank,0)
Print PeekShort(myBank,1)
Print PeekShort(myBank,14)
End
Function PeekShort:Int( bank:TBank,offset:Size_T )
Reads an unsigned short value (2 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A short value should not be read from the last possible byte address of the bank.
Returns
The short value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekShort(myBank,0)
Print PeekShort(myBank,1)
Print PeekShort(myBank,14)
End
Function PokeShort( bank:TBank,offset:Int,value:Int )
Writes an unsigned short value (2 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A short value should not be poked at the last possible byte address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeShort myBank,0,256
PokeShort myBank,14,32768+1
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PokeShort( bank:TBank,offset:Size_T,value:Int )
Writes an unsigned short value (2 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A short value should not be poked at the last possible byte address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeShort myBank,0,256
PokeShort myBank,14,32768+1
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PeekInt:Int( bank:TBank,offset:Int )
Reads a signed int value (4 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
An int value should not be read from the last possible byte or short address of the bank.
Returns
The int value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekInt(myBank,0)
Print PeekInt(myBank,1)
Print PeekInt(myBank,12)
Function PeekInt:Int( bank:TBank,offset:Size_T )
Reads a signed int value (4 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
An int value should not be read from the last possible byte or short address of the bank.
Returns
The int value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekInt(myBank,0)
Print PeekInt(myBank,1)
Print PeekInt(myBank,12)
Function PokeInt( bank:TBank,offset:Int,value:Int )
Writes a signed int value (4 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
An int value should not be poked at the last possible byte or short address of the bank.
Example 1
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeInt myBank,0,-10000001
PokeInt myBank,12,31415926
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Example 2
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until 4
PokeInt MyBank,t*4,Int(Rnd($12345678))
Next
Function PokeInt( bank:TBank,offset:Size_T,value:Int )
Writes a signed int value (4 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
An int value should not be poked at the last possible byte or short address of the bank.
Example 1
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeInt myBank,0,-10000001
PokeInt myBank,12,31415926
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Example 2
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until 4
PokeInt MyBank,t*4,Int(Rnd($12345678))
Next
Function PeekLong:Long( bank:TBank,offset:Int )
Reads a signed long value (8 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A long value should not be read from the last possible byte, short or int address of the bank.
Returns
The long integer value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekLong(myBank,0)
Print PeekLong(myBank,1)
Print PeekLong(myBank,8)
Function PeekLong:Long( bank:TBank,offset:Size_T )
Reads a signed long value (8 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A long value should not be read from the last possible byte, short or int address of the bank.
Returns
The long integer value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekLong(myBank,0)
Print PeekLong(myBank,1)
Print PeekLong(myBank,8)
Function PokeLong( bank:TBank,offset:Int,value:Long )
Writes a signed long value (8 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A long value should not be poked at the last possible byte, short or int address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeLong myBank,0,-10000001234567
PokeLong myBank,8,31415926000000
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PokeLong( bank:TBank,offset:Size_T,value:Long )
Writes a signed long value (8 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A long value should not be poked at the last possible byte, short or int address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeLong myBank,0,-10000001234567
PokeLong myBank,8,31415926000000
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PeekFloat:Float( bank:TBank,offset:Int )
Reads a signed float value (4 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A float value should not be read from the last possible byte or short address of the bank.
Returns
The float value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekFloat(myBank,0)
Print PeekFloat(myBank,1)
Print PeekFloat(myBank,12)
End
Function PeekFloat:Float( bank:TBank,offset:Size_T )
Reads a signed float value (4 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A float value should not be read from the last possible byte or short address of the bank.
Returns
The float value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekFloat(myBank,0)
Print PeekFloat(myBank,1)
Print PeekFloat(myBank,12)
End
Function PokeFloat( bank:TBank,offset:Int,value:Float )
Writes a signed float value (4 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A float value should not be poked at the last possible byte or short address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeFloat myBank,0,0.123456
PokeFloat myBank,12,1234.5678
For Local t:Int = 0 ubtil BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PokeFloat( bank:TBank,offset:Size_T,value:Float )
Writes a signed float value (4 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A float value should not be poked at the last possible byte or short address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeFloat myBank,0,0.123456
PokeFloat myBank,12,1234.5678
For Local t:Int = 0 ubtil BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PeekDouble:Double( bank:TBank,offset:Int )
Reads a signed double value (8 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A double value should not be read from the last possible byte, short, int or long address of the bank.
Returns
The double value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekDouble(myBank,0)
Print PeekDouble(myBank,1)
Print PeekDouble(myBank,8)
End
Function PeekDouble:Double( bank:TBank,offset:Size_T )
Reads a signed double value (8 bytes) from a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A double value should not be read from the last possible byte, short, int or long address of the bank.
Returns
The double value at the specified byte offset within the bank
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
For Local t:Int = 0 Until BankSize(myBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Print
Print PeekDouble(myBank,0)
Print PeekDouble(myBank,1)
Print PeekDouble(myBank,8)
End
Function PokeDouble( bank:TBank,offset:Int,value:Double )
Writes a signed double value (8 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A double value should not be poked at the last possible byte, short, int or float address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeDouble myBank,0,123495543.12342345123:Double
PokeDouble myBank,8,121235567.89015678123:Double
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function PokeDouble( bank:TBank,offset:Size_T,value:Double )
Writes a signed double value (8 bytes) into a bank, at a given address.
Take notice not to exceed the boundaries of the bank.
A double value should not be poked at the last possible byte, short, int or float address of the bank.
Example
SuperStrict
Local myBank:TBank=CreateBank(16)
PokeDouble myBank,0,123495543.12342345123:Double
PokeDouble myBank,8,121235567.89015678123:Double
For Local t:Int = 0 Until BankSize(myBank)
Print PeekByte(myBank,t)
Next
Function ReadBank:Long( bank:TBank,stream:TStream,offset:Int,count:Long )
Read bytes from a Stream to a Bank
Returns
The number of bytes successfully read from the Stream
Function ReadBank:Long( bank:TBank,stream:TStream,offset:Size_T,count:Long )
Read bytes from a Stream to a Bank
Returns
The number of bytes successfully read from the Stream
Function WriteBank:Long( bank:TBank,stream:TStream,offset:Int,count:Long )
Write bytes from a Bank To a Stream
Returns
The number of bytes successfully written to the Stream
Example
SuperStrict
Local myBank:TBank=CreateBank(8)
Print "Created Bank..."
For Local t:Int = 0 Until BankSize(MyBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Local bankStream:TStream=WriteStream("mybank.dat")
WriteBank(myBank,bankStream,0,BankSize(myBank))
CloseStream(bankStream)
Local myNextBank:TBank=TBank.Load("mybank.dat")
Print "Loaded Bank..."
For Local t:Int = 0 Until BankSize(MyNextBank)
Print PeekByte(MyNextBank,t)
Next
Function WriteBank:Long( bank:TBank,stream:TStream,offset:Size_T,count:Long )
Write bytes from a Bank to a Stream
Returns
The number of bytes successfully written to the Stream
Example
SuperStrict
Local myBank:TBank=CreateBank(8)
Print "Created Bank..."
For Local t:Int = 0 Until BankSize(MyBank)
PokeByte mybank,t,Int(Rnd(255))
Print PeekByte(myBank,t)
Next
Local bankStream:TStream=WriteStream("mybank.dat")
WriteBank(myBank,bankStream,0,BankSize(myBank))
CloseStream(bankStream)
Local myNextBank:TBank=TBank.Load("mybank.dat")
Print "Loaded Bank..."
For Local t:Int = 0 Until BankSize(MyNextBank)
Print PeekByte(MyNextBank,t)
Next