Package org.apache.uima.cas

# Interface SelectFSs<T extends FeatureStructure>

All Superinterfaces:
  `AutoCloseable`, `BaseStream<T,Stream<T>>`, `Iterable<T>`, `Stream<T>`

All Known Implementing Classes:
  `SelectFSs_impl`

public interface SelectFSs<T extends FeatureStructure> extends Iterable<T>, Stream<T>
Collection of builder style methods to specify selection of FSs from indexes Documentation is in a chapter in the UIMA Version 3 User's Guide.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface java.util.stream.Stream

  `Stream.Builder<T extends Object>`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `SelectFSs<T>`
  `allViews()`
  Extend the selection to be over all the CAS views, not just a single view.
  `SelectFSs<T>`
  `allViews(boolean allViews)`
  Extend or not extend the selection to be over all the CAS views, not just a single view.
  `T[]`
  `asArray(Class<? super T> clazz)`
  `List<T>`
  `asList()`
  `SelectFSs<T>`
  `at(int begin, int end)`
  Subselection - specifies selecting Feature Structures having the same begin and end Requires an Annotation Index.
  `SelectFSs<T>`
  `at(AnnotationFS fs)`
  Subselection - specifies selecting Feature Structures having the same begin and end - influenced by typePriority, positionUsesType, and useAnnotationEquals Requires an Annotation Index.
  `SelectFSs<T>`
  `backwards()`
  Specifies that the iteration should run in reverse order from normal.
  `SelectFSs<T>`
  `backwards(boolean backwards)`
  Specifies that the iteration should run in the normal or reverse order.
  `SelectFSs<T>`
  `between(AnnotationFS fs1, AnnotationFS fs2)`
  Subselection - specifies selecting Feature Structures which lie between two annotations.
  `SelectFSs<T>`
  `coveredBy(int begin, int end)`
  Subselection - specifies selecting Feature Structures starting (and maybe ending) within a bounding Feature Structure Requires an Annotation Index.
  `SelectFSs<T>`
  `coveredBy(AnnotationFS fs)`
  Subselection - specifies selecting Feature Structures starting (and maybe ending) within a bounding Feature Structure - influenced by typePriority, positionUsesType, useAnnotationEquals, includeAnnotationsWithEndBeyondBounds Requires an Annotation Index.
  `SelectFSs<T>`
  `covering(int begin, int end)`
  Subselection - specifies selecting Feature Structures starting before or equal to bounding Feature Structure's begin and ending at or beyond the bounding Feature Structure's end Requires an Annotation Index.
  `SelectFSs<T>`
  `covering(AnnotationFS fs)`
  Subselection - specifies selecting Feature Structures starting before or equal to bounding Feature Structure and ending at or beyond the bounding Feature Structure - influenced by typePriority, positionUsesType, useAnnotationEquals Requires an Annotation Index.
  `SelectFSs<T>`
  `following(int position)`
  Select `annotations` that follow the specified document position (i.e.
  `SelectFSs<T>`
  `following(int position, int offset)`
  For AnnotationIndex, position to first Annotation whose begin >= position and then adjust position by the offset.
  `SelectFSs<T>`
  `following(Annotation annotation)`
  For AnnotationIndex, position to first Annotation whose begin >= fs.getEnd();
  `SelectFSs<T>`
  `following(Annotation annotation, int offset)`
  For AnnotationIndex, position to first Annotation whose begin >= fs.getEnd() and then adjust position by the offset
  `default void`
  `forEach(Consumer<? super T> action)`
  This method is required, because the 2 interfaces inherited both define this and this is needed to disambiguate Otherwise, get a compile error (but not on Eclipse...)
  `FSIterator<T>`
  `fsIterator()`
  `T`
  `get()`
  Get the first element or null if empty or the element at the first position is null.
  `T`
  `get(int offset)`
  Get the offset element or null if empty or the offset went outside the the selected elements.
  `T`
  `get(int begin, int end)`
  Position using a temporary Annotation with its begin and end set to the arguments.
  `T`
  `get(int begin, int end, int offset)`
  Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset).
  `T`
  `get(FeatureStructure fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `get(FeatureStructure fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `T`
  `get(TOP fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `get(TOP fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `SelectFSs<T>`
  `includeAnnotationsWithEndBeyondBounds()`
  Meaningful only for coveredBy, includes annotations where the end exceeds the bounding annotation's end.
  `SelectFSs<T>`
  `includeAnnotationsWithEndBeyondBounds(boolean includeAnnotationsWithEndBeyondBounds)`
  Meaningful only for coveredBy, includes or filters out annotations where the end exceeds the bounding annotation's end.
  `boolean`
  `isEmpty()`
  `SelectFSs<T>`
  `limit(int n)`
  Limits the number of Feature Structures returned by this select
  `SelectFSs<T>`
  `nonOverlapping()`
  Meaningful only for Annotation Indexes, specifies that iteration should return only annotations which don't overlap with each other.
  `SelectFSs<T>`
  `nonOverlapping(boolean nonOverlapping)`
  Meaningful only for Annotation Indexes, specifies that iteration should or should not return only annotations which don't overlap with each other.
  `SelectFSs<T>`
  `nullOK()`
  Applies to the various argument forms of the get and single methods.
  `SelectFSs<T>`
  `nullOK(boolean nullOk)`
  Applies to the various argument forms of the get and single methods.
  `SelectFSs<T>`
  `orderNotNeeded()`
  Specifies that order is not required while iterating over an otherwise ordered index.
  `SelectFSs<T>`
  `orderNotNeeded(boolean unordered)`
  Specifies that order is or is not required while iterating over an otherwise ordered index.
  `SelectFSs<T>`
  `preceding(int position)`
  Select `annotations` that precede the specified document position (i.e.
  `SelectFSs<T>`
  `preceding(int position, int offset)`
  For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, ending at the last Annotation whose end <= position.
  `SelectFSs<T>`
  `preceding(Annotation annotation)`
  For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, whose end <= fs.getBegin().
  `SelectFSs<T>`
  `preceding(Annotation annotation, int offset)`
  For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, ending at the last Annotation whose end <= fs.getBegin(), after adjusting by offset items.
  `static <U extends FeatureStructure>
  SelectFSs<U>`
  `select(FSIndex<U> index)`
  Use this static method to capture the generic argument
  `SelectFSs<T>`
  `shifted(int shiftAmount)`
  Starting Position specification - Shifts the normal start position by the shiftAmount, which may be negative.
  `T`
  `single()`
  `T`
  `single(int offset)`
  Get the offset element or null if empty or the offset went outside the the selected elements.
  `T`
  `single(int begin, int end)`
  Position using a temporary Annotation with its begin and end set to the arguments.
  `T`
  `single(int begin, int end, int offset)`
  Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset).
  `T`
  `single(FeatureStructure fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `single(FeatureStructure fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `T`
  `single(TOP fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `single(TOP fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `T`
  `singleOrNull()`
  `T`
  `singleOrNull(int offset)`
  Get the offset element or null if empty or the offset went outside the the selected elements.
  `T`
  `singleOrNull(int begin, int end)`
  Position using a temporary Annotation with its begin and end set to the arguments.
  `T`
  `singleOrNull(int begin, int end, int offset)`
  Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset).
  `T`
  `singleOrNull(FeatureStructure fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `singleOrNull(FeatureStructure fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `T`
  `singleOrNull(TOP fs)`
  Positions to the fs using moveTo(fs).
  `T`
  `singleOrNull(TOP fs, int offset)`
  Positions to the fs using moveTo(fs), followed by a shifted(offset).
  `SelectFSs<T>`
  `skipWhenSameBeginEndType()`
  Meaningful only for coveredBy and covering: if true, then returned annotations are compared equal to the bounding annotation, and if equal, they are skipped.
  `default Spliterator<T>`
  `spliterator()`
  `SelectFSs<T>`
  `startAt(int begin)`
  Starting Position specification - For Annotation Indexes, specifies which FS to start at.
  `SelectFSs<T>`
  `startAt(int begin, int end)`
  Starting Position specification - For Annotation Indexes, specifies which FS to start at.
  `SelectFSs<T>`
  `startAt(int begin, int end, int shift)`
  Starting Position specification - A combination of startAt followed by a shift Requires an Annotation Index.
  `SelectFSs<T>`
  `startAt(FeatureStructure fs)`
  Starting Position specification - For ordered sources, specifies which FS to start at.
  `SelectFSs<T>`
  `startAt(FeatureStructure fs, int shift)`
  Starting Position specification - A combination of startAt followed by a shift Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted This versions avoids a runtime cast check.
  `SelectFSs<T>`
  `startAt(TOP fs)`
  Starting Position specification - For ordered sources, specifies which FS to start at.
  `SelectFSs<T>`
  `startAt(TOP fs, int shift)`
  Starting Position specification - A combination of startAt followed by a shift Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted
  `SelectFSs<T>`
  `typePriority()`
  Specify that type priority should be included when comparing two Feature Structures when moving to the leftmost among otherwise equal items for moveTo(fs).
  `SelectFSs<T>`
  `typePriority(boolean typePriority)`
  Specify that type priority should or should not be included when comparing two Feature Structures while positioning an iterator
  `SelectFSs<T>`
  `useAnnotationEquals(boolean useAnnotationEquals)`
  Meaningful only for coveredBy: if true, then returned annotations are compared to the bounding annotation using the specified kind of equal comparison, and if equal, they are skipped.

  ### Methods inherited from interface java.util.stream.BaseStream

  `close, isParallel, iterator, onClose, parallel, sequential, unordered`

  ### Methods inherited from interface java.lang.Iterable

  `iterator`

  ### Methods inherited from interface java.util.stream.Stream

  `allMatch, anyMatch, collect, collect, count, distinct, dropWhile, filter, findAny, findFirst, flatMap, flatMapToDouble, flatMapToInt, flatMapToLong, forEachOrdered, limit, map, mapMulti, mapMultiToDouble, mapMultiToInt, mapMultiToLong, mapToDouble, mapToInt, mapToLong, max, min, noneMatch, peek, reduce, reduce, reduce, skip, sorted, sorted, takeWhile, toArray, toArray, toList`

- ## Method Details

  - ### typePriority

    SelectFSs<T> typePriority()
    Specify that type priority should be included when comparing two Feature Structures when moving to the leftmost among otherwise equal items for moveTo(fs).

    Default is to not include type priority.

    Returns:
      the updated SelectFSs object

  - ### typePriority

    SelectFSs<T> typePriority(boolean typePriority)
    Specify that type priority should or should not be included when comparing two Feature Structures while positioning an iterator

    Default is to not include type priority.

    Parameters:
      `typePriority` - if true says to include the type priority
    Returns:
      the updated SelectFSs object

  - ### nonOverlapping

    SelectFSs<T> nonOverlapping()
    Meaningful only for Annotation Indexes, specifies that iteration should return only annotations which don't overlap with each other. Also known as "unambiguous".

    Default is to not have this filter.

    Returns:
      the updated SelectFSs object

  - ### nonOverlapping

    SelectFSs<T> nonOverlapping(boolean nonOverlapping)
    Meaningful only for Annotation Indexes, specifies that iteration should or should not return only annotations which don't overlap with each other. Also known as "unambiguous".

    Default is to not have this filter.

    Parameters:
      `nonOverlapping` - true to specify filtering for only non-overlapping annotations.
    Returns:
      the updated SelectFSs object

  - ### includeAnnotationsWithEndBeyondBounds

    SelectFSs<T> includeAnnotationsWithEndBeyondBounds()
    Meaningful only for coveredBy, includes annotations where the end exceeds the bounding annotation's end.

    Default is to NOT include annotations whose end exceeds the bounding annotation's end.

    Returns:
      the updated SelectFSs object

  - ### includeAnnotationsWithEndBeyondBounds

    SelectFSs<T> includeAnnotationsWithEndBeyondBounds(boolean includeAnnotationsWithEndBeyondBounds)
    Meaningful only for coveredBy, includes or filters out annotations where the end exceeds the bounding annotation's end.

    Default is to NOT include annotations whose end exceeds the bounding annotation's end.

    Parameters:
      `includeAnnotationsWithEndBeyondBounds` - false to filter out annotations whose end exceeds the bounding annotation's end
    Returns:
      the updated SelectFSs object

  - ### skipWhenSameBeginEndType

    SelectFSs<T> skipWhenSameBeginEndType()
    Meaningful only for coveredBy and covering: if true, then returned annotations are compared equal to the bounding annotation, and if equal, they are skipped.

    Default is to use feature structure identity comparison (same id()s), not equals, when doing the test to see if an annotation should be skipped.

    This is identical to useAnnotationEquals(true).

    Returns:
      the updated SelectFSs object

  - ### useAnnotationEquals

    SelectFSs<T> useAnnotationEquals(boolean useAnnotationEquals)
    Meaningful only for coveredBy: if true, then returned annotations are compared to the bounding annotation using the specified kind of equal comparison, and if equal, they are skipped.

    Default is to use feature structure identity comparison (same id()s), not equals, when doing the test to see if an annotation should be skipped.

    Parameters:
      `useAnnotationEquals` - if true, use equals, if false, use id() ==.
    Returns:
      the updated SelectFSs object

  - ### allViews

    SelectFSs<T> allViews()
    Extend the selection to be over all the CAS views, not just a single view.

    Default is that the selection is just for one CAS view

    Returns:
      the updated SelectFSs object

  - ### allViews

    SelectFSs<T> allViews(boolean allViews)
    Extend or not extend the selection to be over all the CAS views, not just a single view.

    Default is that the selection is just for one CAS view

    Parameters:
      `allViews` - true to extend the selection.
    Returns:
      the updated SelectFSs object

  - ### nullOK

    SelectFSs<T> nullOK()
    Applies to the various argument forms of the get and single methods. Indicates that a null value should not throw an exception.

    Calling this method is equivalent to nullOK(true). If never called, nulls are not OK by default.

    Returns:
      the updated SelectFSs object

  - ### nullOK

    SelectFSs<T> nullOK(boolean nullOk)
    Applies to the various argument forms of the get and single methods. Indicates that a null value should or should not throw an exception.

    Default: null is not OK as a value

    Parameters:
      `nullOk` - true if null is an ok value.
    Returns:
      the updated SelectFSs object

  - ### orderNotNeeded

    SelectFSs<T> orderNotNeeded()
    Specifies that order is not required while iterating over an otherwise ordered index. This can be a performance boost for hierarchically nested types.

    Default: order is required by default, when iterating over an ordered index.

    Returns:
      the updated SelectFSs object

  - ### orderNotNeeded

    SelectFSs<T> orderNotNeeded(boolean unordered)
    Specifies that order is or is not required while iterating over an otherwise ordered index. This can be a performance boost for hierarchically nested types.

    Default: order is required by default, when iterating over an ordered index.

    Parameters:
      `unordered` - true means order is not needed.
    Returns:
      the updated SelectFSs object

  - ### backwards

    SelectFSs<T> backwards()
    Specifies that the iteration should run in reverse order from normal. Note that this does not compose; two calls to this will still result in the iteration running in reverse order.
    Returns:
      the updated SelectFSs object

  - ### backwards

    SelectFSs<T> backwards(boolean backwards)
    Specifies that the iteration should run in the normal or reverse order. Note that this does not compose.
    Parameters:
      `backwards` - true to run in reverse order
    Returns:
      the updated SelectFSs object

  - ### shifted

    SelectFSs<T> shifted(int shiftAmount)
    Starting Position specification - Shifts the normal start position by the shiftAmount, which may be negative. Repeated calls to this just replaces the requested shift amount; a single shift only occurs when a result is obtained.
    Parameters:
      `shiftAmount` - the amount to shift; this many Feature Structures which normally would be returned are instead skipped.
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(TOP fs)
    Starting Position specification - For ordered sources, specifies which FS to start at. Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted
    Parameters:
      `fs` - a Feature Structure specifying a starting position.
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(FeatureStructure fs)
    Starting Position specification - For ordered sources, specifies which FS to start at. Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted
    Parameters:
      `fs` - a Feature Structure specifying a starting position.
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(int begin)
    Starting Position specification - For Annotation Indexes, specifies which FS to start at. This method is incompatible with `typePriority()` and turns type priorities off implicitly. Do not turn type priorities back on. Positions to the leftmost (if there are multiple equal ones) Annotation whose begin is >= begin
    Parameters:
      `begin` - the begin bound
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(int begin, int end)
    Starting Position specification - For Annotation Indexes, specifies which FS to start at.
    Parameters:
      `begin` - the begin bound
      `end` - the end bound
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(TOP fs, int shift)
    Starting Position specification - A combination of startAt followed by a shift Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted
    Parameters:
      `fs` - a Feature Structure specifying a starting position.
      `shift` - the amount to shift; this many Feature Structures which normally would be returned are instead skipped.
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(FeatureStructure fs, int shift)
    Starting Position specification - A combination of startAt followed by a shift Requires an ordered index not necessarily AnnotationIndex, not necessarily sorted This versions avoids a runtime cast check.
    Parameters:
      `fs` - a Feature Structure specifying a starting position.
      `shift` - the amount to shift; this many Feature Structures which normally would be returned are instead skipped.
    Returns:
      the updated SelectFSs object

  - ### startAt

    SelectFSs<T> startAt(int begin, int end, int shift)
    Starting Position specification - A combination of startAt followed by a shift Requires an Annotation Index.
    Parameters:
      `begin` - the begin bound
      `end` - the end bound
      `shift` - the amount to shift; this many Feature Structures which normally would be returned are instead skipped.
    Returns:
      the updated SelectFSs object

  - ### limit

    SelectFSs<T> limit(int n)
    Limits the number of Feature Structures returned by this select
    Parameters:
      `n` - the maximum number of feature structures returned. This must be a value >= 0.
    Returns:
      the updated SelectFSs object

  - ### at

    SelectFSs<T> at(AnnotationFS fs)
    Subselection - specifies selecting Feature Structures having the same begin and end - influenced by typePriority, positionUsesType, and useAnnotationEquals Requires an Annotation Index.
    Parameters:
      `fs` - specifies the bounds.
    Returns:
      the updated SelectFSs object

  - ### at

    SelectFSs<T> at(int begin, int end)
    Subselection - specifies selecting Feature Structures having the same begin and end Requires an Annotation Index. - influenced by typePriority, positionUsesType, and useAnnotationEquals
    Parameters:
      `begin` - the begin bound
      `end` - the end bound
    Returns:
      the updated SelectFSs object

  - ### coveredBy

    SelectFSs<T> coveredBy(AnnotationFS fs)
    Subselection - specifies selecting Feature Structures starting (and maybe ending) within a bounding Feature Structure - influenced by typePriority, positionUsesType, useAnnotationEquals, includeAnnotationsWithEndBeyondBounds Requires an Annotation Index.
    Parameters:
      `fs` - specifies the bounds.
    Returns:
      the updated SelectFSs object

  - ### coveredBy

    SelectFSs<T> coveredBy(int begin, int end)
    Subselection - specifies selecting Feature Structures starting (and maybe ending) within a bounding Feature Structure Requires an Annotation Index.
    Parameters:
      `begin` - the begin bound
      `end` - the end bound
    Returns:
      the updated SelectFSs object

  - ### covering

    SelectFSs<T> covering(AnnotationFS fs)
    Subselection - specifies selecting Feature Structures starting before or equal to bounding Feature Structure and ending at or beyond the bounding Feature Structure - influenced by typePriority, positionUsesType, useAnnotationEquals Requires an Annotation Index.
    Parameters:
      `fs` - specifies the bounds.
    Returns:
      the updated SelectFSs object

  - ### covering

    SelectFSs<T> covering(int begin, int end)
    Subselection - specifies selecting Feature Structures starting before or equal to bounding Feature Structure's begin and ending at or beyond the bounding Feature Structure's end Requires an Annotation Index.
    Parameters:
      `begin` - the begin bound
      `end` - the end bound
    Returns:
      the updated SelectFSs object

  - ### between

    SelectFSs<T> between(AnnotationFS fs1, AnnotationFS fs2)
    Subselection - specifies selecting Feature Structures which lie between two annotations. A bounding Annotation is constructed whose begin is the end of fs1, and whose end is the begin of fs2. Requires an Annotation Index.

    If fs1 > fs2, they are swapped.

    Parameters:
      `fs1` - the beginning bound
      `fs2` - the ending bound
    Returns:
      the updated SelectFSs object

  - ### following

    SelectFSs<T> following(Annotation annotation)
    For AnnotationIndex, position to first Annotation whose begin >= fs.getEnd();
    Parameters:
      `annotation` - the Annotation to follow
    Returns:
      the updated SelectFSs object

  - ### following

    SelectFSs<T> following(int position)
    Select `annotations` that follow the specified document position (i.e. character offset). This is equivalent to performing a `following(new Annotation(jcas, 0, position)`, so all annotations starting at `position` or after are returned, including zero-width annotations.
    Parameters:
      `position` - start following this position
    Returns:
      the updated SelectFSs object

  - ### following

    SelectFSs<T> following(Annotation annotation, int offset)
    For AnnotationIndex, position to first Annotation whose begin >= fs.getEnd() and then adjust position by the offset
    Parameters:
      `annotation` - start following this Annotation, adjusted for the offset
      `offset` - positive or negative shift amount to adjust starting position
    Returns:
      the updated SelectFSs object

  - ### following

    SelectFSs<T> following(int position, int offset)
    For AnnotationIndex, position to first Annotation whose begin >= position and then adjust position by the offset.
    Parameters:
      `position` - start following this position, adjusted for the offset
      `offset` - positive or negative shift amount to adjust starting position
    Returns:
      the updated SelectFSs object

  - ### preceding

    SelectFSs<T> preceding(Annotation annotation)
    For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, whose end <= fs.getBegin(). Annotations whose end > fs.getBegin() are skipped.
    Parameters:
      `annotation` - the Annotation to use as the position to start before.
    Returns:
      the updated SelectFSs object

  - ### preceding

    SelectFSs<T> preceding(int position)
    Select `annotations` that precede the specified document position (i.e. character offset). This is equivalent to performing a `preceding(new Annotation(jcas, position, Integer.MAX_VALUE)`, so all annotations ending at `position` or before are returned, including zero-width annotations.
    Parameters:
      `position` - start following this position
    Returns:
      the updated SelectFSs object

  - ### preceding

    SelectFSs<T> preceding(Annotation annotation, int offset)
    For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, ending at the last Annotation whose end <= fs.getBegin(), after adjusting by offset items. Annotations whose end > fs.getBegin() are skipped (including during the offset positioning)
    Parameters:
      `annotation` - the Annotation to use as the position to start before.
      `offset` - the offset adjustment, positive or negative. Positive moves backwards.
    Returns:
      the updated SelectFSs object

  - ### preceding

    SelectFSs<T> preceding(int position, int offset)
    For AnnotationIndex, set up a selection that will go from the beginning to the first Annotation to the left of the specified position, ending at the last Annotation whose end <= position. after adjusting by offset items. Annotations whose end > position are skipped (including during the offset positioning)
    Parameters:
      `position` - the position to start before.
      `offset` - the offset adjustment, positive or negative. Positive moves backwards.
    Returns:
      the updated SelectFSs object

  - ### fsIterator

    FSIterator<T> fsIterator()
    Returns:
      an FSIterator over the selection. The iterator is set up depending on preceding configuration calls to this SelectFSs instance.

  - ### asList

    List<T> asList()
    Returns:
      a List object whose elements represent the selection.

  - ### asArray

    T[] asArray(Class<? super T> clazz)
    Parameters:
      `clazz` - the class of the type of the elements
    Returns:
      a Array object representation of the elements of the selection.

  - ### get

    T get()
    Get the first element or null if empty or the element at the first position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned.
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - conditioned on nullOK == false, and null being returned or the selection is empty.

  - ### single

    T single()
    Returns:
      first element, verifying that the size of the selection is 1 (or maybe 0)
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false ) if element is null or if there is more than 1 element in the selection, or if the selection is empty

  - ### singleOrNull

    T singleOrNull()
    Returns:
      first element, which may be null, or null if selection is empty.
    Throws:
      `CASRuntimeException` - if there is more than 1 element in the selection.

  - ### get

    T get(int offset)
    Get the offset element or null if empty or the offset went outside the the selected elements.

    If nullOK is false, then throws CASRuntimeException if null would have been returned, or the selection is empty, or doesn't have enough elements to satisfy the positioning.

    Parameters:
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null
    Throws:
      `CASRuntimeException` - conditioned on nullOK == false, and null being returned or the selection is empty, or the offset positioning going outside the elements in the selection.

  - ### single

    T single(int offset)
    Get the offset element or null if empty or the offset went outside the the selected elements.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive, reverse direction if offset is negative) then throw an exception.

    If nullOK is false, then throws CASRuntimeException if null would have been returned, or the selection is empty, or doesn't have enough elements to satisfy the positioning.

    Parameters:
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive, reverse direction if offset is negative) or (conditioned on nullOK == false) null being returned or the selection is empty, or the offset positioning going outside the elements in the selection.

  - ### singleOrNull

    T singleOrNull(int offset)
    Get the offset element or null if empty or the offset went outside the the selected elements.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive, reverse direction if offset is negative) then throw an exception.

    Parameters:
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive, reverse direction if offset is negative)

  - ### get

    T get(TOP fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned. This versions avoids a runtime cast check.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### get

    T get(FeatureStructure fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### single

    T single(TOP fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned. This versions avoids a runtime cast check.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned or (conditioned on nullOK == false) and null being returned or the selection is empty.

  - ### single

    T single(FeatureStructure fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned or (conditioned on nullOK == false) and null being returned or the selection is empty.

  - ### singleOrNull

    T singleOrNull(TOP fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null. This versions avoids a runtime cast check.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned

  - ### singleOrNull

    T singleOrNull(FeatureStructure fs)
    Positions to the fs using moveTo(fs). Get the element at that position or null if empty or the element at that position is null.
    Parameters:
      `fs` - the positioning Feature Structure
    Returns:
      first element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned

  - ### get

    T get(TOP fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned. This versions avoids a runtime cast check.
    Parameters:
      `fs` - where to move to
      `offset` - the offset move after positioning to fs, may be 0 or positive or negative
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### get

    T get(FeatureStructure fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned.
    Parameters:
      `fs` - where to move to
      `offset` - the offset move after positioning to fs, may be 0 or positive or negative
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### single

    T single(TOP fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    If nullOK is false, then throws CASRuntimeException if null would have been returned. This versions avoids a runtime cast check.

    Parameters:
      `fs` - the positioning Feature Structure
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned or (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### single

    T single(FeatureStructure fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    If nullOK is false, then throws CASRuntimeException if null would have been returned.

    Parameters:
      `fs` - the positioning Feature Structure
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned or (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### singleOrNull

    T singleOrNull(TOP fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    This versions avoids a runtime cast check.

    Parameters:
      `fs` - the positioning Feature Structure
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned

  - ### singleOrNull

    T singleOrNull(FeatureStructure fs, int offset)
    Positions to the fs using moveTo(fs), followed by a shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    Parameters:
      `fs` - the positioning Feature Structure
      `offset` - the offset adjustment, positive or negative.
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned

  - ### get

    T get(int begin, int end)
    Position using a temporary Annotation with its begin and end set to the arguments. Gets the element at that position or null if empty or the element at that position is null. if nullOK is false, then throws CASRuntimeException if null would have been returned. This versions avoids a runtime cast check.
    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - conditioned on nullOK == false, and null being returned or the selection is empty.

  - ### single

    T single(int begin, int end)
    Position using a temporary Annotation with its begin and end set to the arguments. Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element following the one being returned then throw an exception.

    if nullOK is false, then throws CASRuntimeException if null would have been returned.

    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned or (conditioned on nullOK == false) null being returned or the selection is empty.

  - ### singleOrNull

    T singleOrNull(int begin, int end)
    Position using a temporary Annotation with its begin and end set to the arguments. Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element following the one being returned then throw an exception.

    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element following the one being returned

  - ### get

    T get(int begin, int end, int offset)
    Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
      `offset` - the amount (positive or negative or 0) passed as an argument to shifted(int)
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - (conditioned on nullOK == false) if null being returned or the selection is empty.

  - ### single

    T single(int begin, int end, int offset)
    Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
      `offset` - the amount (positive or negative or 0) passed as an argument to shifted(int)
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned or (conditioned on nullOK == false) if null being returned or the selection is empty.

  - ### singleOrNull

    T singleOrNull(int begin, int end, int offset)
    Position using a temporary Annotation with its begin and end set to the arguments, followed by shifted(offset). Gets the element at that position or null if empty or the element at that position is null.

    If, after positioning, there is another element next to the one being returned (in the forward direction if offset is positive or 0, reverse direction if offset is negative) then throw an exception.

    Parameters:
      `begin` - the begin position of the temporary Annotation
      `end` - the end position of the temporary Annotation
      `offset` - the amount (positive or negative or 0) passed as an argument to shifted(int)
    Returns:
      the selected element or null if empty
    Throws:
      `CASRuntimeException` - if, after positioning, there is another element next to the one being returned

  - ### spliterator

    default Spliterator<T> spliterator()
    Specified by:
      `spliterator` in interface `BaseStream<T extends FeatureStructure,Stream<T extends FeatureStructure>>`
    Specified by:
      `spliterator` in interface `Iterable<T extends FeatureStructure>`

  - ### select

    static <U extends FeatureStructure> SelectFSs<U> select(FSIndex<U> index)
    Use this static method to capture the generic argument
    Type Parameters:
      `U` - generic type of index
    Parameters:
      `index` - - the index to select over as a source
    Returns:
      - a SelectFSs instance

  - ### forEach

    default void forEach(Consumer<? super T> action)
    This method is required, because the 2 interfaces inherited both define this and this is needed to disambiguate Otherwise, get a compile error (but not on Eclipse...)
    Specified by:
      `forEach` in interface `Iterable<T extends FeatureStructure>`
    Specified by:
      `forEach` in interface `Stream<T extends FeatureStructure>`

  - ### isEmpty

    boolean isEmpty()
    Returns:
      true if the selection is empty