runtime/Swift/Sources/Antlr4/IntStream.swift - external/github.com/antlr/antlr4 - Git at Google

 ///
 /// Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
 /// Use of this file is governed by the BSD 3-clause license that
 /// can be found in the LICENSE.txt file in the project root.
 ///


 ///
 /// A simple stream of symbols whose values are represented as integers. This
 /// interface provides __marked ranges__ with support for a minimum level
 /// of buffering necessary to implement arbitrary lookahead during prediction.
 /// For more information on marked ranges, see _#mark_.
 ///
 /// __Initializing Methods:__ Some methods in this interface have
 /// unspecified behavior if no call to an initializing method has occurred after
 /// the stream was constructed. The following is a list of initializing methods:
 ///
 /// * _#LA_
 /// * _#consume_
 /// * _#size_
 ///
 public protocol IntStream: AnyObject {

     ///
     /// Consumes the current symbol in the stream. This method has the following
     /// effects:
     ///
     /// * __Forward movement:__ The value of _#index index()_
     /// before calling this method is less than the value of `index()`
     /// after calling this method.
     /// * __Ordered lookahead:__ The value of `LA(1)` before
     /// calling this method becomes the value of `LA(-1)` after calling
     /// this method.
     ///
     /// Note that calling this method does not guarantee that `index()` is
     /// incremented by exactly 1, as that would preclude the ability to implement
     /// filtering streams (e.g. _org.antlr.v4.runtime.CommonTokenStream_ which distinguishes
     /// between "on-channel" and "off-channel" tokens).
     ///
     /// - throws: _ANTLRError.illegalState_ if an attempt is made to consume the the
     /// end of the stream (i.e. if `LA(1)==`_#EOF EOF_ before calling
     /// `consume`).
     ///
     func consume() throws

     ///
     /// Gets the value of the symbol at offset `i` from the current
     /// position. When `i==1`, this method returns the value of the current
     /// symbol in the stream (which is the next symbol to be consumed). When
     /// `i==-1`, this method returns the value of the previously read
     /// symbol in the stream. It is not valid to call this method with
     /// `i==0`, but the specific behavior is unspecified because this
     /// method is frequently called from performance-critical code.
     ///
     /// This method is guaranteed to succeed if any of the following are true:
     ///
     /// * `i>0`
     /// * `i==-1` and _#index index()_ returns a value greater
     /// than the value of `index()` after the stream was constructed
     /// and `LA(1)` was called in that order. Specifying the current
     /// `index()` relative to the index after the stream was created
     /// allows for filtering implementations that do not return every symbol
     /// from the underlying source. Specifying the call to `LA(1)`
     /// allows for lazily initialized streams.
     /// * `LA(i)` refers to a symbol consumed within a marked region
     /// that has not yet been released.
     ///
     /// If `i` represents a position at or beyond the end of the stream,
     /// this method returns _#EOF_.
     ///
     /// The return value is unspecified if `i<0` and fewer than `-i`
     /// calls to _#consume consume()_ have occurred from the beginning of
     /// the stream before calling this method.
     ///
     /// - throws: _ANTLRError.unsupportedOperation_ if the stream does not support
     /// retrieving the value of the specified symbol
     ///
     func LA(_ i: Int) throws -> Int

     ///
     /// A mark provides a guarantee that _#seek seek()_ operations will be
     /// valid over a "marked range" extending from the index where `mark()`
     /// was called to the current _#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 _#release release()_ when the guarantees provided by the marked
     /// range are no longer necessary. When calls to
     /// `mark()`/`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
     /// _org.antlr.v4.runtime.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 _#mark mark()_,
     /// _#release release(mark)_, _#index index()_, and
     /// _#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);
     /// }
     ///
     ///
     /// - returns: An opaque marker which should be passed to
     /// _#release release()_ when the marked range is no longer required.
     ///
     func mark() -> Int

     ///
     /// This method releases a marked range created by a call to
     /// _#mark mark()_. Calls to `release()` must appear in the
     /// reverse order of the corresponding calls to `mark()`. If a mark is
     /// released twice, or if marks are not released in reverse order of the
     /// corresponding calls to `mark()`, the behavior is unspecified.
     ///
     /// For more information and an example, see _#mark_.
     ///
     /// - parameter marker: A marker returned by a call to `mark()`.
     /// - seealso: #mark
     ///
     func release(_ marker: Int) throws

     ///
     /// Return the index into the stream of the input symbol referred to by
     /// `LA(1)`.
     ///
     /// The behavior of this method is unspecified if no call to an
     /// _org.antlr.v4.runtime.IntStream initializing method_ has occurred after this stream was
     /// constructed.
     ///
     func index() -> Int

     ///
     /// Set the input cursor to the position indicated by `index`. If the
     /// specified index lies past the end of the stream, the operation behaves as
     /// though `index` was the index of the EOF symbol. After this method
     /// returns without throwing an exception, then at least one of the following
     /// will be true.
     ///
     /// * _#index index()_ will return the index of the first symbol
     /// appearing at or after the specified `index`. Specifically,
     /// implementations which filter their sources should automatically
     /// adjust `index` forward the minimum amount required for the
     /// operation to target a non-ignored symbol.
     /// * `LA(1)` returns _#EOF_
     ///
     /// This operation is guaranteed to not throw an exception if `index`
     /// lies within a marked region. For more information on marked regions, see
     /// _#mark_. The behavior of this method is unspecified if no call to
     /// an _org.antlr.v4.runtime.IntStream initializing method_ has occurred after this stream
     /// was constructed.
     ///
     /// - parameter index: The absolute index to seek to.
     ///
     /// - throws: _ANTLRError.illegalArgument_ if `index` is less than 0
     /// - throws: _ANTLRError.unsupportedOperation_ if the stream does not support
     /// seeking to the specified index
     ///
     func seek(_ index: Int) throws

     ///
     /// Returns the total number of symbols in the stream, including a single EOF
     /// symbol.
     ///
     /// - throws: _ANTLRError.unsupportedOperation_ if the size of the stream is
     /// unknown.
     ///
     func size() -> Int

     ///
     /// Gets the name of the underlying symbol source. This method returns a
     /// non-null, non-empty string. If such a name is not known, this method
     /// returns _#UNKNOWN_SOURCE_NAME_.
     ///
     func getSourceName() -> String
 }
	///
	/// Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
	/// Use of this file is governed by the BSD 3-clause license that
	/// can be found in the LICENSE.txt file in the project root.
	///



	///
	/// A simple stream of symbols whose values are represented as integers. This
	/// interface provides __marked ranges__ with support for a minimum level
	/// of buffering necessary to implement arbitrary lookahead during prediction.
	/// For more information on marked ranges, see _#mark_.
	///
	/// __Initializing Methods:__ Some methods in this interface have
	/// unspecified behavior if no call to an initializing method has occurred after
	/// the stream was constructed. The following is a list of initializing methods:
	///
	/// * _#LA_
	/// * _#consume_
	/// * _#size_
	///
	public protocol IntStream: AnyObject {

	///
	/// Consumes the current symbol in the stream. This method has the following
	/// effects:
	///
	/// * __Forward movement:__ The value of _#index index()_
	/// before calling this method is less than the value of `index()`
	/// after calling this method.
	/// * __Ordered lookahead:__ The value of `LA(1)` before
	/// calling this method becomes the value of `LA(-1)` after calling
	/// this method.
	///
	/// Note that calling this method does not guarantee that `index()` is
	/// incremented by exactly 1, as that would preclude the ability to implement
	/// filtering streams (e.g. _org.antlr.v4.runtime.CommonTokenStream_ which distinguishes
	/// between "on-channel" and "off-channel" tokens).
	///
	/// - throws: _ANTLRError.illegalState_ if an attempt is made to consume the the
	/// end of the stream (i.e. if `LA(1)==`_#EOF EOF_ before calling
	/// `consume`).
	///
	func consume() throws

	///
	/// Gets the value of the symbol at offset `i` from the current
	/// position. When `i==1`, this method returns the value of the current
	/// symbol in the stream (which is the next symbol to be consumed). When
	/// `i==-1`, this method returns the value of the previously read
	/// symbol in the stream. It is not valid to call this method with
	/// `i==0`, but the specific behavior is unspecified because this
	/// method is frequently called from performance-critical code.
	///
	/// This method is guaranteed to succeed if any of the following are true:
	///
	/// * `i>0`
	/// * `i==-1` and _#index index()_ returns a value greater
	/// than the value of `index()` after the stream was constructed
	/// and `LA(1)` was called in that order. Specifying the current
	/// `index()` relative to the index after the stream was created
	/// allows for filtering implementations that do not return every symbol
	/// from the underlying source. Specifying the call to `LA(1)`
	/// allows for lazily initialized streams.
	/// * `LA(i)` refers to a symbol consumed within a marked region
	/// that has not yet been released.
	///
	/// If `i` represents a position at or beyond the end of the stream,
	/// this method returns _#EOF_.
	///
	/// The return value is unspecified if `i<0` and fewer than `-i`
	/// calls to _#consume consume()_ have occurred from the beginning of
	/// the stream before calling this method.
	///
	/// - throws: _ANTLRError.unsupportedOperation_ if the stream does not support
	/// retrieving the value of the specified symbol
	///
	func LA(_ i: Int) throws -> Int

	///
	/// A mark provides a guarantee that _#seek seek()_ operations will be
	/// valid over a "marked range" extending from the index where `mark()`
	/// was called to the current _#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 _#release release()_ when the guarantees provided by the marked
	/// range are no longer necessary. When calls to
	/// `mark()`/`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
	/// _org.antlr.v4.runtime.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 _#mark mark()_,
	/// _#release release(mark)_, _#index index()_, and
	/// _#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);
	/// }
	///
	///
	/// - returns: An opaque marker which should be passed to
	/// _#release release()_ when the marked range is no longer required.
	///
	func mark() -> Int

	///
	/// This method releases a marked range created by a call to
	/// _#mark mark()_. Calls to `release()` must appear in the
	/// reverse order of the corresponding calls to `mark()`. If a mark is
	/// released twice, or if marks are not released in reverse order of the
	/// corresponding calls to `mark()`, the behavior is unspecified.
	///
	/// For more information and an example, see _#mark_.
	///
	/// - parameter marker: A marker returned by a call to `mark()`.
	/// - seealso: #mark
	///
	func release(_ marker: Int) throws

	///
	/// Return the index into the stream of the input symbol referred to by
	/// `LA(1)`.
	///
	/// The behavior of this method is unspecified if no call to an
	/// _org.antlr.v4.runtime.IntStream initializing method_ has occurred after this stream was
	/// constructed.
	///
	func index() -> Int

	///
	/// Set the input cursor to the position indicated by `index`. If the
	/// specified index lies past the end of the stream, the operation behaves as
	/// though `index` was the index of the EOF symbol. After this method
	/// returns without throwing an exception, then at least one of the following
	/// will be true.
	///
	/// * _#index index()_ will return the index of the first symbol
	/// appearing at or after the specified `index`. Specifically,
	/// implementations which filter their sources should automatically
	/// adjust `index` forward the minimum amount required for the
	/// operation to target a non-ignored symbol.
	/// * `LA(1)` returns _#EOF_
	///
	/// This operation is guaranteed to not throw an exception if `index`
	/// lies within a marked region. For more information on marked regions, see
	/// _#mark_. The behavior of this method is unspecified if no call to
	/// an _org.antlr.v4.runtime.IntStream initializing method_ has occurred after this stream
	/// was constructed.
	///
	/// - parameter index: The absolute index to seek to.
	///
	/// - throws: _ANTLRError.illegalArgument_ if `index` is less than 0
	/// - throws: _ANTLRError.unsupportedOperation_ if the stream does not support
	/// seeking to the specified index
	///
	func seek(_ index: Int) throws

	///
	/// Returns the total number of symbols in the stream, including a single EOF
	/// symbol.
	///
	/// - throws: _ANTLRError.unsupportedOperation_ if the size of the stream is
	/// unknown.
	///
	func size() -> Int

	///
	/// Gets the name of the underlying symbol source. This method returns a
	/// non-null, non-empty string. If such a name is not known, this method
	/// returns _#UNKNOWN_SOURCE_NAME_.
	///
	func getSourceName() -> String
	}