Package org.apache.lucene.util

## Class DocIdSetBuilder

- java.lang.Object
- - org.apache.lucene.util.DocIdSetBuilder

-     public final class DocIdSetBuilder
      extends Object

  A builder of `DocIdSet`s. At first it uses a sparse structure to gather documents, and then upgrades to a non-sparse bit set once enough hits match.

  To add documents, you first need to call `grow(int)` in order to reserve space, and then call `DocIdSetBuilder.BulkAdder.add(int)` on the returned `DocIdSetBuilder.BulkAdder`.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `DocIdSetBuilder.BulkAdder` | Utility class to efficiently add many docs in one go.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DocIdSetBuilder​(int maxDoc)` | Create a builder that can contain doc IDs between `0` and `maxDoc`.
    `DocIdSetBuilder​(int maxDoc, PointValues values, String field)` | Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `PointValues`.
    `DocIdSetBuilder​(int maxDoc, Terms terms)` | Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `Terms`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(DocIdSetIterator iter)` | Add the content of the provided `DocIdSetIterator` to this builder.
    `DocIdSet` | `build()` | Build a `DocIdSet` from the accumulated doc IDs.
    `DocIdSetBuilder.BulkAdder` | `grow​(int numDocs)` | Reserve space and return a `DocIdSetBuilder.BulkAdder` object that can be used to add up to `numDocs` documents.

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

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

- - ### Constructor Detail

    - #### DocIdSetBuilder

          public DocIdSetBuilder​(int maxDoc)

      Create a builder that can contain doc IDs between `0` and `maxDoc`.

    - #### DocIdSetBuilder

          public DocIdSetBuilder​(int maxDoc,
                                 Terms terms)
                          throws IOException

      Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `Terms`.
      Throws:
        `IOException`

    - #### DocIdSetBuilder

          public DocIdSetBuilder​(int maxDoc,
                                 PointValues values,
                                 String field)
                          throws IOException

      Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `PointValues`.
      Throws:
        `IOException`

  - ### Method Detail

    - #### add

          public void add​(DocIdSetIterator iter)
                   throws IOException

      Add the content of the provided `DocIdSetIterator` to this builder. NOTE: if you need to build a `DocIdSet` out of a single `DocIdSetIterator`, you should rather use `RoaringDocIdSet.Builder`.
      Throws:
        `IOException`

    - #### grow

          public DocIdSetBuilder.BulkAdder grow​(int numDocs)

      Reserve space and return a `DocIdSetBuilder.BulkAdder` object that can be used to add up to `numDocs` documents.

    - #### build

          public DocIdSet build()

      Build a `DocIdSet` from the accumulated doc IDs.