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 Methods Buf Lock Unlock Size Capacity Resize Read Write PeekByte PokeByte PeekShort PokeShort PeekInt PokeInt PeekLong PokeLong PeekFloat PokeFloat PeekDouble PokeDouble Save Functions Load Create CreateStatic TBank: Methods Buf 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. Lock 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. Unlock 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. Size Method Size() Description: Get a bank's size Returns: The size, in bytes, of the memory block controlled by the bank Capacity Method Capacity() Description: Get capacity of bank Returns: The capacity, in bytes, of the bank's internal memory buffer Resize Method Resize( size ) Description: Resize a bank Read Method Read( stream:TStream,offset,count ) Description: Read bytes from a stream into a bank Write Method Write( stream:TStream,offset,count ) Description: Write bytes in a bank to a stream PeekByte Method PeekByte( offset ) Description: Peek a byte from a bank Returns: The byte value at the specified byte offset within the bank PokeByte Method PokeByte( offset,value ) Description: Poke a byte into a bank PeekShort Method PeekShort( offset ) Description: Peek a short from a bank Returns: The short value at the specified byte offset within the bank PokeShort Method PokeShort( offset,value ) Description: Poke a short into a bank PeekInt Method PeekInt( offset ) Description: Peek an int from a bank Returns: The int value at the specified byte offset within the bank PokeInt Method PokeInt( offset,value ) Description: Poke an int into a bank PeekLong Method PeekLong:Long( offset ) Description: Peek a long from a bank Returns: The long value at the specified byte offset within the bank PokeLong Method PokeLong( offset,value:Long ) Description: Poke a long value into a bank PeekFloat Method PeekFloat#( offset ) Description: Peek a float from a bank Returns: The float value at the specified byte offset within the bank PokeFloat Method PokeFloat( offset,value# ) Description: Poke a float value into a bank PeekDouble Method PeekDouble!( offset ) Description: Peek a double from a bank Returns: The double value at the specified byte offset within the bank PokeDouble Method PokeDouble( offset,value! ) Description: Poke a double value into a bank Save Method Save( url:Object ) Description: Save a bank to a stream Information: Return True if successful, otherwise False. TBank: Functions Load 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. Create Function Create:TBank( size ) Description: Create a bank Returns: A new TBank object with an initial size of size CreateStatic 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