# 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.
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.
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