Package org.apache.lucene.queries.intervals

# Class Intervals

java.lang.Object
org.apache.lucene.queries.intervals.Intervals

public final class Intervals extends Object
Factory functions for creating `interval sources`.

These sources implement minimum-interval algorithms taken from the paper Efficient Optimally Lazy Algorithms for Minimal-Interval Semantics

Note: by default, sources that are sensitive to internal gaps (e.g. `PHRASE` and `MAXGAPS`) will rewrite their sub-sources so that disjunctions of different lengths are pulled up to the top of the interval tree. For example, `PHRASE(or(PHRASE("a", "b", "c"), "b"), "c")` will automatically rewrite itself to `OR(PHRASE("a", "b", "c", "c"), PHRASE("b", "c"))` to ensure that documents containing `"b c"` are matched. This can lead to less efficient queries, as more terms need to be loaded (for example, the `"c"` iterator above is loaded twice), so if you care more about speed than about accuracy you can use the `or(boolean, IntervalsSource...)` factory method to prevent rewriting.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_MAX_EXPANSIONS`
  The default number of expansions in: `multiterm(CompiledAutomaton, String)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static IntervalsSource`
  `after(IntervalsSource source, IntervalsSource reference)`
  Returns intervals from the source that appear after intervals from the reference
  `static IntervalsSource`
  `analyzedText(String text, Analyzer analyzer, String field, int maxGaps, boolean ordered)`
  Returns intervals that correspond to tokens from a `TokenStream` returned for `text` by applying the provided `Analyzer` as if `text` was the content of the given `field`.
  `static IntervalsSource`
  `analyzedText(TokenStream tokenStream, int maxGaps, boolean ordered)`
  Returns intervals that correspond to tokens from the provided `TokenStream`.
  `static IntervalsSource`
  `atLeast(int minShouldMatch, IntervalsSource... sources)`
  Return intervals that span combinations of intervals from `minShouldMatch` of the sources
  `static IntervalsSource`
  `before(IntervalsSource source, IntervalsSource reference)`
  Returns intervals from the source that appear before intervals from the reference
  `static IntervalsSource`
  `containedBy(IntervalsSource small, IntervalsSource big)`
  Create a contained-by `IntervalsSource`
  `static IntervalsSource`
  `containing(IntervalsSource big, IntervalsSource small)`
  Create a containing `IntervalsSource`
  `static IntervalsSource`
  `extend(IntervalsSource source, int before, int after)`
  Create an `IntervalsSource` that wraps another source, extending its intervals by a number of positions before and after.
  `static IntervalsSource`
  `fixField(String field, IntervalsSource source)`
  Create an `IntervalsSource` that always returns intervals from a specific field
  `static IntervalsSource`
  `fuzzyTerm(String term, int maxEdits)`
  A fuzzy term `IntervalsSource` matches the disjunction of intervals of terms that are within the specified `maxEdits` from the provided term.
  `static IntervalsSource`
  `fuzzyTerm(String term, int maxEdits, int prefixLength, boolean transpositions, int maxExpansions)`
  A fuzzy term `IntervalsSource` matches the disjunction of intervals of terms that are within the specified `maxEdits` from the provided term.
  `static IntervalsSource`
  `maxgaps(int gaps, IntervalsSource subSource)`
  Create an `IntervalsSource` that filters a sub-source by its gaps
  `static IntervalsSource`
  `maxwidth(int width, IntervalsSource subSource)`
  Create an `IntervalsSource` that filters a sub-source by the width of its intervals
  `static IntervalsSource`
  `multiterm(CompiledAutomaton ca, int maxExpansions, String pattern)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that are accepted by the given automaton
  `static IntervalsSource`
  `multiterm(CompiledAutomaton ca, String pattern)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that are accepted by the given automaton
  `static IntervalsSource`
  `noIntervals(String reason)`
  Returns a source that produces no intervals
  `static IntervalsSource`
  `nonOverlapping(IntervalsSource minuend, IntervalsSource subtrahend)`
  Create a non-overlapping IntervalsSource
  `static IntervalsSource`
  `notContainedBy(IntervalsSource small, IntervalsSource big)`
  Create a not-contained-by `IntervalsSource`
  `static IntervalsSource`
  `notContaining(IntervalsSource minuend, IntervalsSource subtrahend)`
  Create a not-containing `IntervalsSource`
  `static IntervalsSource`
  `notWithin(IntervalsSource minuend, int positions, IntervalsSource subtrahend)`
  Create a not-within `IntervalsSource`
  `static IntervalsSource`
  `or(boolean rewrite, List<IntervalsSource> subSources)`
  Return an `IntervalsSource` over the disjunction of a set of sub-sources
  `static IntervalsSource`
  `or(boolean rewrite, IntervalsSource... subSources)`
  Return an `IntervalsSource` over the disjunction of a set of sub-sources
  `static IntervalsSource`
  `or(List<IntervalsSource> subSources)`
  Return an `IntervalsSource` over the disjunction of a set of sub-sources
  `static IntervalsSource`
  `or(IntervalsSource... subSources)`
  Return an `IntervalsSource` over the disjunction of a set of sub-sources
  `static IntervalsSource`
  `ordered(IntervalsSource... subSources)`
  Create an ordered `IntervalsSource`
  `static IntervalsSource`
  `overlapping(IntervalsSource source, IntervalsSource reference)`
  Returns intervals from a source that overlap with intervals from another source
  `static IntervalsSource`
  `phrase(String... terms)`
  Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of terms
  `static IntervalsSource`
  `phrase(IntervalsSource... subSources)`
  Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of `interval sources`
  `static IntervalsSource`
  `prefix(BytesRef prefix)`
  Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix
  `static IntervalsSource`
  `prefix(BytesRef prefix, int maxExpansions)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix
  `static IntervalsSource`
  `range(BytesRef lowerTerm, BytesRef upperTerm, boolean includeLower, boolean includeUpper)`
  Return an `IntervalsSource` over the disjunction of all terms that fall within the given range
  `static IntervalsSource`
  `range(BytesRef lowerTerm, BytesRef upperTerm, boolean includeLower, boolean includeUpper, int maxExpansions)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that fall within the given range
  `static IntervalsSource`
  `regexp(BytesRef regexp)`
  Return an `IntervalsSource` over the disjunction of all terms that match a regular expression
  `static IntervalsSource`
  `regexp(BytesRef regexp, int maxExpansions)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that match a regular expression
  `static IntervalsSource`
  `term(String term)`
  Return an `IntervalsSource` exposing intervals for a term
  `static IntervalsSource`
  `term(String term, Predicate<BytesRef> payloadFilter)`
  Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position
  `static IntervalsSource`
  `term(BytesRef term)`
  Return an `IntervalsSource` exposing intervals for a term
  `static IntervalsSource`
  `term(BytesRef term, Predicate<BytesRef> payloadFilter)`
  Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position
  `static IntervalsSource`
  `unordered(IntervalsSource... subSources)`
  Create an unordered `IntervalsSource`.
  `static IntervalsSource`
  `unorderedNoOverlaps(IntervalsSource a, IntervalsSource b)`
  Create an unordered `IntervalsSource` allowing no overlaps between subsources
  `static IntervalsSource`
  `wildcard(BytesRef wildcard)`
  Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob
  `static IntervalsSource`
  `wildcard(BytesRef wildcard, int maxExpansions)`
  Expert: Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob
  `static IntervalsSource`
  `within(IntervalsSource source, int positions, IntervalsSource reference)`
  Returns intervals of the source that appear within a set number of positions of intervals from the reference

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

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

- ## Field Details

  - ### DEFAULT_MAX_EXPANSIONS

    public static final int DEFAULT_MAX_EXPANSIONS
    The default number of expansions in:
    - `multiterm(CompiledAutomaton, String)`
    See Also:
      - Constant Field Values

- ## Method Details

  - ### term

    public static IntervalsSource term(BytesRef term)
    Return an `IntervalsSource` exposing intervals for a term

  - ### term

    public static IntervalsSource term(String term)
    Return an `IntervalsSource` exposing intervals for a term

  - ### term

    public static IntervalsSource term(String term, Predicate<BytesRef> payloadFilter)
    Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position

  - ### term

    public static IntervalsSource term(BytesRef term, Predicate<BytesRef> payloadFilter)
    Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position

  - ### phrase

    public static IntervalsSource phrase(String... terms)
    Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of terms

  - ### phrase

    public static IntervalsSource phrase(IntervalsSource... subSources)
    Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of `interval sources`

  - ### or

    public static IntervalsSource or(IntervalsSource... subSources)
    Return an `IntervalsSource` over the disjunction of a set of sub-sources

    Automatically rewrites if wrapped by an interval source that is sensitive to internal gaps

  - ### or

    public static IntervalsSource or(boolean rewrite, IntervalsSource... subSources)
    Return an `IntervalsSource` over the disjunction of a set of sub-sources
    Parameters:
      `rewrite` - if `false`, do not rewrite intervals that are sensitive to internal gaps; this may run more efficiently, but can miss valid hits due to minimization
      `subSources` - the sources to combine

  - ### or

    public static IntervalsSource or(List<IntervalsSource> subSources)
    Return an `IntervalsSource` over the disjunction of a set of sub-sources

  - ### or

    public static IntervalsSource or(boolean rewrite, List<IntervalsSource> subSources)
    Return an `IntervalsSource` over the disjunction of a set of sub-sources
    Parameters:
      `rewrite` - if `false`, do not rewrite intervals that are sensitive to internal gaps; this may run more efficiently, but can miss valid hits due to minimization
      `subSources` - the sources to combine

  - ### prefix

    public static IntervalsSource prefix(BytesRef prefix)
    Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix
    Throws:
      `IllegalStateException` - if the prefix expands to more than `DEFAULT_MAX_EXPANSIONS` terms

  - ### prefix

    public static IntervalsSource prefix(BytesRef prefix, int maxExpansions)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix

    WARNING: Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

    Parameters:
      `prefix` - the prefix to expand
      `maxExpansions` - the maximum number of terms to expand to
    Throws:
      `IllegalStateException` - if the prefix expands to more than `maxExpansions` terms

  - ### wildcard

    public static IntervalsSource wildcard(BytesRef wildcard)
    Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob
    Throws:
      `IllegalStateException` - if the wildcard glob expands to more than `DEFAULT_MAX_EXPANSIONS` terms
    See Also:
      - `for glob format`

  - ### wildcard

    public static IntervalsSource wildcard(BytesRef wildcard, int maxExpansions)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob

    WARNING: Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

    Parameters:
      `wildcard` - the glob to expand
      `maxExpansions` - the maximum number of terms to expand to
    Throws:
      `IllegalStateException` - if the wildcard glob expands to more than `maxExpansions` terms
    See Also:
      - `for glob format`

  - ### regexp

    public static IntervalsSource regexp(BytesRef regexp)
    Return an `IntervalsSource` over the disjunction of all terms that match a regular expression
    Parameters:
      `regexp` - regular expression
    Throws:
      `IllegalStateException` - if the regex expands to more than `DEFAULT_MAX_EXPANSIONS` terms
    See Also:
      - `for regexp format`

  - ### regexp

    public static IntervalsSource regexp(BytesRef regexp, int maxExpansions)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that match a regular expression

    WARNING: Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

    Parameters:
      `regexp` - regular expression
      `maxExpansions` - the maximum number of terms to expand to
    Throws:
      `IllegalStateException` - if the regex expands to more than `DEFAULT_MAX_EXPANSIONS` terms
    See Also:
      - `for regexp format`

  - ### range

    public static IntervalsSource range(BytesRef lowerTerm, BytesRef upperTerm, boolean includeLower, boolean includeUpper)
    Return an `IntervalsSource` over the disjunction of all terms that fall within the given range
    Parameters:
      `lowerTerm` - The term text at the lower end of the range; can be `null` to indicate an open-ended range at this end
      `upperTerm` - The term text at the upper end of the range; can be `null` to indicate an open-ended range at this end
      `includeLower` - If true, the `lowerTerm` is included in the range
      `includeUpper` - If true, the `upperTerm` is included in the range
    Throws:
      `IllegalStateException` - if the range expands to more than `DEFAULT_MAX_EXPANSIONS` terms

  - ### range

    public static IntervalsSource range(BytesRef lowerTerm, BytesRef upperTerm, boolean includeLower, boolean includeUpper, int maxExpansions)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that fall within the given range

    WARNING: Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

    Parameters:
      `lowerTerm` - The term text at the lower end of the range; can be `null` to indicate an open-ended range at this end
      `upperTerm` - The term text at the upper end of the range; can be `null` to indicate an open-ended range at this end
      `includeLower` - If true, the `lowerTerm` is included in the range
      `includeUpper` - If true, the `upperTerm` is included in the range
      `maxExpansions` - the maximum number of terms to expand to
    Throws:
      `IllegalStateException` - if the wildcard glob expands to more than `maxExpansions` terms

  - ### fuzzyTerm

    public static IntervalsSource fuzzyTerm(String term, int maxEdits)
    A fuzzy term `IntervalsSource` matches the disjunction of intervals of terms that are within the specified `maxEdits` from the provided term.
    Parameters:
      `term` - the term to search for
      `maxEdits` - must be `>= 0` and `<=` `LevenshteinAutomata.MAXIMUM_SUPPORTED_DISTANCE`, use `FuzzyQuery.defaultMaxEdits` for the default, if needed.
    See Also:
      - `fuzzyTerm(String, int, int, boolean, int)`

  - ### fuzzyTerm

    public static IntervalsSource fuzzyTerm(String term, int maxEdits, int prefixLength, boolean transpositions, int maxExpansions)
    A fuzzy term `IntervalsSource` matches the disjunction of intervals of terms that are within the specified `maxEdits` from the provided term.

    The implementation is delegated to a `multiterm(CompiledAutomaton, int, String)` interval source, with an automaton sourced from `FuzzyQuery`.

    Parameters:
      `term` - the term to search for
      `maxEdits` - must be `>= 0` and `<=` `LevenshteinAutomata.MAXIMUM_SUPPORTED_DISTANCE`, use `FuzzyQuery.defaultMaxEdits` for the default, if needed.
      `prefixLength` - length of common (non-fuzzy) prefix
      `transpositions` - true if transpositions should be treated as a primitive edit operation. If this is false, comparisons will implement the classic Levenshtein algorithm.
      `maxExpansions` - the maximum number of terms to match. Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

  - ### multiterm

    public static IntervalsSource multiterm(CompiledAutomaton ca, String pattern)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that are accepted by the given automaton
    Parameters:
      `ca` - an automaton accepting matching terms
      `pattern` - string representation of the given automaton, mostly used in exception messages
    Throws:
      `IllegalStateException` - if the automaton accepts more than `DEFAULT_MAX_EXPANSIONS` terms

  - ### multiterm

    public static IntervalsSource multiterm(CompiledAutomaton ca, int maxExpansions, String pattern)
    Expert: Return an `IntervalsSource` over the disjunction of all terms that are accepted by the given automaton

    WARNING: Setting `maxExpansions` to higher than the default value of `DEFAULT_MAX_EXPANSIONS` can be both slow and memory-intensive

    Parameters:
      `ca` - an automaton accepting matching terms
      `maxExpansions` - the maximum number of terms to expand to
      `pattern` - string representation of the given automaton, mostly used in exception messages
    Throws:
      `IllegalStateException` - if the automaton accepts more than `maxExpansions` terms

  - ### maxwidth

    public static IntervalsSource maxwidth(int width, IntervalsSource subSource)
    Create an `IntervalsSource` that filters a sub-source by the width of its intervals
    Parameters:
      `width` - the maximum width of intervals in the sub-source to filter
      `subSource` - the sub-source to filter

  - ### maxgaps

    public static IntervalsSource maxgaps(int gaps, IntervalsSource subSource)
    Create an `IntervalsSource` that filters a sub-source by its gaps
    Parameters:
      `gaps` - the maximum number of gaps in the sub-source to filter
      `subSource` - the sub-source to filter

  - ### extend

    public static IntervalsSource extend(IntervalsSource source, int before, int after)
    Create an `IntervalsSource` that wraps another source, extending its intervals by a number of positions before and after.

    This can be useful for adding defined gaps in a block query; for example, to find 'a b [2 arbitrary terms] c', you can call:

           Intervals.phrase(Intervals.term("a"), Intervals.extend(Intervals.term("b"), 0, 2), Intervals.term("c"));

    Note that calling `IntervalIterator.gaps()` on iterators returned by this source delegates directly to the wrapped iterator, and does not include the extensions.
    Parameters:
      `source` - the source to extend
      `before` - how many positions to extend before the delegated interval
      `after` - how many positions to extend after the delegated interval

  - ### ordered

    public static IntervalsSource ordered(IntervalsSource... subSources)
    Create an ordered `IntervalsSource`

    Returns intervals in which the subsources all appear in the given order

    Parameters:
      `subSources` - an ordered set of `IntervalsSource` objects

  - ### unordered

    public static IntervalsSource unordered(IntervalsSource... subSources)
    Create an unordered `IntervalsSource`. Note that if there are multiple intervals ends at the same position are eligible, only the narrowest one will be returned. For example if asking for `unordered(term("apple"), term("banana"))` on field of "apple wolf apple orange banana", only the "apple orange banana" will be returned.

    Returns intervals in which all the subsources appear. The subsources may overlap

    Parameters:
      `subSources` - an unordered set of `IntervalsSource`s

  - ### unorderedNoOverlaps

    public static IntervalsSource unorderedNoOverlaps(IntervalsSource a, IntervalsSource b)
    Create an unordered `IntervalsSource` allowing no overlaps between subsources

    Returns intervals in which both the subsources appear and do not overlap.

  - ### fixField

    public static IntervalsSource fixField(String field, IntervalsSource source)
    Create an `IntervalsSource` that always returns intervals from a specific field

    This is useful for comparing intervals across multiple fields, for example fields that have been analyzed differently, allowing you to search for stemmed terms near unstemmed terms, etc.

  - ### nonOverlapping

    public static IntervalsSource nonOverlapping(IntervalsSource minuend, IntervalsSource subtrahend)
    Create a non-overlapping IntervalsSource

    Returns intervals of the minuend that do not overlap with intervals from the subtrahend

    Parameters:
      `minuend` - the `IntervalsSource` to filter
      `subtrahend` - the `IntervalsSource` to filter by

  - ### overlapping

    public static IntervalsSource overlapping(IntervalsSource source, IntervalsSource reference)
    Returns intervals from a source that overlap with intervals from another source
    Parameters:
      `source` - the source to filter
      `reference` - the source to filter by

  - ### notWithin

    public static IntervalsSource notWithin(IntervalsSource minuend, int positions, IntervalsSource subtrahend)
    Create a not-within `IntervalsSource`

    Returns intervals of the minuend that do not appear within a set number of positions of intervals from the subtrahend query

    Parameters:
      `minuend` - the `IntervalsSource` to filter
      `positions` - the minimum distance that intervals from the minuend may occur from intervals of the subtrahend
      `subtrahend` - the `IntervalsSource` to filter by

  - ### within

    public static IntervalsSource within(IntervalsSource source, int positions, IntervalsSource reference)
    Returns intervals of the source that appear within a set number of positions of intervals from the reference
    Parameters:
      `source` - the `IntervalsSource` to filter
      `positions` - the maximum distance that intervals of the source may occur from intervals of the reference
      `reference` - the `IntervalsSource` to filter by

  - ### notContaining

    public static IntervalsSource notContaining(IntervalsSource minuend, IntervalsSource subtrahend)
    Create a not-containing `IntervalsSource`

    Returns intervals from the minuend that do not contain intervals of the subtrahend

    Parameters:
      `minuend` - the `IntervalsSource` to filter
      `subtrahend` - the `IntervalsSource` to filter by

  - ### containing

    public static IntervalsSource containing(IntervalsSource big, IntervalsSource small)
    Create a containing `IntervalsSource`

    Returns intervals from the big source that contain one or more intervals from the small source

    Parameters:
      `big` - the `IntervalsSource` to filter
      `small` - the `IntervalsSource` to filter by

  - ### notContainedBy

    public static IntervalsSource notContainedBy(IntervalsSource small, IntervalsSource big)
    Create a not-contained-by `IntervalsSource`

    Returns intervals from the small `IntervalsSource` that do not appear within intervals from the big `IntervalsSource`.

    Parameters:
      `small` - the `IntervalsSource` to filter
      `big` - the `IntervalsSource` to filter by

  - ### containedBy

    public static IntervalsSource containedBy(IntervalsSource small, IntervalsSource big)
    Create a contained-by `IntervalsSource`

    Returns intervals from the small query that appear within intervals of the big query

    Parameters:
      `small` - the `IntervalsSource` to filter
      `big` - the `IntervalsSource` to filter by

  - ### atLeast

    public static IntervalsSource atLeast(int minShouldMatch, IntervalsSource... sources)
    Return intervals that span combinations of intervals from `minShouldMatch` of the sources

  - ### before

    public static IntervalsSource before(IntervalsSource source, IntervalsSource reference)
    Returns intervals from the source that appear before intervals from the reference

  - ### after

    public static IntervalsSource after(IntervalsSource source, IntervalsSource reference)
    Returns intervals from the source that appear after intervals from the reference

  - ### noIntervals

    public static IntervalsSource noIntervals(String reason)
    Returns a source that produces no intervals
    Parameters:
      `reason` - A reason string that will appear in the toString output of this source

  - ### analyzedText

    public static IntervalsSource analyzedText(String text, Analyzer analyzer, String field, int maxGaps, boolean ordered) throws IOException
    Returns intervals that correspond to tokens from a `TokenStream` returned for `text` by applying the provided `Analyzer` as if `text` was the content of the given `field`. The intervals can be ordered or unordered and can have optional gaps inside.
    Parameters:
      `text` - The text to analyze.
      `analyzer` - The `Analyzer` to use to acquire a `TokenStream` which is then converted into intervals.
      `field` - The field `text` should be parsed as.
      `maxGaps` - Maximum number of allowed gaps between sub-intervals resulting from tokens.
      `ordered` - Whether sub-intervals should enforce token ordering or not.
    Returns:
      Returns an `IntervalsSource` that matches tokens acquired from analysis of `text`. Possibly an empty interval source, never `null`.
    Throws:
      `IOException` - If an I/O exception occurs.

  - ### analyzedText

    public static IntervalsSource analyzedText(TokenStream tokenStream, int maxGaps, boolean ordered) throws IOException
    Returns intervals that correspond to tokens from the provided `TokenStream`. This is a low-level counterpart to `analyzedText(String, Analyzer, String, int, boolean)`. The intervals can be ordered or unordered and can have optional gaps inside.
    Parameters:
      `tokenStream` - The token stream to produce intervals for. The token stream may be fully or partially consumed after returning from this method.
      `maxGaps` - Maximum number of allowed gaps between sub-intervals resulting from tokens.
      `ordered` - Whether sub-intervals should enforce token ordering or not.
    Returns:
      Returns an `IntervalsSource` that matches tokens acquired from analysis of `text`. Possibly an empty interval source, never `null`.
    Throws:
      `IOException` - If an I/O exception occurs.