BlitzMax/Modules/Miscellaneous/Banks

From Wikibooks, open books for an open world
Jump to: navigation, search

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]

TBank[edit]

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[edit]

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[edit]

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[edit]

CreateBank[edit]

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]

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]

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]

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]

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]

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]

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]

Function BankSize( bank:TBank )

Description: Get size of bank

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

BankCapacity[edit]

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]

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]

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]

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]

Function PokeByte( bank:TBank,offset,value )

Description: Poke a byte into a bank

PeekShort[edit]

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]

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]

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]

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]

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]

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]

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]

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

Description: Poke a float into a bank

Information: A float requires 4 bytes of storage

PeekDouble[edit]

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]

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

Description: Poke a double into a bank

Information: A double requires 8 bytes of storage

ReadBank[edit]

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]

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