Buffer

Mutable buffer of value elements.

This wraps one of the Java NIO buffer classes. Most of the Java documentation is applicable to this class.

Buffer instances are in no way synchronized and are typically used from a single fiber. Extract immutable Chunks to pass values to other fibers or via streams.

Construction

There is a concrete buffer subclass for each primitive type. There are three ways to create a buffer:

Allocation

Simply allocates a new buffer on the heap of a certain size, for example Buffer.byte(100), Buffer.char(200).

For ByteBuffer there is the special case of direct buffers, which can be constructed via Buffer.byteDirect. See the Java docs for details of the advantages and disadvantages of direct byte buffers.

Wrapping

Buffers can wrap existing Java buffers, or ZIO Chunks. Care must be taken when wrapping Java buffers that the wrapped buffer is not subsequently modified; these objects are typically wrapped to provide efficient interoperability with Java APIs.

A CharBuffer can also wrap any java.lang.CharSequence.

Views

While ByteBuffers are created via allocation or wrapping, the other buffer types are more commonly constructed as a view over a ByteBuffer. Each numeric buffer class supports either big-endian or little-endian byte order as required.

View buffers are constructed via the various asXXX methods on the zio.nio.ByteBuffer class, for example:

val ints(implicit trace: ZTraceElement): UIO[IntBuffer] = bytes.asIntBuffer

Changes to made via view buffers are reflected in the original ByteBuffer and vice-versa.

Differences from Java

The Java API supports "invocation chaining", which does not work with effect values. The Java example:

b.flip().position(23).limit(42)

is typically written:

for {
  _ <- b.flip
  _ <- b.position(23)
  _ <- b.limit(42)
} yield ()

or in cases like this when the intermediate values aren't used:

b.flip *> b.position(23) *> b.limit(42)

Annotations: @specialized()

Linear Supertypes

AnyRef, Any

Known Subclasses

ByteBuffer, CharBuffer, DoubleBuffer, FloatBuffer, IntBuffer, LongBuffer, MappedByteBuffer, ShortBuffer

Abstract Value Members

abstract def array(implicit trace: ZTraceElement): UIO[Array[A]]

Attributes
protected[zio.nio]
abstract def asReadOnlyBuffer(implicit trace: ZTraceElement): UIO[Buffer[A]]

Creates a read-only view of this buffer.
abstract val buffer: java.nio.Buffer

Attributes
protected[zio.nio]
abstract def compact(implicit trace: ZTraceElement): UIO[Unit]

Compacts this buffer (optional operation).
Compacts this buffer (optional operation). The bytes between the buffer's current position and its limit, if any, are copied to the beginning of the buffer. That is, the byte at index p = position() is copied to index 0, the byte at index p + 1 is copied to index 1, and so forth until the byte at index limit() - 1 is copied to index n = limit() - 1 - p. The buffer's position is then set to n+1 and its limit is set to its capacity. The mark, if defined, is discarded.
The buffer's position is set to the number of bytes copied, rather than to zero, so that an invocation of this method can be followed immediately by an invocation of another relative put method.
Invoke this method after writing data from a buffer in case the write was incomplete.
Dies with ReadOnlyBufferException if this buffer is read-only.
abstract def duplicate(implicit trace: ZTraceElement): UIO[Buffer[A]]

Creates a new buffer that shares this buffer's content.
Creates a new buffer that shares this buffer's content. The content of the new buffer will be that of this buffer. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's capacity, limit, position, and mark values will be identical to those of this buffer.
abstract def get(i: Int)(implicit trace: ZTraceElement): UIO[A]

Absolute get of a single element.
Absolute get of a single element. Reads the element at the given index. The position does not change.
Dies with IndexOutOfBoundsException if the index is negative or not smaller than the limit.
abstract def get(implicit trace: ZTraceElement): UIO[A]

Relative get of a single element.
Relative get of a single element. Reads the element at the position and increments the position.
Dies with BufferUnderflowException If there are no elements remaining.
abstract def getChunk(maxLength: Int = Int.MaxValue)(implicit trace: ZTraceElement): UIO[Chunk[A]]

Relative get of multiple elements.
Relative get of multiple elements.
Reads up to the specified number of elements from the current position. If fewer than maxLength elements are remaining, then all the remaining elements are read. The position is incremented by the number of elements read.
maxLength
Defaults to Int.MaxValue, meaning all remaining elements will be read.
abstract def order(implicit trace: ZTraceElement): UIO[ByteOrder]

The byte order used for reading multiple byte values.
The byte order used for reading multiple byte values.
Also the byte order used any view buffers created from this buffer.
abstract def put(index: Int, element: A)(implicit trace: ZTraceElement): UIO[Unit]

Absolute put of a single element.
Absolute put of a single element. Writes the element at the specified index. The position does not change.
Dies with IndexOutOfBoundsException if the index is negative or not smaller than the limit. Dies with ReadOnlyBufferException if this is a read-only buffer.
abstract def put(element: A)(implicit trace: ZTraceElement): UIO[Unit]

Relative put of a single element.
Relative put of a single element. Writes the element at the position and increments the position.
Dies with BufferOverflowException if there are no elements remaining. Dies with ReadOnlyBufferException if this is a read-only buffer.
abstract def putChunkAll(chunk: Chunk[A])(implicit trace: ZTraceElement): UIO[Unit]

Tries to put an entire chunk in this buffer, possibly overflowing.
Tries to put an entire chunk in this buffer, possibly overflowing.
putChunk is a safe public variant of this that won't overflow.

Attributes
protected
abstract def slice(implicit trace: ZTraceElement): UIO[Buffer[A]]

Creates a new buffer whose content is a shared subsequence of this buffer's content.
Creates a new buffer whose content is a shared subsequence of this buffer's content. The content of the new buffer will start at this buffer's current position. Changes to this buffer's content will be visible in the new buffer, and vice versa; the two buffers' position, limit, and mark values will be independent.
The new buffer's position will be zero, its capacity and its limit will be the number of bytes remaining in this buffer.

Concrete Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def asInstanceOf[T0]: T0

Definition Classes
Any
final def capacity: Int

Returns this buffer's capacity.
final def clear(implicit trace: ZTraceElement): UIO[Unit]

Clears this buffer.
Clears this buffer. The position is set to zero, the limit is set to the capacity, and the mark is discarded. No values in the buffer are actually cleared, but this is typically used before putting new values into a buffer, after all its contents have been processed.
If the buffer's current values have not been completely processed, then the compact method may be more appropriate.
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
final def flip(implicit trace: ZTraceElement): UIO[Unit]

Flips this buffer.
Flips this buffer. The limit is set to the current position and then the position is set to zero. If the mark is defined then it is discarded. After a sequence of channel-read or put operations, invoke this method to prepare for a sequence of channel-write or relative get operations.
This method is often used in conjunction with the compact method when transferring data from one place to another.
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
final def hasArray: Boolean

Indicates if this buffer is backed by an array on the heap.
Indicates if this buffer is backed by an array on the heap.
The underlying array can be used in a safe way via the withArray method.
final def hasRemaining(implicit trace: ZTraceElement): UIO[Boolean]

Indicates whether there are any elements between this buffer's position and its limit.
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isDirect: Boolean

Indicates if this buffer was directly allocated.
Indicates if this buffer was directly allocated.
Returns true for directly allocated ByteBuffers and view buffers created from them.
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def isReadOnly: Boolean

Indicates if this buffer is read-only.
Indicates if this buffer is read-only.
Calling any put methods on a read-only buffer with throw ReadOnlyBufferException.
final def limit(newLimit: Int)(implicit trace: ZTraceElement): UIO[Unit]

Sets this buffer's limit.
Sets this buffer's limit.
Dies with IllegalArgumentException if the new limit is outside the bounds.
newLimit
Must be >= 0 and <= this buffer's capacity.
final def limit(implicit trace: ZTraceElement): UIO[Int]

Returns this buffer's limit.
final def mark(implicit trace: ZTraceElement): UIO[Unit]

Sets this buffer's mark to the current position.
final def moveLimit(delta: Int)(implicit trace: ZTraceElement): UIO[Int]

Moves this buffer's limit forward or backwards by a delta.
Moves this buffer's limit forward or backwards by a delta.
delta
The number of elements to move, negative to move backwards.
returns
The new limit.
final def movePosition(delta: Int)(implicit trace: ZTraceElement): UIO[Int]

Moves this buffer's position forward or backwards by a delta.
Moves this buffer's position forward or backwards by a delta.
delta
The number of elements to move, negative to move backwards.
returns
The new position.
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
final def position(newPosition: Int)(implicit trace: ZTraceElement): UIO[Unit]

Sets this buffer's position.
Sets this buffer's position.
Dies with IllegalArgumentException if the new position is outside the bounds.
newPosition
Must be >= 0 and <= the current limit.
final def position(implicit trace: ZTraceElement): UIO[Int]

Returns this buffer's position.
final def putChunk(chunk: Chunk[A])(implicit trace: ZTraceElement): UIO[Chunk[A]]

Relative put of multiple elements.
Relative put of multiple elements. Writes as many elements as can fit in remaining buffer space, returning any elements that did not fit.
returns
The remaining elements that could not fit in this buffer, if any.
final def remaining(implicit trace: ZTraceElement): UIO[Int]

Returns the number of elements between this buffer's position and its limit.
final def reset(implicit trace: ZTraceElement): UIO[Unit]

Resets the position to the previously set mark.
Resets the position to the previously set mark. A mark must be set before calling this.
Dies with InvalidMarkException if a mark has not previously been set.
final def rewind(implicit trace: ZTraceElement): UIO[Unit]

Rewinds this buffer.
Rewinds this buffer. The position is set to zero and the mark is discarded. Invoke this method before a sequence of channel-write or get operations, assuming that the limit has already been set appropriately.
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toString(): String

Definition Classes
AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def withArray[R, E, B](noArray: ZIO[R, E, B], hasArray: (Array[A], Int) ⇒ ZIO[R, E, B])(implicit trace: ZTraceElement): ZIO[R, E, B]

Perform effects using this buffer's underlying array directly.
Perform effects using this buffer's underlying array directly. Because only some buffers are backed by arrays, two cases must be handled. Ideally, the same result is produced in each case, with the hasArray variant just being more efficient.
For the hasArray case, the function is provided the backing array itself and an offset within that array which contains the first element of this buffer. Elements in the array before the offset are not contained in this buffer.
noArray
The effect to perform if this buffer is not backed by an array.
hasArray
The effect to perform if this buffer is backed by an array.

Related Docs: object Buffer | package nio

abstract class Buffer[A] extends AnyRef

Construction

Allocation

Wrapping

Views

Differences from Java

Abstract Value Members

abstract def array(implicit trace: ZTraceElement): UIO[Array[A]]

abstract def asReadOnlyBuffer(implicit trace: ZTraceElement): UIO[Buffer[A]]

abstract val buffer: java.nio.Buffer

abstract def compact(implicit trace: ZTraceElement): UIO[Unit]

abstract def duplicate(implicit trace: ZTraceElement): UIO[Buffer[A]]

abstract def get(i: Int)(implicit trace: ZTraceElement): UIO[A]

abstract def get(implicit trace: ZTraceElement): UIO[A]

abstract def getChunk(maxLength: Int = Int.MaxValue)(implicit trace: ZTraceElement): UIO[Chunk[A]]

abstract def order(implicit trace: ZTraceElement): UIO[ByteOrder]

abstract def put(index: Int, element: A)(implicit trace: ZTraceElement): UIO[Unit]

abstract def put(element: A)(implicit trace: ZTraceElement): UIO[Unit]

abstract def putChunkAll(chunk: Chunk[A])(implicit trace: ZTraceElement): UIO[Unit]

abstract def slice(implicit trace: ZTraceElement): UIO[Buffer[A]]

Concrete Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: Any): Boolean

final def asInstanceOf[T0]: T0

final def capacity: Int

final def clear(implicit trace: ZTraceElement): UIO[Unit]

def clone(): AnyRef

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

final def flip(implicit trace: ZTraceElement): UIO[Unit]

final def getClass(): Class[_]

final def hasArray: Boolean

final def hasRemaining(implicit trace: ZTraceElement): UIO[Boolean]

def hashCode(): Int

final def isDirect: Boolean

final def isInstanceOf[T0]: Boolean

final def isReadOnly: Boolean

final def limit(newLimit: Int)(implicit trace: ZTraceElement): UIO[Unit]

final def limit(implicit trace: ZTraceElement): UIO[Int]

final def mark(implicit trace: ZTraceElement): UIO[Unit]

final def moveLimit(delta: Int)(implicit trace: ZTraceElement): UIO[Int]

final def movePosition(delta: Int)(implicit trace: ZTraceElement): UIO[Int]

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

final def position(newPosition: Int)(implicit trace: ZTraceElement): UIO[Unit]

final def position(implicit trace: ZTraceElement): UIO[Int]

final def putChunk(chunk: Chunk[A])(implicit trace: ZTraceElement): UIO[Chunk[A]]

final def remaining(implicit trace: ZTraceElement): UIO[Int]

final def reset(implicit trace: ZTraceElement): UIO[Unit]

final def rewind(implicit trace: ZTraceElement): UIO[Unit]

final def synchronized[T0](arg0: ⇒ T0): T0

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

final def withArray[R, E, B](noArray: ZIO[R, E, B], hasArray: (Array[A], Int) ⇒ ZIO[R, E, B])(implicit trace: ZTraceElement): ZIO[R, E, B]

Inherited from AnyRef

Inherited from Any

Ungrouped