Class

Xojo.Core.MemoryBlock


Warning

This item was deprecated in version 2020r2. Please use MemoryBlock as a replacement.

Description

A read-only class for managing blocks of memory. Since the contents of a MemoryBlock cannot be altered, if you need to alter a MemoryBlock, use MutableMemoryBlock.

Properties

Name

Type

Read-Only

Shared

Data

Ptr

LittleEndian

Boolean

Size

UInteger

Property descriptions


Xojo.Core.MemoryBlock.Data

Data As Ptr

The memory data in the MemoryBlock.

This property is read-only.

This data pointer is invalidated when the MemoryBlock is changed.


Xojo.Core.MemoryBlock.LittleEndian

LittleEndian As Boolean

When True, indicates that the MemoryBlock data is in LittleEndian format. The default is True.

Simple endian usage:

Var mb1 As New Xojo.Core.MemoryBlock(2) ' defaults to Little Endian = True on all platforms
mb1.Int8Value(0) = 1
mb1.Int8Value(1) = 2

Var firstUInt16 As Int16
firstUInt16 = mb1.UInt16Value(0)
' firstUInt16 = (256 * 2) + (1 * 1) = 513

mb1.LittleEndian = False
Var secondUInt16 As Int16
secondUInt16 = mb1.UInt16Value(0)
' secondUInt16 = (256 * 1) + (1 * 2) = 258

Xojo.Core.MemoryBlock.Size

Size As UInteger

The size (in bytes) of the MemoryBlock.

This property is read-only.

If the size is unknown, this returns &hFFFFFFFF (32-bit apps) or &hFFFFFFFFFFFFFFFF (64-bit app).

Method descriptions


Xojo.Core.MemoryBlock.BooleanValue

BooleanValue(offset As UInteger) As Boolean

Gets a Boolean value at the specified offset (in bytes). Any non-zero value is considered True.


Xojo.Core.MemoryBlock.Clone

Clone As MemoryBlock

Makes a copy of the MemoryBlock. If its size is known, it copies the content.

Var mb1 As New Xojo.Core.MemoryBlock(64)
Var mb2 As Xojo.Core.MemoryBlock = mb1.Clone

Xojo.Core.MemoryBlock.Comparison

Comparison

MemoryBlocks can be compared with each other using the "=" operator.

MemoryBlocks are considered equal for these conditions: * The MemoryBlocks are the same object * Both MemoryBlocks' data point to the same location * Both MemoryBlocks' size and content are the same There is no concept of one MemoryBlock being greater than or less than another MemoryBlock.


Xojo.Core.MemoryBlock.Constructor

Constructor(bytes() As Byte)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a MemoryBlock from an existing Byte array.


Xojo.Core.MemoryBlock.Constructor

Constructor(other As MemoryBlock)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new MemoryBlock with the data from an existing MemoryBlock.


Xojo.Core.MemoryBlock.Constructor

Constructor(p As Ptr)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a MemoryBlock from an existing chunk of memory.


Xojo.Core.MemoryBlock.Constructor

Constructor(p As Ptr, size As UInteger)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a MemoryBlock from an existing block of memory of a specific size.


Xojo.Core.MemoryBlock.Constructor

Constructor(size As UInteger)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a MemoryBlock with the desired size in bytes.

Reserve 1K:

Var mb As New Xojo.Core.MemoryBlock(1024) ' Reserve 1K bytes

Xojo.Core.MemoryBlock.CStringValue

CStringValue(offset As UInteger) As CString

Gets a CString value at the specified offset (in bytes).

A CString is a sequence of non-zero bytes followed by a terminating Chr(0) to mark the end of the CString.


Xojo.Core.MemoryBlock.CurrencyValue

CurrencyValue(offset As UInteger) As Currency

Gets an 8-byte Currency value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.DoubleValue

DoubleValue(offset As UInteger) As Double

Gets a Double value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.IndexOf

IndexOf(offset As UInteger, other As MemoryBlock) As UInteger

Returns the position of the other MemoryBlock starting at the offset. Returns -1 if other was not found.


Xojo.Core.MemoryBlock.Int16Value

Int16Value(offset As UInteger) As Int16

Gets an Int16 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.Int32Value

Int32Value(offset As UInteger) As Int32

Gets an Int32 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.Int64Value

Int64Value(offset As UInteger) As Int64

Gets an Int64 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.Int8Value

Int8Value(offset As UInteger) As Int8

Gets an Int8 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.Left

Left(bytes As UInteger) As MemoryBlock

Gets the specified number of bytes at the beginning of the MemoryBlock.


Xojo.Core.MemoryBlock.PtrValue

PtrValue(offset As UInteger) As Ptr

Gets a Ptr value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.Right

Right(bytes As UInteger) As MemoryBlock

Gets the bytes from the end of the MemoryBlock.

Get the last two bytes of a MemoryBlock:

Var bytes() As Byte
bytes.Append(&h0a)
bytes.Append(&h0b)
bytes.Append(&h0c)

Var data As New Xojo.Core.MemoryBlock(bytes)
Var mb As Xojo.Core.MemoryBlock = data.Right(2)

Xojo.Core.MemoryBlock.SingleValue

SingleValue(offset As UInteger) As Single

Gets a Single value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.UInt16Value

UInt16Value(offset As UInteger) As UInt16

Gets an UInt16 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.UInt32Value

UInt32Value(offset As UInteger) As UInt32

Gets an UInt32 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.UInt64Value

UInt64Value(offset As UInteger) As UInt64

Gets an UInt64 value at the specified offset (in bytes).


Xojo.Core.MemoryBlock.UInt8Value

UInt8Value(offset As UInteger) As UInt8

Gets an UInt8 value at the specified offset (in bytes). A UInt8 can also be considered a Byte.

Get the bytes from a MemoryBlock:

Var getBytes() As UInt8
For i As Integer = 0 To 3
  getBytes.AddRow(mb.UInt8Value(i))
Next

Xojo.Core.MemoryBlock.WStringValue

WStringValue(offset As UInteger) As WString

Gets a WString value at the specified offset (in bytes).

Notes

For 32-bit apps, you can request a maximum of about 2 to 3 GB depending on the OS. Generally Windows is closer to 2GB and macOS/Linux are closer to 3GB. There is no practical limit for 64-bit apps.

To convert Text to a MemoryBlock, use TextEncoding.ConvertTextToData. To convert a MemoryBlock to Text, use TextEncoding.ConvertDataToText.

Compared to MutableMemoryBlock, MemoryBlock is more efficient in terms of memory use savings, but doesn't really have any difference in terms of access. Being able to pass around immutable chunks of data allows the framework to directly reference internal data and avoid having to copy it on the off chance it might get modified.


Decodehex

To convert a hex Text to a MemoryBlock you can use code like this:

' hex contains hex as Text
Var bytes() As UInt8
For i As Integer = 0 To hex.Length - 2 Step 2
  Var value As UInt8 = UInt8.FromHex(hex.Mid(i, 2))
  bytes.AddRow(value)
Next
Var mb As New Xojo.Core.MemoryBlock(bytes)

Encodehex

To EncodeHex the contents of a MemoryBlock you can use code like this:

Var joiner() As Text
For i As Integer = 0 To hashMB.Size - 1
  Var b As UInt8 = hashMB.UInt8Value(i)
  joiner.AddRow(b.ToHex(2))
Next
Var hex As Text = Text.Join(joiner, "")

Converting to a classic memoryblock

When using both the Classic and New Framework in a single (desktop, web or console) app, you may find that you need to convert a Xojo.Core.MemoryBlock to a Classic MemoryBlock for use with other methods. You can do so by copying the data from the Xojo.Core.MemoryBlock to the Classic MemoryBlock:

' newMB is a Xojo.Core.MemoryBlock
Var temp As MemoryBlock = newMb.Data
Var mb As New MemoryBlock(newMb.Size)
mb.StringValue(0, mb.Size) = temp.StringValue(0, mb.Size)
temp = Nil ' optional as it will also be cleared when it goes out of scope

Compatibility

All project types on all supported operating systems.

See also

Object parent class; MemoryBlock, MemoryBlock classes