/*

 * Copyright 1995-2007 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.util;

import java.io.*;

import java.nio.ByteBuffer;

import java.nio.ByteOrder;

import java.nio.LongBuffer;

/**

 * This class implements a vector of bits that grows as needed. Each

 * component of the bit set has a {@code boolean} value. The

 * bits of a {@code BitSet} are indexed by nonnegative integers.

 * Individual indexed bits can be examined, set, or cleared. One

 * {@code BitSet} may be used to modify the contents of another

 * {@code BitSet} through logical AND, logical inclusive OR, and

 * logical exclusive OR operations.

 *

 * <p>By default, all bits in the set initially have the value

 * {@code false}.

 *

 * <p>Every bit set has a current size, which is the number of bits

 * of space currently in use by the bit set. Note that the size is

 * related to the implementation of a bit set, so it may change with

 * implementation. The length of a bit set relates to logical length

 * of a bit set and is defined independently of implementation.

 *

 * <p>Unless otherwise noted, passing a null parameter to any of the

 * methods in a {@code BitSet} will result in a

 * {@code NullPointerException}.

 *

 * <p>A {@code BitSet} is not safe for multithreaded use without

 * external synchronization.

 *

 * @author  Arthur van Hoff

 * @author  Michael McCloskey

 * @author  Martin Buchholz

 * @since   JDK1.0

 */

public class BitSet implements Cloneable, java.io.Serializable {

    /*

     * BitSets are packed into arrays of "words."  Currently a word is

     * a long, which consists of 64 bits, requiring 6 address bits.

     * The choice of word size is determined purely by performance concerns.

     */

    private final static int ADDRESS_BITS_PER_WORD = 6;

    private final static int BITS_PER_WORD = 1 << ADDRESS_BITS_PER_WORD;

    private final static int BIT_INDEX_MASK = BITS_PER_WORD - 1;

    /* Used to shift left or right for a partial word mask */

    private static final long WORD_MASK = 0xffffffffffffffffL;

    /**

     * @serialField bits long[]

     *

     * The bits in this BitSet.  The ith bit is stored in bits[i/64] at

     * bit position i % 64 (where bit position 0 refers to the least

     * significant bit and 63 refers to the most significant bit).

     */

    private static final ObjectStreamField[] serialPersistentFields = {

        new ObjectStreamField("bits", long[].class),

    };

    /**

     * The internal field corresponding to the serialField "bits".

     */

    private long[] words;

    /**

     * The number of words in the logical size of this BitSet.

     */

    private transient int wordsInUse = 0;

    /**

     * Whether the size of "words" is user-specified.  If so, we assume

     * the user knows what he's doing and try harder to preserve it.

     */

    private transient boolean sizeIsSticky = false;

    /* use serialVersionUID from JDK 1.0.2 for interoperability */

    private static final long serialVersionUID = 7997698588986878753L;

    /**

     * Given a bit index, return word index containing it.

     */

    private static int wordIndex(int bitIndex) {

        return bitIndex >> ADDRESS_BITS_PER_WORD;

    }

    /**

     * Every public method must preserve these invariants.

     */

    private void checkInvariants() {

        assert(wordsInUse == 0 || words[wordsInUse - 1] != 0);

        assert(wordsInUse >= 0 && wordsInUse <= words.length);

        assert(wordsInUse == words.length || words[wordsInUse] == 0);

    }

    /**

     * Sets the field wordsInUse to the logical size in words of the bit set.

     * WARNING:This method assumes that the number of words actually in use is

     * less than or equal to the current value of wordsInUse!

     */

    private void recalculateWordsInUse() {

        // Traverse the bitset until a used word is found

        int i;

        for (i = wordsInUse-1; i >= 0; i--)

            if (words[i] != 0)

                break;

        wordsInUse = i+1; // The new logical size

    }

    /**

     * Creates a new bit set. All bits are initially {@code false}.

     */

    public BitSet() {

        initWords(BITS_PER_WORD);

        sizeIsSticky = false;

    }

    /**

     * Creates a bit set whose initial size is large enough to explicitly

     * represent bits with indices in the range {@code 0} through

     * {@code nbits-1}. All bits are initially {@code false}.

     *

     * @param  nbits the initial size of the bit set

     * @throws NegativeArraySizeException if the specified initial size

     *         is negative

     */

    public BitSet(int nbits) {

        // nbits can't be negative; size 0 is OK

        if (nbits < 0)

            throw new NegativeArraySizeException("nbits < 0: " + nbits);

        initWords(nbits);

        sizeIsSticky = true;

    }

    private void initWords(int nbits) {

        words = new long[wordIndex(nbits-1) + 1];

    }

    /**

     * Creates a bit set using words as the internal representation.

     * The last word (if there is one) must be non-zero.

     */

    private BitSet(long[] words) {

        this.words = words;

        this.wordsInUse = words.length;

        checkInvariants();

    }

    /**

     * Returns a new bit set containing all the bits in the given long array.

     *

     * <p>More precisely,

     * <br>{@code BitSet.valueOf(longs).get(n) == ((longs[n/64] & (1L<<(n%64))) != 0)}

     * <br>for all {@code n < 64 * longs.length}.

     *

     * <p>This method is equivalent to

     * {@code BitSet.valueOf(LongBuffer.wrap(longs))}.

     *

     * @param longs a long array containing a little-endian representation

     *        of a sequence of bits to be used as the initial bits of the

     *        new bit set

     * @since 1.7

     */

    public static BitSet valueOf(long[] longs) {

        int n;

        for (n = longs.length; n > 0 && longs[n - 1] == 0; n--)

            ;

        return new BitSet(Arrays.copyOf(longs, n));

    }

    /**

     * Returns a new bit set containing all the bits in the given long

     * buffer between its position and limit.

     *

     * <p>More precisely,

     * <br>{@code BitSet.valueOf(lb).get(n) == ((lb.get(lb.position()+n/64) & (1L<<(n%64))) != 0)}

     * <br>for all {@code n < 64 * lb.remaining()}.

     *

     * <p>The long buffer is not modified by this method, and no

     * reference to the buffer is retained by the bit set.

     *

     * @param lb a long buffer containing a little-endian representation

     *        of a sequence of bits between its position and limit, to be

     *        used as the initial bits of the new bit set

     * @since 1.7

     */

    public static BitSet valueOf(LongBuffer lb) {

        lb = lb.slice();

        int n;

        for (n = lb.remaining(); n > 0 && lb.get(n - 1) == 0; n--)

            ;

        long[] words = new long[n];

        lb.get(words);

        return new BitSet(words);

    }

    /**

     * Returns a new bit set containing all the bits in the given byte array.

     *

     * <p>More precisely,

     * <br>{@code BitSet.valueOf(bytes).get(n) == ((bytes[n/8] & (1<<(n%8))) != 0)}

     * <br>for all {@code n <  8 * bytes.length}.

     *

     * <p>This method is equivalent to

     * {@code BitSet.valueOf(ByteBuffer.wrap(bytes))}.

     *

     * @param bytes a byte array containing a little-endian

     *        representation of a sequence of bits to be used as the

     *        initial bits of the new bit set

     * @since 1.7

     */

    public static BitSet valueOf(byte[] bytes) {

        return BitSet.valueOf(ByteBuffer.wrap(bytes));

    }

    /**

     * Returns a new bit set containing all the bits in the given byte

     * buffer between its position and limit.

     *

     * <p>More precisely,

     * <br>{@code BitSet.valueOf(bb).get(n) == ((bb.get(bb.position()+n/8) & (1<<(n%8))) != 0)}

     * <br>for all {@code n < 8 * bb.remaining()}.

     *

     * <p>The byte buffer is not modified by this method, and no

     * reference to the buffer is retained by the bit set.

     *

     * @param bb a byte buffer containing a little-endian representation

     *        of a sequence of bits between its position and limit, to be

     *        used as the initial bits of the new bit set

     * @since 1.7

     */

    public static BitSet valueOf(ByteBuffer bb) {

        bb = bb.slice().order(ByteOrder.LITTLE_ENDIAN);

        int n;

        for (n = bb.remaining(); n > 0 && bb.get(n - 1) == 0; n--)

            ;

        long[] words = new long[(n + 7) / 8];

        bb.limit(n);

        int i = 0;

        while (bb.remaining() >= 8)

            words[i++] = bb.getLong();

        for (int remaining = bb.remaining(), j = 0; j < remaining; j++)

            words[i] |= (bb.get() & 0xffL) << (8 * j);

        return new BitSet(words);

    }

    /**

     * Returns a new byte array containing all the bits in this bit set.

     *

     * <p>More precisely, if

     * <br>{@code byte[] bytes = s.toByteArray();}

     * <br>then {@code bytes.length == (s.length()+7)/8} and

     * <br>{@code s.get(n) == ((bytes[n/8] & (1<<(n%8))) != 0)}

     * <br>for all {@code n < 8 * bytes.length}.

     *

     * @return a byte array containing a little-endian representation

     *         of all the bits in this bit set

     * @since 1.7

    */

    public byte[] toByteArray() {

        int n = wordsInUse;

        if (n == 0)

            return new byte[0];

        int len = 8 * (n-1);

        for (long x = words[n - 1]; x != 0; x >>>= 8)

            len++;

        byte[] bytes = new byte[len];

        ByteBuffer bb = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN);

        for (int i = 0; i < n - 1; i++)

            bb.putLong(words[i]);

        for (long x = words[n - 1]; x != 0; x >>>= 8)

            bb.put((byte) (x & 0xff));

        return bytes;

    }

    /**

     * Returns a new long array containing all the bits in this bit set.

     *

     * <p>More precisely, if

     * <br>{@code long[] longs = s.toLongArray();}

     * <br>then {@code longs.length == (s.length()+63)/64} and

     * <br>{@code s.get(n) == ((longs[n/64] & (1L<<(n%64))) != 0)}

     * <br>for all {@code n < 64 * longs.length}.

     *

     * @return a long array containing a little-endian representation

     *         of all the bits in this bit set

     * @since 1.7

    */

    public long[] toLongArray() {

        return Arrays.copyOf(words, wordsInUse);

    }

    /**

     * Ensures that the BitSet can hold enough words.

     * @param wordsRequired the minimum acceptable number of words.

     */

    private void ensureCapacity(int wordsRequired) {

        if (words.length < wordsRequired) {

            // Allocate larger of doubled size or required size

            int request = Math.max(2 * words.length, wordsRequired);

            words = Arrays.copyOf(words, request);

            sizeIsSticky = false;

        }

    }

    /**

     * Ensures that the BitSet can accommodate a given wordIndex,

     * temporarily violating the invariants.  The caller must

     * restore the invariants before returning to the user,

     * possibly using recalculateWordsInUse().

     * @param wordIndex the index to be accommodated.

     */

    private void expandTo(int wordIndex) {

        int wordsRequired = wordIndex+1;

        if (wordsInUse < wordsRequired) {

            ensureCapacity(wordsRequired);

            wordsInUse = wordsRequired;

        }

    }

    /**

     * Checks that fromIndex ... toIndex is a valid range of bit indices.

     */

    private static void checkRange(int fromIndex, int toIndex) {

        if (fromIndex < 0)

            throw new IndexOutOfBoundsException("fromIndex < 0: " + fromIndex);

        if (toIndex < 0)

            throw new IndexOutOfBoundsException("toIndex < 0: " + toIndex);

        if (fromIndex > toIndex)

            throw new IndexOutOfBoundsException("fromIndex: " + fromIndex +

                                                " > toIndex: " + toIndex);

    }

    /**

     * Sets the bit at the specified index to the complement of its

     * current value.

     *

     * @param  bitIndex the index of the bit to flip

     * @throws IndexOutOfBoundsException if the specified index is negative

     * @since  1.4

     */

    public void flip(int bitIndex) {

        if (bitIndex < 0)

            throw new IndexOutOfBoundsException("bitIndex < 0: " + bitIndex);

        int wordIndex = wordIndex(bitIndex);

        expandTo(wordIndex);

        words[wordIndex] ^= (1L << bitIndex);

        recalculateWordsInUse();

        checkInvariants();

    }

    /**

     * Sets each bit from the specified {@code fromIndex} (inclusive) to the

     * specified {@code toIndex} (exclusive) to the complement of its current

     * value.

     *

     * @param  fromIndex index of the first bit to flip

     * @param  toIndex index after the last bit to flip

     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative,

     *         or {@code toIndex} is negative, or {@code fromIndex} is

     *         larger than {@code toIndex}

     * @since  1.4

     */

    public void flip(int fromIndex, int toIndex) {

        checkRange(fromIndex, toIndex);

        if (fromIndex == toIndex)

            return;

        int startWordIndex = wordIndex(fromIndex);

        int endWordIndex   = wordIndex(toIndex - 1);

        expandTo(endWordIndex);

        long firstWordMask = WORD_MASK << fromIndex;

        long lastWordMask  = WORD_MASK >>> -toIndex;

        if (startWordIndex == endWordIndex) {

            // Case 1: One word

            words[startWordIndex] ^= (firstWordMask & lastWordMask);

        } else {

            // Case 2: Multiple words

            // Handle first word

            words[startWordIndex] ^= firstWordMask;

            // Handle intermediate words, if any

            for (int i = startWordIndex+1; i < endWordIndex; i++)

                words[i] ^= WORD_MASK;

            // Handle last word

            words[endWordIndex] ^= lastWordMask;

        }

        recalculateWordsInUse();

        checkInvariants();

    }

    /**

     * Sets the bit at the specified index to {@code true}.

     *

     * @param  bitIndex a bit index

     * @throws IndexOutOfBoundsException if the specified index is negative

     * @since  JDK1.0

     */

    public void set(int bitIndex) {

        if (bitIndex < 0)

            throw new IndexOutOfBoundsException("bitIndex < 0: " + bitIndex);

        int wordIndex = wordIndex(bitIndex);

        expandTo(wordIndex);

        words[wordIndex] |= (1L << bitIndex); // Restores invariants

        checkInvariants();

    }

    /**

     * Sets the bit at the specified index to the specified value.

     *

     * @param  bitIndex a bit index

     * @param  value a boolean value to set

     * @throws IndexOutOfBoundsException if the specified index is negative

     * @since  1.4

     */

    public void set(int bitIndex, boolean value) {

        if (value)

            set(bitIndex);

        else

            clear(bitIndex);

    }

    /**

     * Sets the bits from the specified {@code fromIndex} (inclusive) to the

     * specified {@code toIndex} (exclusive) to {@code true}.

     *

     * @param  fromIndex index of the first bit to be set

     * @param  toIndex index after the last bit to be set

     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative,

     *         or {@code toIndex} is negative, or {@code fromIndex} is

     *         larger than {@code toIndex}

     * @since  1.4

     */

    public void set(int fromIndex, int toIndex) {

        checkRange(fromIndex, toIndex);

        if (fromIndex == toIndex)

            return;

        // Increase capacity if necessary

        int startWordIndex = wordIndex(fromIndex);

        int endWordIndex   = wordIndex(toIndex - 1);

        expandTo(endWordIndex);

        long firstWordMask = WORD_MASK << fromIndex;

        long lastWordMask  = WORD_MASK >>> -toIndex;

        if (startWordIndex == endWordIndex) {

            // Case 1: One word

            words[startWordIndex] |= (firstWordMask & lastWordMask);

        } else {

            // Case 2: Multiple words

            // Handle first word

            words[startWordIndex] |= firstWordMask;

            // Handle intermediate words, if any

            for (int i = startWordIndex+1; i < endWordIndex; i++)

                words[i] = WORD_MASK;

            // Handle last word (restores invariants)

            words[endWordIndex] |= lastWordMask;

        }

        checkInvariants();

    }

    /**

     * Sets the bits from the specified {@code fromIndex} (inclusive) to the

     * specified {@code toIndex} (exclusive) to the specified value.

     *

     * @param  fromIndex index of the first bit to be set

     * @param  toIndex index after the last bit to be set

     * @param  value value to set the selected bits to

     * @throws IndexOutOfBoundsException if {@code fromIndex} is negative,

     *         or {@code toIndex} is negative, or {@code fromIndex} is

     *         larger than {@code toIndex}

     * @since  1.4

     */

    public void set(int fromIndex, int toIndex, boolean value) {

        if (value)

            set(fromIndex, toIndex);

        else

            clear(fromIndex, toIndex);

    }

    /**

     * Sets the bit specified by the index to {@code false}.

     *

     * @param  bitIndex the index of the bit to be cleared

     * @throws IndexOutOfBoundsException if the specified index is negative

     * @since  JDK1.0