mark method

@override int mark()

A mark provides a guarantee that {@link #seek seek()} operations will be valid over a "marked range" extending from the index where {@code mark()} was called to the current {@link #index index()}. This allows the use of streaming input sources by specifying the minimum buffering requirements to support arbitrary lookahead during prediction.

The returned mark is an opaque handle (type [int]) which is passed to {@link #release release()} when the guarantees provided by the marked range are no longer necessary. When calls to {@code mark()}/{@code release()} are nested, the marks must be released in reverse order of which they were obtained. Since marked regions are used during performance-critical sections of prediction, the specific behavior of invalid usage is unspecified (i.e. a mark is not released, or a mark is released twice, or marks are not released in reverse order from which they were created).

The behavior of this method is unspecified if no call to an {@link IntStream initializing method} has occurred after this stream was constructed.

This method does not change the current position in the input stream.

The following example shows the use of {@link #mark mark()}, {@link #release release(mark)}, {@link #index index()}, and {@link #seek seek(index)} as part of an operation to safely work within a marked region, then restore the stream position to its original value and release the mark.

IntStream stream = ...;
int index = -1;
int mark = stream.mark();
try {
  index = stream.index();
  // perform work here...
} finally {
  if (index != -1) {
    stream.seek(index);
  }
  stream.release(mark);
}

@return An opaque marker which should be passed to {@link #release release()} when the marked range is no longer required.

Implementation

@override
int mark() {
  return 0;
}