LUCENE-10311: add long method, that forwards to int method and truncates

Confusion happens because grow(numAdds) reserves space for you to call
add() up to numAdds times.

When numAdds exceeds a "threshold" (maxdoc >> 8), we really don't care
about big numbers at all: we'll switch to a FixedBitSet(maxDoc) with
fixed sized storage, bounded only by maxDoc.

But we can just add a one-liner grow(long) that doesn't require the
caller to understand any of this, and hide it via implementation detail.

Author: rmuir

lucene/core/src/java/org/apache/lucene/util/DocIdSetBuilder.java

@@ -144,13 +144,23 @@ public void add(DocIdSetIterator iter) throws IOException {
   }
 
   /**
-   * Reserve space and return a {@link BulkAdder} object that can be used to add up to {@code
-   * numDocs} documents.
+   * Reserve space and return a {@link BulkAdder} object that supports up to {@code numAdds}
+   * invocations of {@link BulkAdder#add(int)}.
    */
-  public BulkAdder grow(int numDocs) {
+  public BulkAdder grow(long numAdds) {
+    // as an impl detail, we don't need to care about numbers bigger than int32,
+    // we switch over to FixedBitSet storage well before that threshold.
+    return grow((int) Math.min(Integer.MAX_VALUE, numAdds));
+  }
+
+  /**
+   * Reserve space and return a {@link BulkAdder} object that supports up to {@code numAdds}
+   * invocations of {@link BulkAdder#add(int)}.
+   */
+  public BulkAdder grow(int numAdds) {
     if (bitSet == null) {
-      if ((long) totalAllocated + numDocs <= threshold) {
-        ensureBufferCapacity(numDocs);
+      if ((long) totalAllocated + numAdds <= threshold) {
+        ensureBufferCapacity(numAdds);
       } else {
         upgradeToBitSet();
       }