Package uk.ac.starlink.array

# Class BufferIterator

java.lang.Object
uk.ac.starlink.array.BufferIterator

All Implemented Interfaces:
  `Iterator`

public class BufferIterator extends Object implements Iterator
Provides buffers for convenient stepping through an array. At each step a primitive buffer of a given type of just the right size to match the current chunk is returned. This class is provided as a convenience for applications code which wishes to iterate through an array in sections, using a buffer of the size matching the section at each step.

This class provides a thin convenience wrapper around `ChunkStepper`, which is itself a simple class which steps from zero to a given limit in chunks. The only additional functionality provided by a `BufferIterator` is that it will ensure a suitable primitive buffer is available at each step, and (since the `next` method actually returns something, namely the buffer), it implements the `Iterator` interface which `ChunkStepper` does not.

A typical use of `BufferIterator` is as follows:

         ArrayAccess acc = ndarray.getAccess();
         for ( BufferIterator bufIt = new BufferIterator( npix, Type.DOUBLE );
               bufIt.hasNext(); ) {
             double[] buf = (double[]) bIt.next();
             acc.read( buf, 0, buf.length );
             doStuff( buf );
         }

Author:
  Mark Taylor (Starlink)
See Also:
  - `ChunkStepper`

## Constructor Summary

Constructors
Constructor
Description
`BufferIterator(long length)`
Create a new `BufferIterator` with a default chunk size.
`BufferIterator(long length, Type type, int chunkSize)`
Create a new `BufferIterator` with a given chunk size.

## Method Summary

Modifier and Type
Method
Description
`long`
`getBase()`
The offset of the base of the chunk most recently returned by `next`.
`boolean`
`hasNext()`
See if iteration has finished.
`Object`
`next()`
Returns a primitive buffer of this object's type, with a length matching that of this chunk.
`void`
`remove()`
Remove functionality is not implemented by this class.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface java.util.Iterator

`forEachRemaining`

## Constructor Details

### BufferIterator

public BufferIterator(long length, Type type, int chunkSize)
Create a new `BufferIterator` with a given chunk size.

Parameters:
  `length` - the total number of elements to iterate over
  `type` - the type of the primitive buffer which the `next` method will return at each iteration
  `chunkSize` - the size of buffer which will be used (except perhaps for the last chunk)
Throws:
  `IllegalArgumentException` - if `chunkSize<=0` or `length<0`

### BufferIterator

public BufferIterator(long length)
Create a new `BufferIterator` with a default chunk size.

Parameters:
  `length` - the total number of elements to iterate over

## Method Details

### next

public Object next()
Returns a primitive buffer of this object's type, with a length matching that of this chunk. Note it is not necessarily a new buffer created for each iteration, the one returned by this method may be the same one that it returned last time (in fact it will be, except perhaps for the last iteration when a smaller one may be required).

Specified by:
  `next` in interface `Iterator`
Returns:
  a primitive array of the same size as this chunk
Throws:
  `NoSuchElementException` - if hasNext would return false

### hasNext

public boolean hasNext()
See if iteration has finished.

Specified by:
  `hasNext` in interface `Iterator`
Returns:
  true iff there are more chunks

### remove

public void remove()
Remove functionality is not implemented by this class.

Specified by:
  `remove` in interface `Iterator`
Throws:
  `UnsupportedOperationException` - always

### getBase

public long getBase()
The offset of the base of the chunk most recently returned by `next`. This will be zero for the first chunk, and increasing by the size of the buffer returned by `next` with each iteration after that.

Returns:
  the base of the current chunk
Throws:
  `IllegalStateException` - if called before the first call of `next`