001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.util;
018
019import java.io.Serializable;
020import java.util.BitSet;
021import java.util.Objects;
022import java.util.stream.IntStream;
023
024/**
025 * A fluent {@link BitSet} with additional operations.
026 * <p>
027 * Originally from Apache Commons VFS with more added to act as a fluent replacement for {@link java.util.BitSet}.
028 * </p>
029 * @since 3.13.0
030 */
031public final class FluentBitSet implements Cloneable, Serializable {
032
033    private static final long serialVersionUID = 1L;
034
035    /**
036     * Working BitSet.
037     */
038    private final BitSet bitSet;
039
040    /**
041     * Creates a new bit set. All bits are initially {@code false}.
042     */
043    public FluentBitSet() {
044        this(new BitSet());
045    }
046
047    /**
048     * Creates a new instance for the given bit set.
049     *
050     * @param set The bit set to wrap.
051     */
052    public FluentBitSet(final BitSet set) {
053        this.bitSet = Objects.requireNonNull(set, "set");
054    }
055
056    /**
057     * Creates a bit set whose initial size is large enough to explicitly represent bits with indices in the range {@code 0}
058     * through {@code nbits-1}. All bits are initially {@code false}.
059     *
060     * @param nbits the initial size of the bit set.
061     * @throws NegativeArraySizeException if the specified initial size is negative.
062     */
063    public FluentBitSet(final int nbits) {
064        this(new BitSet(nbits));
065    }
066
067    /**
068     * Performs a logical <b>AND</b> of this target bit set with the argument bit set. This bit set is modified so that each
069     * bit in it has the value {@code true} if and only if it both initially had the value {@code true} and the
070     * corresponding bit in the bit set argument also had the value {@code true}.
071     *
072     * @param set a bit set.
073     * @return {@code this} instance.
074     */
075    public FluentBitSet and(final BitSet set) {
076        bitSet.and(set);
077        return this;
078    }
079
080    /**
081     * Performs a logical <b>AND</b> of this target bit set with the argument bit set. This bit set is modified so that each
082     * bit in it has the value {@code true} if and only if it both initially had the value {@code true} and the
083     * corresponding bit in the bit set argument also had the value {@code true}.
084     *
085     * @param set a bit set.
086     * @return {@code this} instance.
087     */
088    public FluentBitSet and(final FluentBitSet set) {
089        bitSet.and(set.bitSet);
090        return this;
091    }
092
093    /**
094     * Clears all of the bits in this {@link BitSet} whose corresponding bit is set in the specified {@link BitSet}.
095     *
096     * @param set the {@link BitSet} with which to mask this {@link BitSet}.
097     * @return {@code this} instance.
098     */
099    public FluentBitSet andNot(final BitSet set) {
100        bitSet.andNot(set);
101        return this;
102    }
103
104    /**
105     * Clears all of the bits in this {@link BitSet} whose corresponding bit is set in the specified {@link BitSet}.
106     *
107     * @param set the {@link BitSet} with which to mask this {@link BitSet}.
108     * @return {@code this} instance.
109     */
110    public FluentBitSet andNot(final FluentBitSet set) {
111        this.bitSet.andNot(set.bitSet);
112        return this;
113    }
114
115    /**
116     * Gets the wrapped bit set.
117     *
118     * @return the wrapped bit set.
119     */
120    public BitSet bitSet() {
121        return bitSet;
122    }
123
124    /**
125     * Returns the number of bits set to {@code true} in this {@link BitSet}.
126     *
127     * @return the number of bits set to {@code true} in this {@link BitSet}.
128     */
129    public int cardinality() {
130        return bitSet.cardinality();
131    }
132
133    /**
134     * Sets all of the bits in this BitSet to {@code false}.
135     *
136     * @return {@code this} instance.
137     */
138    public FluentBitSet clear() {
139        bitSet.clear();
140        return this;
141    }
142
143    /**
144     * Sets the bits specified by the indexes to {@code false}.
145     *
146     * @param bitIndexArray the index of the bit to be cleared.
147     * @throws IndexOutOfBoundsException if the specified index is negative.
148     * @return {@code this} instance.
149     */
150    public FluentBitSet clear(final int... bitIndexArray) {
151        for (final int e : bitIndexArray) {
152            this.bitSet.clear(e);
153        }
154        return this;
155    }
156
157    /**
158     * Sets the bit specified by the index to {@code false}.
159     *
160     * @param bitIndex the index of the bit to be cleared.
161     * @throws IndexOutOfBoundsException if the specified index is negative.
162     * @return {@code this} instance.
163     */
164    public FluentBitSet clear(final int bitIndex) {
165        bitSet.clear(bitIndex);
166        return this;
167    }
168
169    /**
170     * Sets the bits from the specified {@code fromIndex} (inclusive) to the specified {@code toIndex} (exclusive) to
171     * {@code false}.
172     *
173     * @param fromIndex index of the first bit to be cleared.
174     * @param toIndex index after the last bit to be cleared.
175     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
176     *         {@code fromIndex} is larger than {@code toIndex}.
177     * @return {@code this} instance.
178     */
179    public FluentBitSet clear(final int fromIndex, final int toIndex) {
180        bitSet.clear(fromIndex, toIndex);
181        return this;
182    }
183
184    /**
185     * Cloning this {@link BitSet} produces a new {@link BitSet} that is equal to it. The clone of the bit set is another
186     * bit set that has exactly the same bits set to {@code true} as this bit set.
187     *
188     * @return a clone of this bit set
189     * @see #size()
190     */
191    @Override
192    public Object clone() {
193        return new FluentBitSet((BitSet) bitSet.clone());
194    }
195
196    @Override
197    public boolean equals(final Object obj) {
198        if (this == obj) {
199            return true;
200        }
201        if (!(obj instanceof FluentBitSet)) {
202            return false;
203        }
204        final FluentBitSet other = (FluentBitSet) obj;
205        return Objects.equals(bitSet, other.bitSet);
206    }
207
208    /**
209     * Sets the bit at the specified index to the complement of its current value.
210     *
211     * @param bitIndex the index of the bit to flip.
212     * @throws IndexOutOfBoundsException if the specified index is negative.
213     * @return {@code this} instance.
214     */
215    public FluentBitSet flip(final int bitIndex) {
216        bitSet.flip(bitIndex);
217        return this;
218    }
219
220    /**
221     * Sets each bit from the specified {@code fromIndex} (inclusive) to the specified {@code toIndex} (exclusive) to the
222     * complement of its current value.
223     *
224     * @param fromIndex index of the first bit to flip.
225     * @param toIndex index after the last bit to flip.
226     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
227     *         {@code fromIndex} is larger than {@code toIndex}.
228     * @return {@code this} instance.
229     */
230    public FluentBitSet flip(final int fromIndex, final int toIndex) {
231        bitSet.flip(fromIndex, toIndex);
232        return this;
233    }
234
235    /**
236     * Returns the value of the bit with the specified index. The value is {@code true} if the bit with the index
237     * {@code bitIndex} is currently set in this {@link BitSet}; otherwise, the result is {@code false}.
238     *
239     * @param bitIndex the bit index.
240     * @return the value of the bit with the specified index.
241     * @throws IndexOutOfBoundsException if the specified index is negative.
242     */
243    public boolean get(final int bitIndex) {
244        return bitSet.get(bitIndex);
245    }
246
247    /**
248     * Returns a new {@link BitSet} composed of bits from this {@link BitSet} from {@code fromIndex} (inclusive) to
249     * {@code toIndex} (exclusive).
250     *
251     * @param fromIndex index of the first bit to include.
252     * @param toIndex index after the last bit to include.
253     * @return a new {@link BitSet} from a range of this {@link BitSet}.
254     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
255     *         {@code fromIndex} is larger than {@code toIndex}.
256     */
257    public FluentBitSet get(final int fromIndex, final int toIndex) {
258        return new FluentBitSet(bitSet.get(fromIndex, toIndex));
259    }
260
261    @Override
262    public int hashCode() {
263        return bitSet.hashCode();
264    }
265
266    /**
267     * Returns true if the specified {@link BitSet} has any bits set to {@code true} that are also set to {@code true} in
268     * this {@link BitSet}.
269     *
270     * @param set {@link BitSet} to intersect with.
271     * @return boolean indicating whether this {@link BitSet} intersects the specified {@link BitSet}.
272     */
273    public boolean intersects(final BitSet set) {
274        return bitSet.intersects(set);
275    }
276
277    /**
278     * Returns true if the specified {@link BitSet} has any bits set to {@code true} that are also set to {@code true} in
279     * this {@link BitSet}.
280     *
281     * @param set {@link BitSet} to intersect with.
282     * @return boolean indicating whether this {@link BitSet} intersects the specified {@link BitSet}.
283     */
284    public boolean intersects(final FluentBitSet set) {
285        return bitSet.intersects(set.bitSet);
286    }
287
288    /**
289     * Returns true if this {@link BitSet} contains no bits that are set to {@code true}.
290     *
291     * @return boolean indicating whether this {@link BitSet} is empty.
292     */
293    public boolean isEmpty() {
294        return bitSet.isEmpty();
295    }
296
297    /**
298     * Returns the "logical size" of this {@link BitSet}: the index of the highest set bit in the {@link BitSet} plus one.
299     * Returns zero if the {@link BitSet} contains no set bits.
300     *
301     * @return the logical size of this {@link BitSet}.
302     */
303    public int length() {
304        return bitSet.length();
305    }
306
307    /**
308     * Returns the index of the first bit that is set to {@code false} that occurs on or after the specified starting index.
309     *
310     * @param fromIndex the index to start checking from (inclusive).
311     * @return the index of the next clear bit.
312     * @throws IndexOutOfBoundsException if the specified index is negative.
313     */
314    public int nextClearBit(final int fromIndex) {
315        return bitSet.nextClearBit(fromIndex);
316    }
317
318    /**
319     * Returns the index of the first bit that is set to {@code true} that occurs on or after the specified starting index.
320     * If no such bit exists then {@code -1} is returned.
321     * <p>
322     * To iterate over the {@code true} bits in a {@link BitSet}, use the following loop:
323     * </p>
324     *
325     * <pre>
326     * {@code
327     * for (int i = bs.nextSetBit(0); i >= 0; i = bs.nextSetBit(i+1)) {
328     *     // operate on index i here
329     *     if (i == Integer.MAX_VALUE) {
330     *         break; // or (i+1) would overflow
331     *     }
332     * }}
333     * </pre>
334     *
335     * @param fromIndex the index to start checking from (inclusive).
336     * @return the index of the next set bit, or {@code -1} if there is no such bit.
337     * @throws IndexOutOfBoundsException if the specified index is negative.
338     */
339    public int nextSetBit(final int fromIndex) {
340        return bitSet.nextSetBit(fromIndex);
341    }
342
343    /**
344     * Performs a logical <b>OR</b> of this bit set with the bit set argument. This bit set is modified so that a bit in it
345     * has the value {@code true} if and only if it either already had the value {@code true} or the corresponding bit in
346     * the bit set argument has the value {@code true}.
347     *
348     * @param set a bit set.
349     * @return {@code this} instance.
350     */
351    public FluentBitSet or(final BitSet set) {
352        bitSet.or(set);
353        return this;
354    }
355
356    /**
357     * Performs a logical <b>OR</b> of this bit set with the bit set arguments. This bit set is modified so that a bit in it
358     * has the value {@code true} if and only if it either already had the value {@code true} or the corresponding bit in
359     * the bit set argument has the value {@code true}.
360     *
361     * @param set a bit set.
362     * @return {@code this} instance.
363     */
364    public FluentBitSet or(final FluentBitSet... set) {
365        for (final FluentBitSet e : set) {
366            this.bitSet.or(e.bitSet);
367        }
368        return this;
369    }
370
371    /**
372     * Performs a logical <b>OR</b> of this bit set with the bit set argument. This bit set is modified so that a bit in it
373     * has the value {@code true} if and only if it either already had the value {@code true} or the corresponding bit in
374     * the bit set argument has the value {@code true}.
375     *
376     * @param set a bit set.
377     * @return {@code this} instance.
378     */
379    public FluentBitSet or(final FluentBitSet set) {
380        this.bitSet.or(set.bitSet);
381        return this;
382    }
383
384    /**
385     * Returns the index of the nearest bit that is set to {@code false} that occurs on or before the specified starting
386     * index. If no such bit exists, or if {@code -1} is given as the starting index, then {@code -1} is returned.
387     *
388     * @param fromIndex the index to start checking from (inclusive).
389     * @return the index of the previous clear bit, or {@code -1} if there is no such bit.
390     * @throws IndexOutOfBoundsException if the specified index is less than {@code -1}.
391     */
392    public int previousClearBit(final int fromIndex) {
393        return bitSet.previousClearBit(fromIndex);
394    }
395
396    /**
397     * Returns the index of the nearest bit that is set to {@code true} that occurs on or before the specified starting
398     * index. If no such bit exists, or if {@code -1} is given as the starting index, then {@code -1} is returned.
399     *
400     * <p>
401     * To iterate over the {@code true} bits in a {@link BitSet}, use the following loop:
402     *
403     * <pre>
404     *  {@code
405     * for (int i = bs.length(); (i = bs.previousSetBit(i-1)) >= 0; ) {
406     *     // operate on index i here
407     * }}
408     * </pre>
409     *
410     * @param fromIndex the index to start checking from (inclusive)
411     * @return the index of the previous set bit, or {@code -1} if there is no such bit
412     * @throws IndexOutOfBoundsException if the specified index is less than {@code -1}
413     */
414    public int previousSetBit(final int fromIndex) {
415        return bitSet.previousSetBit(fromIndex);
416    }
417
418    /**
419     * Sets the bit at the specified indexes to {@code true}.
420     *
421     * @param bitIndexArray a bit index array.
422     * @throws IndexOutOfBoundsException if the specified index is negative.
423     * @return {@code this} instance.
424     */
425    public FluentBitSet set(final int... bitIndexArray) {
426        for (final int e : bitIndexArray) {
427            bitSet.set(e);
428        }
429        return this;
430    }
431
432    /**
433     * Sets the bit at the specified index to {@code true}.
434     *
435     * @param bitIndex a bit index
436     * @throws IndexOutOfBoundsException if the specified index is negative
437     * @return {@code this} instance.
438     */
439    public FluentBitSet set(final int bitIndex) {
440        bitSet.set(bitIndex);
441        return this;
442    }
443
444    /**
445     * Sets the bit at the specified index to the specified value.
446     *
447     * @param bitIndex a bit index.
448     * @param value a boolean value to set.
449     * @throws IndexOutOfBoundsException if the specified index is negative.
450     * @return {@code this} instance.
451     */
452    public FluentBitSet set(final int bitIndex, final boolean value) {
453        bitSet.set(bitIndex, value);
454        return this;
455    }
456
457    /**
458     * Sets the bits from the specified {@code fromIndex} (inclusive) to the specified {@code toIndex} (exclusive) to
459     * {@code true}.
460     *
461     * @param fromIndex index of the first bit to be set.
462     * @param toIndex index after the last bit to be set.
463     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
464     *         {@code fromIndex} is larger than {@code toIndex}.
465     * @return {@code this} instance.
466     */
467    public FluentBitSet set(final int fromIndex, final int toIndex) {
468        bitSet.set(fromIndex, toIndex);
469        return this;
470    }
471
472    /**
473     * Sets the bits from the specified {@code fromIndex} (inclusive) to the specified {@code toIndex} (exclusive) to the
474     * specified value.
475     *
476     * @param fromIndex index of the first bit to be set.
477     * @param toIndex index after the last bit to be set.
478     * @param value value to set the selected bits to.
479     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
480     *         {@code fromIndex} is larger than {@code toIndex}.
481     * @return {@code this} instance.
482     */
483    public FluentBitSet set(final int fromIndex, final int toIndex, final boolean value) {
484        bitSet.set(fromIndex, toIndex, value);
485        return this;
486    }
487
488    /**
489     * Sets the bits from the specified {@code fromIndex} (inclusive) to the specified {@code toIndex} (inclusive) to
490     * {@code true}.
491     *
492     * @param fromIndex index of the first bit to be set
493     * @param toIndex index of the last bit to be set
494     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative, or {@code toIndex} is negative, or
495     *         {@code fromIndex} is larger than {@code toIndex}
496     * @return {@code this} instance.
497     */
498    public FluentBitSet setInclusive(final int fromIndex, final int toIndex) {
499        bitSet.set(fromIndex, toIndex + 1);
500        return this;
501    }
502
503    /**
504     * Returns the number of bits of space actually in use by this {@link BitSet} to represent bit values. The maximum
505     * element in the set is the size - 1st element.
506     *
507     * @return the number of bits currently in this bit set.
508     */
509    public int size() {
510        return bitSet.size();
511    }
512
513    /**
514     * Returns a stream of indices for which this {@link BitSet} contains a bit in the set state. The indices are returned
515     * in order, from lowest to highest. The size of the stream is the number of bits in the set state, equal to the value
516     * returned by the {@link #cardinality()} method.
517     *
518     * <p>
519     * The bit set must remain constant during the execution of the terminal stream operation. Otherwise, the result of the
520     * terminal stream operation is undefined.
521     * </p>
522     *
523     * @return a stream of integers representing set indices.
524     * @since 1.8
525     */
526    public IntStream stream() {
527        return bitSet.stream();
528    }
529
530    /**
531     * Returns a new byte array containing all the bits in this bit set.
532     *
533     * <p>
534     * More precisely, if:
535     * </p>
536     * <ol>
537     * <li>{@code byte[] bytes = s.toByteArray();}</li>
538     * <li>then {@code bytes.length == (s.length()+7)/8} and</li>
539     * <li>{@code s.get(n) == ((bytes[n/8] & (1<<(n%8))) != 0)}</li>
540     * <li>for all {@code n < 8 * bytes.length}.</li>
541     * </ol>
542     *
543     * @return a byte array containing a little-endian representation of all the bits in this bit set
544     */
545    public byte[] toByteArray() {
546        return bitSet.toByteArray();
547    }
548
549    /**
550     * Returns a new byte array containing all the bits in this bit set.
551     *
552     * <p>
553     * More precisely, if:
554     * </p>
555     * <ol>
556     * <li>{@code long[] longs = s.toLongArray();}</li>
557     * <li>then {@code longs.length == (s.length()+63)/64} and</li>
558     * <li>{@code s.get(n) == ((longs[n/64] & (1L<<(n%64))) != 0)}</li>
559     * <li>for all {@code n < 64 * longs.length}.</li>
560     * </ol>
561     *
562     * @return a byte array containing a little-endian representation of all the bits in this bit set
563     */
564    public long[] toLongArray() {
565        return bitSet.toLongArray();
566    }
567
568    @Override
569    public String toString() {
570        return bitSet.toString();
571    }
572
573    /**
574     * Performs a logical <b>XOR</b> of this bit set with the bit set argument. This bit set is modified so that a bit in it
575     * has the value {@code true} if and only if one of the following statements holds:
576     * <ul>
577     * <li>The bit initially has the value {@code true}, and the corresponding bit in the argument has the value
578     * {@code false}.
579     * <li>The bit initially has the value {@code false}, and the corresponding bit in the argument has the value
580     * {@code true}.
581     * </ul>
582     *
583     * @param set a bit set
584     * @return {@code this} instance.
585     */
586    public FluentBitSet xor(final BitSet set) {
587        bitSet.xor(set);
588        return this;
589    }
590
591    /**
592     * Performs a logical <b>XOR</b> of this bit set with the bit set argument. This bit set is modified so that a bit in it
593     * has the value {@code true} if and only if one of the following statements holds:
594     * <ul>
595     * <li>The bit initially has the value {@code true}, and the corresponding bit in the argument has the value
596     * {@code false}.
597     * <li>The bit initially has the value {@code false}, and the corresponding bit in the argument has the value
598     * {@code true}.
599     * </ul>
600     *
601     * @param set a bit set
602     * @return {@code this} instance.
603     */
604    public FluentBitSet xor(final FluentBitSet set) {
605        bitSet.xor(set.bitSet);
606        return this;
607    }
608
609}