ByteBuffer

Description

sealed class Tinman.Core.System.ByteBuffer

Derived from: Disposable ^abstract
IDisposableGeneric<ByteBuffer>
IMemoryConsumption

Represents a byte buffer.

The following figure illustrates the concepts used by a byte buffer:

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+  Absolute byte offset
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+  Capacity = 16 bytes
          |                               |
     Position = 2                      Limit = 10
     (inclusive)                       (exclusive)
         \_____________________________/
          Buffer range, Remaining = 10-2 = 8

Byte order for multi-byte data types is platform specific (e.g. little-endian for Intel x86).

The maximum capacity of a byte buffer is 2^31 bytes (i.e. 2 GB).

Public / Constructors

Allocate

[OwnerReturn]
public static method Allocate → (1)

size ⁱⁿ : int32: [>=0]
Size of the byte buffer, in bytes.
returns → ByteBuffer: The allocated byte buffer.

Allocates a new byte buffer, panicking if not enough memory is available.

The Position of the newly created byte buffer will be zero and the Limit will be set to Capacity. The memory contents of the byte buffer will be initialized to zero.

See also: TinmanException.Panic

AllocateNull

[OwnerReturn]
public static method AllocateNull → (1)

size ⁱⁿ : int32: [>=0]
Size of the byte buffer, in bytes.
returns → ByteBuffer: The allocated byte buffer or null iff not enough memory is available.

Allocates a new byte buffer, returning null if not enough memory is available.

The Position of the newly created byte buffer will be zero and the Limit will be set to Capacity. The memory contents of the byte buffer will be initialized to zero.

CreatePool

[OwnerReturn]
public static method CreatePool → (3)

name ⁱⁿ : string: [not-empty]
Name of the object pool.
bufferSize ⁱⁿ : int32: [>0]
The size of each byte buffer, in bytes.
poolSize ⁱⁿ : int32: [>0]
The maximum size of all byte buffers in the pool, in bytes.
returns → ByteBufferPool: The object pool.

Creates an object pool for ByteBuffer objects of the given size.

FromArray

[OwnerReturn]
public static method FromArray → (3)

array ⁱⁿ : int8 [ ]: [not-null]
The byte array to copy bytes from.
offset ^opt : int32 = 0: [>=0]
Offset into array ⁱⁿ to first byte to copy.
length ^opt : int32 = -1: [-1..array.Length-offset]
Number of bytes to copy. If -1 all bytes in array ⁱⁿ from offset ^opt to the end will be copied.
returns → ByteBuffer: The created ByteBuffer object.

Creates a new instance of ByteBuffer from the given byte array.

Raw

[OwnerReturn]
public static method Raw → (2)

size ⁱⁿ : int32: [>=0]
Size of buffer, in bytes.
data ^opt : IntPtr = default(IntPtr): Initial value for RawData.
returns → ByteBuffer: The raw byte buffer.

Creates a raw byte pointer buffer.

Raw byte buffer do not hold any real memory. They are placeholders for existing memory regions of the given size ⁱⁿ. The start address of a raw byte buffer must be specified via RawData.

Public / Methods

Clear

public method Clear → ()

returns → ByteBuffer: this

Sets the position of this buffer to zero and the limit to its capacity.

This method does not modify the buffer contents. To clear the buffer contents to zero, use Fill.

Compact

[OwnerReturn] [OwnerThis]
public method Compact → ()

returns → ByteBuffer: The compact byte buffer. Will be this iff IsCompact returns true, otherwise a new ByteBuffer is returned.

Returns a compact ByteBuffer that contains the data of this ByteBuffer between its current Position and Limit.

See also: ByteBuffer.IsCompact

Copy

public method Copy → (4)

sourcePosition ⁱⁿ : int32: [>=0]
Absolute position of first byte to read from this source buffer.
target ⁱⁿ : ByteBuffer: [not-null]
The target buffer.
targetPosition ⁱⁿ : int32: [>=0]
Absolute position of first byte to write to target ⁱⁿ.
count ⁱⁿ : int32: [>=0]
The number of bytes to copy.

Copies count ⁱⁿ bytes from this source buffer into the given target ⁱⁿ buffer.

The method will read count ⁱⁿ bytes from this source buffer, starting at sourcePosition ⁱⁿ and will write them to the given target ⁱⁿ buffer, beginning at targetPosition ⁱⁿ. The current buffer positions and limits of both buffers will not be modified.

Fill

public method Fill → (1)

value ^opt : int8 = 0: The clear value.
returns → ByteBuffer: this

Fills the remaining bytes in this buffer.

This method will not modify the Position and Limit of the buffer.

Flip

public method Flip → ()

returns → ByteBuffer: this

Flips the buffer by setting the limit to the current position and resetting the position to zero.

Get

_2 overloads

public method Get¹ → ()

returns → int8: The read value.

Reads an 8-bit signed integer value from the current position and increases the position accordingly.

[Pure]
public method Get² → (1)

position ⁱⁿ : int32: The absolute position.
returns → int8: The read value.

Reads an 8-bit signed integer value from the given absolute position.

GetBytes

_2 overloads

public method GetBytes¹ → (2)

target ⁱⁿ : ByteBuffer: [not-null]
The target buffer.
count ^opt : int32 = -1: [>=-1]
The number of bytes to copy. If -1, the number of remaining bytes in this source buffer will be used.

Copies count ^opt bytes from this source buffer to the given target ⁱⁿ buffer.

The method will read count ^opt bytes from this source buffer, starting at the current buffer position and will write them to the given target ⁱⁿ buffer, beginning at the current buffer position. The current position of both buffers will be incremented by count ^opt. The buffer limits will not be modified.

Copying between raw byte buffers is not allowed (see IsRaw).

public method GetBytes² → (3)

buffer ⁱⁿ : int8 [ ]: [not-null]
The array where to store the bytes.
offset ⁱⁿ : int32: [0..buffer.Length]
Offset into buffer ⁱⁿ to first byte to store.
length ⁱⁿ : int32: [0..buffer.Length-offset]
Total number of bytes to store.

Reads bytes from this buffer and stores them in the given array.

GetDouble

_2 overloads

public method GetDouble¹ → ()

returns → float64: The read value.

Reads a 64-bit floating point value from the current position and increases the position accordingly.

[Pure]
public method GetDouble² → (1)

position ⁱⁿ : int32: The absolute position.
returns → float64: The read value.

Reads a 64-bit floating point value from the given position.

GetFloat

_2 overloads

public method GetFloat¹ → ()

returns → float32: The read value.

Reads a 32-bit floating point value from the current position and increases the position accordingly.

[Pure]
public method GetFloat² → (1)

position ⁱⁿ : int32: The absolute position.
returns → float32: The read value.

Reads a 32-bit floating point value from the given position.

GetInt

_3 overloads

public method GetInt¹ → ()

returns → int32: The read value.

Reads a 32-bit signed integer value from the current position and increases the position accordingly.

public method GetInt² → (1)

order ⁱⁿ : ByteOrder: The byte order to use.
returns → int32: The read value.

Reads a signed 32-bit value from this buffer using the given byte order.

[Pure]
public method GetInt³ → (1)

position ⁱⁿ : int32: The absolute position.
returns → int32: The read value.

Reads a 32-bit signed integer value from the given position.

GetIntPtr

_2 overloads

[Pure]
public method GetIntPtr¹ → ()

returns → IntPtr: The read value.

Reads a pointer value from the current position and increases the position accordingly.

See also: LowLevel.Is64Bit

[Pure]
public method GetIntPtr² → (1)

position ⁱⁿ : int32: The absolute position.
returns → IntPtr: The read value.

Reads a pointer value from the given position.

See also: LowLevel.Is64Bit

GetLong

_3 overloads

public method GetLong¹ → ()

returns → int64: The read value.

Reads a 64-bit signed integer value from the current position and increases the position accordingly.

public method GetLong² → (1)

order ⁱⁿ : ByteOrder: The byte order to use.
returns → int64: The read value.

Reads a signed 64-bit value from this buffer using the given byte order.

[Pure]
public method GetLong³ → (1)

position ⁱⁿ : int32: The absolute position.
returns → int64: The read value.

Reads a 64-bit signed integer value from the given position.

GetShort

_3 overloads

public method GetShort¹ → ()

returns → int16: The read value.

Reads a 16-bit signed integer value from the current position and increases the position accordingly.

public method GetShort² → (1)

order ⁱⁿ : ByteOrder: The byte order to use.
returns → int16: The read value.

Reads a signed 16-bit value from this buffer using the given byte order.

[Pure]
public method GetShort³ → (1)

position ⁱⁿ : int32: The absolute position.
returns → int16: The read value.

Reads a 16-bit signed integer value from the given position.

PositionAndLimit

public method PositionAndLimit → (2)

position ⁱⁿ : int32: [0..ByteBuffer.Capacity]
The new buffer position.
relativeLimit ^opt : int32 = -1: [-1..ByteBuffer.Capacity-position]
The new buffer limit, relative to position ⁱⁿ. If -1, the buffer limit will be set to the capacity.
returns → ByteBuffer: this

Sets the buffer position and limit.

Put

_2 overloads

public method Put¹ → (1)

value ⁱⁿ : int8: The value to write.

Writes an 8-bit signed integer value to the current position and increases the position accordingly.

public method Put² → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : int8: The value to write.

Writes an 8-bit signed integer value to the given position.

PutBytes

_2 overloads

public method PutBytes¹ → (2)

source ⁱⁿ : ByteBuffer: [not-null]
The source buffer.
count ^opt : int32 = -1: [>=-1]
The number of bytes to copy. If -1, the number of remaining bytes in the source buffer will be used.

Copies count ^opt bytes from the given source buffer to this target buffer.

The method will read count ^opt bytes from the given source buffer, starting at the current buffer position and will write them to this target buffer, beginning at the current buffer position. The current position of both buffers will be incremented by count ^opt. The buffer limits will not be modified.

Copying between raw byte buffers is not allowed (see IsRaw).

public method PutBytes² → (3)

buffer ⁱⁿ : int8 [ ]: [not-null]
An array holding the bytes to write.
offset ⁱⁿ : int32: [0..buffer.Length]
Offset into buffer ⁱⁿ to first byte to write.
length ⁱⁿ : int32: [0..buffer.Length-offset]
Total number of bytes to write.

Writes the given bytes into this buffer.

PutDouble

_2 overloads

public method PutDouble¹ → (1)

value ⁱⁿ : float64: The value to write.

Writes a 64-bit floating point value to the current position and increases the position accordingly.

public method PutDouble² → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : float64: The value to write.

Writes a 64-bit floating-point value to the given position.

PutFloat

_2 overloads

public method PutFloat¹ → (1)

value ⁱⁿ : float32: The value to write.

Writes a 32-bit floating point value to the current position and increases the position accordingly.

public method PutFloat² → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : float32: The value to write.

Writes a 32-bit floating-point value to the given position.

PutInt

_3 overloads

public method PutInt¹ → (1)

value ⁱⁿ : int32: The value to write.

Writes a 32-bit signed integer value to the current position and increases the position accordingly.

public method PutInt² → (2)

value ⁱⁿ : int32: The value to write.
order ⁱⁿ : ByteOrder: The byte order to use.

Writes a signed 32-bit value to this buffer using the given byte order.

public method PutInt³ → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : int32: The value to write.

Writes a 32-bit signed integer value to the given position.

PutIntPtr

_2 overloads

public method PutIntPtr¹ → (1)

value ⁱⁿ : IntPtr: The value to write.

Writes a pointer value to the current position and increases the position accordingly.

public method PutIntPtr² → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : IntPtr: The value to write.

Writes a pointer value to the given position.

PutLong

_3 overloads

public method PutLong¹ → (1)

value ⁱⁿ : int64: The value to write.

Writes a 64-bit signed integer value to the current position and increases the position accordingly.

public method PutLong² → (2)

value ⁱⁿ : int64: The value to write.
order ⁱⁿ : ByteOrder: The byte order to use.

Writes a signed 64-bit value to this buffer using the given byte order.

public method PutLong³ → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : int64: The value to write.

Writes a 64-bit signed integer value to the given position.

PutShort

_3 overloads

public method PutShort¹ → (1)

value ⁱⁿ : int16: The value to write.

Writes a 16-bit signed integer value to the current position and increases the position accordingly.

public method PutShort² → (2)

value ⁱⁿ : int16: The value to write.
order ⁱⁿ : ByteOrder: The byte order to use.

Writes a signed 16-bit value to this buffer using the given byte order.

public method PutShort³ → (2)

position ⁱⁿ : int32: The absolute position.
value ⁱⁿ : int16: The value to write.

Writes a 16-bit signed integer value to the given position.

ReadAsStream

[OwnerReturn] [OwnerThis]
public method ReadAsStream → ()

returns → MemoryDataStream: The memory data stream.

Wraps this byte buffer in a data stream.

This byte buffer will end up as the IInternalBuffer.InternalBuffer of the returned MemoryDataStream object.

Skip

public method Skip → (1)

count ⁱⁿ : int32: [>=0]
The number of bytes to skip.

Skips bytes by incrementing Position, without reading from or writing to memory.

ToArray

public method ToArray → ()

returns → int8 [ ]: The read bytes.

Reads all remaining bytes from this buffer and returns them as a byte array.

ToArrayOwn

[OwnerThis]
public method ToArrayOwn → ()

returns → int8 [ ]: The read bytes.

Reads all remaining bytes this buffer and returns them as a byte array.

Zero

public method Zero → (2)

position ^opt : int32 = -1: Absolute offset of first buffer byte that will be filled. If less than 0, the current buffer Position will be used.
count ^opt : int32 = -1: Number of bytes to fill. If less than 0, all bytes up to the buffer Limit will be filled.
returns → ByteBuffer: this

Fills a range of this buffer to 0, without updating its position and limit.

Public / Attributes

Capacity

public attribute Capacity → (get)

value : int32: [>=0]
The buffer capacity, in bytes.

Capacity of this byte buffer, in bytes.

HasRemaining

public attribute HasRemaining → (get)

value : bool: true if there is at least one remaining byte, false if there are no bytes remaining.

Has this byte buffer some remaining bytes left (between current and limit position)?

IsCompact

public attribute IsCompact → (get)

value : bool: true if this buffer is compact, false if not.

Is this buffer compact?

A compact buffer has a Position of 0, and its Limit is equal to its Capacity.

See also: ByteBuffer.Compact

IsRaw

public attribute IsRaw → (get)

value : bool: true if this is a raw byte buffer, false if it is not.

Is this a raw byte buffer?

Raw byte buffers are wrappers for memory regions that have been allocated by a third party (e.g. a locked vertex buffer region). The buffer itself does not hold ownership of the wrapped memory region and will hence perform no disposal whatsoever.

Limit

public attribute Limit → (get,set)

value : int32: [0..ByteBuffer.Capacity]
Byte index of new limit position.

Gets or sets the buffer limit. If the position is larger than the new limit then it is set to the new limit.

NativeOrder

public static attribute NativeOrder → (get)

value : ByteOrder: The native byte order.

Returns the native byte order.

Position

public attribute Position → (get,set)

value : int32: [0..ByteBuffer.Limit]
Byte index of new current position.

Gets or sets the current position of this byte buffer.

RawData

public attribute RawData → (get,set)

value : IntPtr: The base pointer address.

Sets the base pointer address of this byte buffer.

Setting the base pointer of a byte buffer (only for raw buffers, see IsRaw) will reset the Position to zero and the Limit to the buffers Capacity.

RawLimit

public attribute RawLimit → (get)

value : IntPtr: The memory pointer.

Returns a memory pointer to the buffers current limit.

Use this property for interoperability with native code.

RawPosition

public attribute RawPosition → (get)

value : IntPtr: The memory pointer.

Returns a memory pointer to the buffers current position.

Use this property for interoperability with native code.

Remaining

public attribute Remaining → (get)

value : int32: [>=0]
The number of remaining bytes.

Returns the number of bytes remaining between the current buffer position and its limit.

Configuration

ConfigByteOrder

public static attribute ConfigByteOrder → (get)

value : IConfigurator<ByteOrder>: [not-null]
The configurator object.

The configurator object for this type.

ByteBuffer

Description

Public / Constructors

Allocate

Allocate​Null

Create​Pool

From​Array

Raw

Public / Methods

Clear

Compact

Copy

Fill

Flip

Get

Get​Bytes

Get​Double

Get​Float

Get​Int

Get​Int​Ptr

Get​Long

Get​Short

Position​And​Limit

Put

Put​Bytes

Put​Double

Put​Float

Put​Int

Put​Int​Ptr

Put​Long

Put​Short

Read​As​Stream

Skip

To​Array

To​Array​Own

Zero

Public / Attributes

Capacity

Has​Remaining

Is​Compact

Is​Raw

Limit

Native​Order

Position

Raw​Data

Raw​Limit

Raw​Position

Remaining

Configuration

Config​Byte​Order

AllocateNull

CreatePool

FromArray

GetBytes

GetDouble

GetFloat

GetInt

GetIntPtr

GetLong

GetShort

PositionAndLimit

PutBytes

PutDouble

PutFloat

PutInt

PutIntPtr

PutLong

PutShort

ReadAsStream

ToArray

ToArrayOwn

HasRemaining

IsCompact

IsRaw

NativeOrder

RawData

RawLimit

RawPosition

ConfigByteOrder