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.
<p>The returned mark is an opaque handle (type {@code 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).</p>
<p>The behavior of this method is unspecified if no call to an
{@link IntStream initializing method} has occurred after this stream was
constructed.</p>
<p>This method does not change the current position in the input stream.</p>
<p>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.</p>
<pre>
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);
}
</pre>
@return An opaque marker which should be passed to
{@link #release release()} when the marked range is no longer required.
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.
<p>The returned mark is an opaque handle (type {@code 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).</p>
<p>The behavior of this method is unspecified if no call to an {@link IntStream initializing method} has occurred after this stream was constructed.</p>
<p>This method does not change the current position in the input stream.</p>
<p>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.</p> <pre> 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); } </pre>
@return An opaque marker which should be passed to {@link #release release()} when the marked range is no longer required.