Represents a memory buffer that can be read and written to with no allocation. The easiest way to get an idea of what a buffer is, is that it consists in an array of a given capacity, a position index within the array, and a limit index.

Typical operations on a buffer will be to fill it, which you do with put() until you reach the limit.

Then if you want to read the data you just put in the buffer, you flip() the buffer, which will set its limit to the current position, and reset its position to 0. This essentially means that you will be able to read from the beginning of the buffer until the last object you put() in it when writing.

You can then start calling get() to read objects from this buffer until you reach its limit.

Once you are done reading from the buffer, you can clear() the buffer to start writing to it again. That will reset the position to 0 and the limit to the capacity, allowing you to write to the full underlying array.

Buffers can be resized (grown and expanded), which will cause an underlying array reallocation and copy.

By: Stéphane Épardaud
Initializer
Buffer()
Attributes
arraySource Codeshared formal Array<Element> array

The current underlying Array of the buffer. Any changes made to the buffer will be reflected in this array, and vice versa.

Reallocations caused by a call to resize() will cause any prior references obtained though this attribute to become stale.

availableSource Codeshared Integer available

Returns the number of objects that can be read/written from the current position until we reach the limit.

capacitySource Codeshared formal Integer capacity

The underlying array maximum capacity. Both the position and limit cannot exceed the capacity. You can resize() the array to change the capacity.

hasAvailableSource Codeshared Boolean hasAvailable

Returns true if the current position is smaller than the limit.

implementationSource Codeshared formal Object? implementation

The platform-specific implementation object, if any.

limitSource Codeshared formal variable Integer limit

The limit at which to stop reading and writing. The limit will always be greater or equal to the position and smaller or equal to the capacity.

Throws
positionSource Codeshared formal variable Integer position

The current position index within this buffer. Starts at 0 and grows with each get() or put() operation, until it reaches the limit.

Throws
sizeSource Codeshared actual Integer size

The number of elements returned by the iterator of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates.

visibleSource Codeshared default List<Element> visible

A sublist view of array bounded by the current values of position and limit. The size of the returned List will equal available.

Changes made to position or limit after creation of the view will not be synchronized. Also, reallocations caused by a call to resize() will cause any existing views to become stale.

Inherited Attributes
Attributes inherited from: Object
Attributes inherited from: Iterable<Element,Absent>
Methods
clearSource Codeshared formal void clear()

Resets the position to 0 and the limit to the capacity. Use this after reading to start writing to a clear buffer.

equalsSource Codeshared actual default Boolean equals(Object that)

Determine if two values are equal.

For any two non-null objects x and y, x.equals(y) may be written as:

x == y 

Implementations should respect the constraints that:

  • if x===y then x==y (reflexivity),
  • if x==y then y==x (symmetry),
  • if x==y and y==z then x==z (transitivity).

Furthermore it is recommended that implementations ensure that if x==y then x and y have the same concrete class.

A class which explicitly refines equals() is said to support value equality, and the equality operator == is considered much more meaningful for such classes than for a class which simply inherits the default implementation of identity equality from Identifiable.

Note that an implementation of equals() that always returns false does satisfy the constraints given above, as long as the class does not inherit Identifiable. Therefore, in very rare cases where there is no reasonable definition of value equality for a class, for example, function references (Callable), it is acceptable for equals() to be defined to return false for every argument.

Refines Identifiable.equals ultimately refines Object.equals
flipSource Codeshared formal void flip()

Flips this buffer after a write operation, so that it is ready to be read.

This will and set its limit to the current position, and reset its position to 0. This essentially means that you will be able to read from the beginning of the buffer until the last object you put() in it when writing.

getSource Codeshared formal Element get()

Reads an object from this buffer at the current position. Increases the position by 1.

iteratorSource Codeshared actual Iterator<Element> iterator()

Returns an Iterator object to read from the current position until the limit. This iterator modifies the buffer directly, so you will need to clear() or flip() it afterwards if you wish to iterate it again.

putSource Codeshared formal void put(Element element)

Writes an object to this buffer at the current position. Increases the position by 1.

resizeSource Codeshared formal void resize(Integer newSize, Boolean growLimit = false)

Resizes the underlying array, by growing or shrinking it. This implies a new array allocation and copy.

The position will only be affected if the newSize is smaller than the position, in which case the position will be reset down to the newSize (at the end of the buffer).

The limit will be brought down to the newSize if it would otherwise exceed it (when shrinking the buffer below the old limit), effectively making the new limit be at the end of the buffer.

If you are growing the array, the limit will not be changed unless the optional parameter growLimit is set to true (defaults to false), because when you are writing it makes sense to grow the limit, but when you are reading it usually does not, as growing a buffer does not generate new meaningful data.

Parameters:
  • growLimit = false
Inherited Methods
Methods inherited from: Object
Methods inherited from: Category<Element>
Methods inherited from: Iterable<Element,Absent>