PostingsEnum (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, class: PostingsEnum

Package org.apache.lucene.index

# Class PostingsEnum

java.lang.Object
org.apache.lucene.search.DocIdSetIterator
org.apache.lucene.index.PostingsEnum

Direct Known Subclasses:
  `FilterLeafReader.FilterPostingsEnum`, `ImpactsEnum`, `MultiPhraseQuery.UnionPostingsEnum`, `MultiPostingsEnum`

public abstract class PostingsEnum extends DocIdSetIterator
Iterates through the postings. NOTE: you must first call `DocIdSetIterator.nextDoc()` before using any of the per-doc methods.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final short`
  `ALL`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` to get positions, payloads and offsets in the returned enum
  `static final short`
  `FREQS`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require term frequencies in the returned enum.
  `static final short`
  `NONE`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you don't require per-document postings in the returned enum.
  `static final short`
  `OFFSETS`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require offsets in the returned enum.
  `static final short`
  `PAYLOADS`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require payloads in the returned enum.
  `static final short`
  `POSITIONS`
  Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require term positions in the returned enum.

  ### Fields inherited from class org.apache.lucene.search.DocIdSetIterator

  `NO_MORE_DOCS`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PostingsEnum()`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract int`
  `endOffset()`
  Returns end offset for the current position, or -1 if offsets were not indexed.
  `static boolean`
  `featureRequested(int flags, short feature)`
  Returns true if the given feature is requested in the flags, false otherwise.
  `abstract int`
  `freq()`
  Returns term frequency in the current document, or 1 if the field was indexed with `IndexOptions.DOCS`.
  `abstract BytesRef`
  `getPayload()`
  Returns the payload at this position, or null if no payload was indexed.
  `abstract int`
  `nextPosition()`
  Returns the next position, or -1 if positions were not indexed.
  `void`
  `nextPostings(int upTo, DocAndFloatFeatureBuffer buffer)`
  Fill a buffer of doc IDs and frequencies with some number of doc IDs and their corresponding frequencies, starting at the current doc ID, and ending before `upTo`.
  `abstract int`
  `startOffset()`
  Returns start offset for the current position, or -1 if offsets were not indexed.

  ### Methods inherited from class org.apache.lucene.search.DocIdSetIterator

  `advance, all, cost, docID, docIDRunEnd, empty, intoBitSet, nextDoc, range, slowAdvance`

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

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

- ## Field Details

  - ### NONE

    public static final short NONE
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you don't require per-document postings in the returned enum.
    See Also:
      - Constant Field Values

  - ### FREQS

    public static final short FREQS
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require term frequencies in the returned enum.
    See Also:
      - Constant Field Values

  - ### POSITIONS

    public static final short POSITIONS
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require term positions in the returned enum.
    See Also:
      - Constant Field Values

  - ### OFFSETS

    public static final short OFFSETS
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require offsets in the returned enum.
    See Also:
      - Constant Field Values

  - ### PAYLOADS

    public static final short PAYLOADS
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` if you require payloads in the returned enum.
    See Also:
      - Constant Field Values

  - ### ALL

    public static final short ALL
    Flag to pass to `TermsEnum.postings(PostingsEnum, int)` to get positions, payloads and offsets in the returned enum
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### PostingsEnum

    protected PostingsEnum()
    Sole constructor. (For invocation by subclass constructors, typically implicit.)

- ## Method Details

  - ### featureRequested

    public static boolean featureRequested(int flags, short feature)
    Returns true if the given feature is requested in the flags, false otherwise.

  - ### freq

    public abstract int freq() throws IOException
    Returns term frequency in the current document, or 1 if the field was indexed with `IndexOptions.DOCS`. Do not call this before `DocIdSetIterator.nextDoc()` is first called, nor after `DocIdSetIterator.nextDoc()` returns `DocIdSetIterator.NO_MORE_DOCS`.

    NOTE: if the `PostingsEnum` was obtain with `NONE`, the result of this method is undefined.

    Throws:
      `IOException`

  - ### nextPosition

    public abstract int nextPosition() throws IOException
    Returns the next position, or -1 if positions were not indexed. Calling this more than `freq()` times is undefined.
    Throws:
      `IOException`

  - ### startOffset

    public abstract int startOffset() throws IOException
    Returns start offset for the current position, or -1 if offsets were not indexed.
    Throws:
      `IOException`

  - ### endOffset

    public abstract int endOffset() throws IOException
    Returns end offset for the current position, or -1 if offsets were not indexed.
    Throws:
      `IOException`

  - ### getPayload

    public abstract BytesRef getPayload() throws IOException
    Returns the payload at this position, or null if no payload was indexed. You should not modify anything (neither members of the returned BytesRef nor bytes in the byte[]).
    Throws:
      `IOException`

  - ### nextPostings

    public void nextPostings(int upTo, DocAndFloatFeatureBuffer buffer) throws IOException
    Fill a buffer of doc IDs and frequencies with some number of doc IDs and their corresponding frequencies, starting at the current doc ID, and ending before `upTo`. Because it starts on the current doc ID, it is illegal to call this method if the `current doc ID` is `-1`.

    An empty buffer after this method returns indicates that there are no postings left between the current doc ID and `upTo`.

    Implementations should ideally fill the buffer with a number of entries comprised between 8 and a couple hundreds, to keep heap requirements contained, while still being large enough to enable operations on the buffer to auto-vectorize efficiently.

    The default implementation is provided below:

         int batchSize = 16; // arbitrary
         buffer.growNoCopy(batchSize);
         int size = 0;
         for (int doc = docID(); doc < upTo && size < batchSize; doc = nextDoc()) {
           buffer.docs[size] = doc;
           buffer.freqs[size] = freq();
           ++size;
         }
         buffer.size = size;

    NOTE: The provided `DocAndFloatFeatureBuffer` should not hold references to internal data structures.

    Throws:
      `IOException`
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.