Bank module

BlitzMax Forums/BlitzMax Module Tweaks/Bank module

Bot Builder

(Posted 2004) [#1]

Ok, I made the bank module help much more informative(IMHO), as well as 2 extra methods/functions. I also implemented an intelligent autoresize system that is by default off and can be turned on. (described in help for resizebank).

Strict

Rem
bbdoc: Banks
End Rem
Module BRL.Bank

ModuleInfo "Version: 1.01"
ModuleInfo "Author: Mark Sibly"
ModuleInfo "License: Blitz Shared Source Code"
ModuleInfo "Copyright: Blitz Research Ltd"
ModuleInfo "Modserver: BRL"

Import BRL.Stream

Type TBank

	Field _buf:Byte Ptr,_size,_capacity
	Field AutoResizeLimit:Int=0,ResizeIncrement=100			'Auto Resize added by bot builder
	
	Method Delete()
		If _capacity>=0 MemFree _buf,_capacity
	End Method

	Method Buf:Byte Ptr()
		Return _buf
	End Method

	Method Size()
		Return _size
	End Method

	Method Capacity()
		Return _capacity
	End Method

	Method Resize( size )
		Assert _capacity>=0 Else "Static banks cannot be resized"
		If size>_capacity
			Local n=_capacity*3/2
			If n<size n=size
			Local tmp:Byte Ptr=MemAlloc(n)
			MemCopy tmp,_buf,_size
			MemFree _buf,_capacity
			_capacity=n
			_buf=tmp
		EndIf
		_size=size
	End Method

	Method PeekByte( offset )
		Assert offset>=0 And offset<_size Else "Illegal bank offset"
		Return _buf[offset]
	End Method

	Method PokeByte( offset,value )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size Else "Illegal bank offset"
		Else
			If offset>=_size Then
				Assert offset-_size<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+1+ResizeIncrement)
			EndIf
		EndIf
		_buf[offset]=value
	End Method

	Method PeekShort( offset )
		Assert offset>=0 And offset<_size-1 Else "Illegal bank offset"
		Return (Short Ptr(_buf+offset))[0]
	End Method

	Method PokeShort( offset,value )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-1 Else "Illegal bank offset"
		Else
			If offset>=_size-1 Then
				Assert offset-_size+1<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+2+ResizeIncrement)
			EndIf
		EndIf
		(Short Ptr(_buf+offset))[0]=value
	End Method

	Method PeekInt( offset )
		Assert offset>=0 And offset<_size-3 Else "Illegal bank offset"
		Return (Int Ptr(_buf+offset))[0]
	End Method

	Method PokeInt( offset,value )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-3 Else "Illegal bank offset"
		Else
			If offset>=_size-3 Then
				Assert offset-_size+3<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+4+ResizeIncrement)
			EndIf
		EndIf
		(Int Ptr(_buf+offset))[0]=value
	End Method

	Method PeekLong:Long( offset )
		Assert offset>=0 And offset<_size-7 Else "Illegal bank offset"
		Return (Long Ptr(_buf+offset))[0]
	End Method

	Method PokeLong( offset,value:Long )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-7 Else "Illegal bank offset"
		Else
			If offset>=_size-7 Then
				Assert offset-_size+7<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+8+ResizeIncrement)
			EndIf
		EndIf
		(Long Ptr(_buf+offset))[0]=value
	End Method
	
	Method PeekFloat#( offset )
		Assert offset>=0 And offset<_size-3 Else "Illegal bank offset"
		Return (Float Ptr(_buf+offset))[0]
	End Method

	Method PokeFloat( offset,value# )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-3 Else "Illegal bank offset"
		Else
			If offset>=_size-3 Then
				Assert offset-_size+3<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+4+ResizeIncrement)
			EndIf
		EndIf
		(Float Ptr(_buf+offset))[0]=value
	End Method

	Method PeekDouble!( offset )
		Assert offset>=0 And offset<_size-7 Else "Illegal bank offset"
		Return (Double Ptr(_buf+offset))[0]
	End Method

	Method PokeDouble( offset,value! )
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-7 Else "Illegal bank offset"
		Else
			If offset>=_size-7 Then
				Assert offset-_size+7<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+8+ResizeIncrement)
			EndIf
		EndIf
		(Double Ptr(_buf+offset))[0]=value
	End Method

	Method PeekString$(offset)						'by bot builder
		Assert offset>=0 And offset<_size Else "Illegal bank offset"
		Local l=(Int Ptr(_buf+offset))[0],ret$
		For Local i=0 Until l
			ret$:+Chr$((Short Ptr(_buf+offset+4+i*2))[0])
		Next
		Return ret
	End Method

	Method PokeString(offset,Value$)				'By bot builder
		Assert offset>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert offset<_size-3-Value.Length*2 Else "Illegal bank offset"
		Else
			If offset>=_size-3-Value.Length*2 Then
				Assert offset-_size+3+Value.Length*2<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(offset+4+Value.Length*2+ResizeIncrement)
			EndIf
		EndIf
		(Int Ptr(_buf+offset))[0]=Value.Length
		For Local i=0 Until Value.Length
			(Short Ptr(_buf+offset+4+2*i))[0]=Value[i]
		Next
	EndMethod

	Method PeekBit:Byte(ByteIndex,BitIndex)			'By bot builder
		Assert BitIndex>=0 And BitIndex<8 Else "Illegal bit index"
		Assert ByteIndex>=0 And ByteIndex<_size Else "Illegal bank offset"
		Return (_buf[ByteIndex]&(1 Shl Bitindex)) Shr (bitIndex)
	End Method

	Method PokeBit(ByteIndex,BitIndex,value:Byte)	'By bot builder (I would overload this with one accepting a bit index param, but sadly no overloading :(
		Assert BitIndex>=0 And BitIndex<8 Else "Illegal bit index"
		Assert ByteIndex>=0 Else "Illegal bank offset"
		If AutoResizeLimit=0|_capacity=-1 Then
			Assert ByteIndex<_size Else "Illegal bank offset"
		Else
			If ByteIndex>=_size Then
				Assert ByteIndex-_size<AutoResizeLimit Else "Illegal Bank offset, even farther off than AutoResizeLimit. Make sure you aren't mixing up parameters."
				Resize(ByteIndex+1+ResizeIncrement)
			EndIf
		EndIf
		Local BitValue=1 Shl Bitindex
		If Value Then
			If _buf[ByteIndex]&BitValue=0 Then _buf[ByteIndex]=_buf[ByteIndex]|BitValue
		Else
			If _buf[ByteIndex]&BitValue Then _buf[ByteIndex]=_buf[ByteIndex]|~bitValue
		EndIf
	End Method

	Method Save( url:Object )
		Local stream:TStream=WriteStream( url )
		If Not stream Return
		Local n=stream.WriteBytes( _buf,_size )
		stream.Close
		Return n=_size
	End Method

	Function Load:TBank( url:Object )
		Local stream:TStream=ReadStream( url )
		If Not stream Return
		Local data:Byte[]=LoadStream( stream )
		Local bank:TBank=Create(Len(data))
		MemCopy bank.Buf(),data,Len(data)
		stream.Close
		Return bank
	End Function

	Function Create:TBank( size )
		Assert size>=0 Else "Illegal bank size"
		Local bank:TBank=New TBank
		bank._buf=MemAlloc( size )
		bank._size=size
		bank._capacity=size
		Return bank
	End Function
	
	Function CreateStatic:TBank( buf:Byte Ptr,size )
		Assert size>=0 Else "Illegal bank size"
		Local bank:TBank=New TBank
		bank._buf=buf
		bank._size=size
		bank._capacity=-1
		Return bank
	End Function
	
	Method Read( stream:TStream,offset,count )
		Assert offset>=0 And offset<=_size-count Else "Illegal bank offset"
		Return stream.ReadBytes(_buf+offset,count)
	End Method

	Method Write( stream:TStream,offset,count )
		Assert offset>=0 And offset<=_size-count Else "Illegal bank offset"
		Return stream.WriteBytes(_buf+offset,count)
	End Method

End Type

Rem
bbdoc: Creates a bank
returns: A bank object with an initial size of @size.
about:
A bank is just a buffer of memory accessible by some simple functions.  You can either use integer pointers to reference the banks, or use the TBank type and either call the functions or use the type's methods.
End Rem
Function CreateBank:TBank( size=0 )
	Return TBank.Create( size )
End Function

Rem
bbdoc: Creates a bank with existing data.
returns: A bank object that references an existing block of memory
about:
A static bank just references a block of memory, allowing you to use peek and poke functions on it.
Due to this, if the data changes, the bank's data changes, and if the bank is freed the data is not.
End Rem
Function CreateStaticBank:TBank( buf:Byte Ptr,size )
	Return TBank.CreateStatic( buf,size )
End Function

Rem
bbdoc: Loads a bank
returns: A bank containing the binary contents of @url, or null if @url could not be opened
End Rem
Function LoadBank:TBank( url:Object )
	Return TBank.Load( url )
End Function

Rem
bbdoc: Saves a bank
returns: True if successful
End Rem
Function SaveBank( bank:TBank,url:Object )
	Return bank.Save( url )
End Function

Rem
bbdoc: Gets a bank's memory buffer
returns: A byte pointer to the bank's internal memory buffer
End Rem
Function BankBuf:Byte Ptr( bank:TBank )
	Return bank.Buf()
End Function

Rem
bbdoc: Gets size of a bank
returns: The size, in bytes, of the bank's internal memory buffer
End Rem
Function BankSize( bank:TBank )
	Return bank.Size()
End Function

Rem
bbdoc: Returns the capacity of bank
returns: The capacity, in bytes, of the bank's internal memory buffer
about:
This only differs from Size in that when capacity is -1, the array is static, or unchanging.
End Rem
Function BankCapacity( bank:TBank )
	Return bank.Capacity()
End Function

Rem
bbdoc: Resizes a bank
about:
It should be noted that this function involves remaking the entire memory buffer, copying the data, and freeing the old one, in all, very slooow.
So if you frequently resize, it is advised that you set the AutoResizeLimit field of the TBank to a positive value, perhaps 100, so that this module will handle resizeing for you. You won't even have to call resize anymore, as whenever you store memory outside of the banks space, it will create the space, plus a hundred bytes of extra space (well, a hundred is the default, set ResizeIncrement for different values).  The distance away from the bounds of the bank you can write is limited so that if you mix up the parameters and pass the value as an offset, you wont crash the computer.  This way, you have to write 100 bytes (12 longs, 12 doubles, 25 floats, 25 ints, 50 shorts, or 48 charachter long string) before it resizes again, leading to much faser execution.  A little bit of memory for alot more speed.  For big banks you can set increment up a bit and for little banks you can set it down.  
End Rem
Function ResizeBank( bank:TBank,size )
	bank.Resize size
End Function

Rem
bbdoc: Copys a bank's contents from one bank to another.
End Rem
Function CopyBank( src_bank:TBank,src_offset,dst_bank:TBank,dst_offset,count )
	Assert..
	count>=0 And..
	src_offset>=0 And..
	dst_offset>=0 And..
	src_offset+count<=src_bank.Size() And..
	dst_offset+count<=dst_bank.size() Else "Illegal range for CopyBank"
	MemCopy( dst_bank.Buf()+dst_offset,src_bank.Buf()+src_offset,count )
End Function

Rem
bbdoc: Peeks a byte from a bank.
returns: The byte value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekByte( bank:TBank,offset )
	Return bank.PeekByte( offset )
End Function

Rem
bbdoc: Pokes a byte into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeByte( bank:TBank,offset,value )
	bank.PokeByte offset,value
End Function

Rem
bbdoc: Peeks a short from a bank
returns: The short value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekShort( bank:TBank,offset )
	Return bank.PeekShort( offset )
End Function

Rem
bbdoc: Pokes a short into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeShort( bank:TBank,offset,value )
	bank.PokeShort offset,value
End Function

Rem
bbdoc: Peeks an int from a bank
returns: The int value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekInt( bank:TBank,offset )
	Return bank.PeekInt( offset )
End Function

Rem
bbdoc: Pokes an int into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeInt( bank:TBank,offset,value )
	bank.PokeInt offset,value
EndFunction


Rem
bbdoc: Peeks a long integer from a bank
returns: The int value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekLong:Long( bank:TBank,offset )
	Return bank.PeekLong( offset )
End Function

Rem
bbdoc: Pokes a long integer int into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeLong( bank:TBank,offset,value:Long )
	bank.PokeLong offset,value
End Function

Rem
bbdoc: Peeks a float from a bank
returns: The float value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekFloat#( bank:TBank,offset )
	Return bank.PeekFloat( offset )
End Function

Rem
bbdoc: Pokes a float into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeFloat( bank:TBank,offset,value# )
	bank.PokeFloat offset,value
End Function

Rem
bbdoc: Peeks a double from a bank
returns: The double value at the specified byte offset within the bank
about:
This gets the value of the memory at an offset in the bank.
End Rem
Function PeekDouble!( bank:TBank,offset )
	Return bank.PeekDouble( offset )
End Function

Rem
bbdoc: Pokes a double into a bank
about:
This sets the value of the memory at an offset in the bank.
End Rem
Function PokeDouble( bank:TBank,offset,value! )
	bank.PokeDouble offset,value
End Function

Rem
bbdoc: Peeks a string from a bank
returns: The string value at the specified byte offset within the bank.
about:
This gets the value of the memory at an offset in the bank.
Strings are stored as an integer (4 bytes) defining length followed by a series of shorts (2 bytes), each representing a unicode letter.
End Rem
Function PeekString$( bank:TBank,offset )
	Return bank.PeekString( offset )
End Function

Rem
bbdoc: Pokes a string into a bank
This sets the value of the memory at an offset in the bank.
Strings are stored as an integer (4 bytes) defining length followed by a series of shorts (2 bytes), each representing a unicode letter.
End Rem
Function PokeString( bank:TBank,offset,value$ )
	bank.PokeString offset,value
End Function

Rem
bbdoc: Peeks a bit from a bank
returns: The value of a bit in the bank
about:
This funciton takes the byte offset and bit offset of a specified but and returns if the bit is 1 or 0.
Keep in mind that the bit indices go from small to large. So, bit 0 is "worth" 1, bit 1 is "worth" 2, and bit 2 is "worth" 4. Bit can be 0-7.
End Rem
Function PeekBit:Byte( bank:TBank,offset,bit )
	Return bank.PeekBit( offset,bit )
End Function

Rem
bbdoc: Changes the value of a bit in a bank
about:
This sets a specified bit in a bank to a specified value given the byte index the bit is located in, and which bit to set.
Keep in mind that the bit indices go from small to large. So, bit 0 is "worth" 1, bit 1 is "worth" 2, and bit 2 is "worth" 4. Bit can be 0-7.
End Rem
Function PokeBit( bank:TBank,offset,bit,value:Byte )
	bank.PokeBit offset,bit,value
End Function

Rem
bbdoc: Reads bytes from a Stream to a Bank
returns: The number of bytes successfully read from the Stream.
End Rem
Function ReadBank( bank:TBank,stream:TStream,offset,count )
	Return bank.Read( stream,offset,count )
End Function

Rem
bbdoc: Writes bytes from a Bank to a Stream
returns: The number of bytes successfully written to the Stream
End Rem
Function WriteBank( bank:TBank,stream:TStream,offset,count )
	Return bank.Write( stream,offset,count )
End Function

And an example using new features:

Mine:TBank=CreateBank(0)
Mine.AutoResizeLimit=50
Mine.ResizeIncrement=10
Mine.PokeBit(0,0,1)
Mine.PokeBit(0,1,0)
Mine.PokeBit(0,2,1)
Mine.PokeBit(0,3,1)
Mine.PokeBit(0,4,0)
Mine.PokeBit(0,5,0)
Mine.PokeBit(0,6,1)
Mine.PokeBit(0,7,0)
Mine.PokeInt(1,60)
For Local j=0 To 4
	For Local i=0 Until 8
		Print ""+Mine.PeekBit(j,i)
	Next
Next
Print Mine.PeekByte(0)
Print "Bank is "+Mine.Size()+" bytes long"
Print "This is for resizebank speed reasons"

BRL, I would suggest simply copy pasting this into your bank.bmx file.

Mark Tiffany

(Posted 2004) [#2]

As some people will be using banks for performance, the extra if added in poke for auto-resizing seems to be a bad idea.

I'd suggest that a more appropriate way of implementing this would be to Extend the TBank type into a TResizeableBank, and over-ride the relevant methods.

Bot Builder

(Posted 2004) [#3]

IMHO, if you want performance you can just do:

RawMem:Byte Ptr=MemAlloc(50)
RawMem[0]=5
RawMem[1]=2

This would be alot faster than the original bank functions as well.

Anyway, I've seen many times people us banks as a dynamic data structure and resizing every time data is added. This is veerrry sloooow, something my autoresizing stuff doesnt suffer from due to ResizeIncrement. I guess I can wrie it extending bank class, although, if you are going to worry about the speed of an extra if, maybe I should just copy this class and rename it. An extra if and a comparisent isnt going to affect too much. If your worried about this might as well leave BMAX and grab a copy of Dev-C++ eh?

Mark Tiffany

(Posted 2005) [#4]

The other reason for extending the type (rather than replacing) is to avoid your changes being lost on a syncmods (unless TBank is Final?)

Bot Builder

(Posted 2005) [#5]

True. I'm hoping BRL will consider and implement some of the features. At least use the new docs.