/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3;

Supports operations on bit-mapped fields. Instances of this class can be used to store a flag or data within an int, short or byte.
Each BitField is constructed with a mask value, which indicates the bits that will be used to store and retrieve the data for that field. For instance, the mask 0xFF indicates the least-significant byte should be used to store the data.
As an example, consider a car painting machine that accepts
paint instructions as integers. Bit fields can be used to encode this:
   // blue, green and red are 1 byte values (0-255) stored in the three least
   // significant bytes
   BitField blue = new BitField(0xFF);
   BitField green = new BitField(0xFF00);
   BitField red = new BitField(0xFF0000);
   // anyColor is a flag triggered if any color is used
   BitField anyColor = new BitField(0xFFFFFF);
   // isMetallic is a single bit flag
   BitField isMetallic = new BitField(0x1000000);

Using these BitField instances, a paint instruction can be encoded into an integer:
   int paintInstruction = 0;
   paintInstruction = red.setValue(paintInstruction, 35);
   paintInstruction = green.setValue(paintInstruction, 100);
   paintInstruction = blue.setValue(paintInstruction, 255);

Flags and data can be retrieved from the integer:
   // Prints true if red, green or blue is non-zero
   System.out.println(anyColor.isSet(paintInstruction));   // prints true
   // Prints value of red, green and blue
   System.out.println(red.getValue(paintInstruction));     // prints 35
   System.out.println(green.getValue(paintInstruction));   // prints 100
   System.out.println(blue.getValue(paintInstruction));    // prints 255
   // Prints true if isMetallic was set
   System.out.println(isMetallic.isSet(paintInstruction)); // prints false

Since:
2.0/**
 * <p>Supports operations on bit-mapped fields. Instances of this class can be
 * used to store a flag or data within an {@code int}, {@code short} or
 * {@code byte}.</p>
 *
 * <p>Each {@code BitField} is constructed with a mask value, which indicates
 * the bits that will be used to store and retrieve the data for that field.
 * For instance, the mask {@code 0xFF} indicates the least-significant byte
 * should be used to store the data.</p>
 *
 * <p>As an example, consider a car painting machine that accepts
 * paint instructions as integers. Bit fields can be used to encode this:</p>
 *
 *<pre>
 *    // blue, green and red are 1 byte values (0-255) stored in the three least
 *    // significant bytes
 *    BitField blue = new BitField(0xFF);
 *    BitField green = new BitField(0xFF00);
 *    BitField red = new BitField(0xFF0000);
 *
 *    // anyColor is a flag triggered if any color is used
 *    BitField anyColor = new BitField(0xFFFFFF);
 *
 *    // isMetallic is a single bit flag
 *    BitField isMetallic = new BitField(0x1000000);
 *</pre>
 *
 * <p>Using these {@code BitField} instances, a paint instruction can be
 * encoded into an integer:</p>
 *
 *<pre>
 *    int paintInstruction = 0;
 *    paintInstruction = red.setValue(paintInstruction, 35);
 *    paintInstruction = green.setValue(paintInstruction, 100);
 *    paintInstruction = blue.setValue(paintInstruction, 255);
 *</pre>
 *
 * <p>Flags and data can be retrieved from the integer:</p>
 *
 *<pre>
 *    // Prints true if red, green or blue is non-zero
 *    System.out.println(anyColor.isSet(paintInstruction));   // prints true
 *
 *    // Prints value of red, green and blue
 *    System.out.println(red.getValue(paintInstruction));     // prints 35
 *    System.out.println(green.getValue(paintInstruction));   // prints 100
 *    System.out.println(blue.getValue(paintInstruction));    // prints 255
 *
 *    // Prints true if isMetallic was set
 *    System.out.println(isMetallic.isSet(paintInstruction)); // prints false
 *</pre>
 *
 * @since 2.0
 */
public class BitField {

    private final int _mask;
    private final int _shift_count;

    
Creates a BitField instance.
Params:
mask – the mask specifying which bits apply to this
 BitField. Bits that are set in this mask are the bits
 that this BitField operates on/**
     * <p>Creates a BitField instance.</p>
     *
     * @param mask the mask specifying which bits apply to this
     *  BitField. Bits that are set in this mask are the bits
     *  that this BitField operates on
     */
    public BitField(final int mask) {
        _mask = mask;
        _shift_count = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask);
    }

    
Obtains the value for the specified BitField, appropriately
shifted right.
Many users of a BitField will want to treat the specified
bits as an int value, and will not want to be aware that the
value is stored as a BitField (and so shifted left so many
bits).
Params:
holder – the int data containing the bits we're interested
 in
See Also:
setValue(int, int)
Returns:
the selected bits, shifted right appropriately/**
     * <p>Obtains the value for the specified BitField, appropriately
     * shifted right.</p>
     *
     * <p>Many users of a BitField will want to treat the specified
     * bits as an int value, and will not want to be aware that the
     * value is stored as a BitField (and so shifted left so many
     * bits).</p>
     *
     * @see #setValue(int,int)
     * @param holder the int data containing the bits we're interested
     *  in
     * @return the selected bits, shifted right appropriately
     */
    public int getValue(final int holder) {
        return getRawValue(holder) >> _shift_count;
    }

    
Obtains the value for the specified BitField, appropriately
shifted right, as a short.
Many users of a BitField will want to treat the specified
bits as an int value, and will not want to be aware that the
value is stored as a BitField (and so shifted left so many
bits).
Params:
holder – the short data containing the bits we're
 interested in
See Also:
setShortValue(short, short)
Returns:
the selected bits, shifted right appropriately/**
     * <p>Obtains the value for the specified BitField, appropriately
     * shifted right, as a short.</p>
     *
     * <p>Many users of a BitField will want to treat the specified
     * bits as an int value, and will not want to be aware that the
     * value is stored as a BitField (and so shifted left so many
     * bits).</p>
     *
     * @see #setShortValue(short,short)
     * @param holder the short data containing the bits we're
     *  interested in
     * @return the selected bits, shifted right appropriately
     */
    public short getShortValue(final short holder) {
        return (short) getValue(holder);
    }

    
Obtains the value for the specified BitField, unshifted.
Params:
holder – the int data containing the bits we're
 interested in
Returns:
the selected bits/**
     * <p>Obtains the value for the specified BitField, unshifted.</p>
     *
     * @param holder the int data containing the bits we're
     *  interested in
     * @return the selected bits
     */
    public int getRawValue(final int holder) {
        return holder & _mask;
    }

    
Obtains the value for the specified BitField, unshifted.
Params:
holder – the short data containing the bits we're
 interested in
Returns:
the selected bits/**
     * <p>Obtains the value for the specified BitField, unshifted.</p>
     *
     * @param holder the short data containing the bits we're
     *  interested in
     * @return the selected bits
     */
    public short getShortRawValue(final short holder) {
        return (short) getRawValue(holder);
    }

    
Returns whether the field is set or not.
This is most commonly used for a single-bit field, which is
often used to represent a boolean value; the results of using
it for a multi-bit field is to determine whether *any* of its
bits are set.
Params:
holder – the int data containing the bits we're interested
 in
Returns:
true if any of the bits are set, else false/**
     * <p>Returns whether the field is set or not.</p>
     *
     * <p>This is most commonly used for a single-bit field, which is
     * often used to represent a boolean value; the results of using
     * it for a multi-bit field is to determine whether *any* of its
     * bits are set.</p>
     *
     * @param holder the int data containing the bits we're interested
     *  in
     * @return {@code true} if any of the bits are set,
     *  else {@code false}
     */
    public boolean isSet(final int holder) {
        return (holder & _mask) != 0;
    }

    
Returns whether all of the bits are set or not.
This is a stricter test than isSet(int), in that all of the bits in a multi-bit set must be set for this method to return true.
Params:
holder – the int data containing the bits we're
 interested in
Returns:
true if all of the bits are set, else false/**
     * <p>Returns whether all of the bits are set or not.</p>
     *
     * <p>This is a stricter test than {@link #isSet(int)},
     * in that all of the bits in a multi-bit set must be set
     * for this method to return {@code true}.</p>
     *
     * @param holder the int data containing the bits we're
     *  interested in
     * @return {@code true} if all of the bits are set,
     *  else {@code false}
     */
    public boolean isAllSet(final int holder) {
        return (holder & _mask) == _mask;
    }

    
Replaces the bits with new values.
Params:
holder – the int data containing the bits we're
 interested in
value – the new value for the specified bits
See Also:
getValue(int)
Returns:
the value of holder with the bits from the value
 parameter replacing the old bits/**
     * <p>Replaces the bits with new values.</p>
     *
     * @see #getValue(int)
     * @param holder the int data containing the bits we're
     *  interested in
     * @param value the new value for the specified bits
     * @return the value of holder with the bits from the value
     *  parameter replacing the old bits
     */
    public int setValue(final int holder, final int value) {
        return (holder & ~_mask) | ((value << _shift_count) & _mask);
    }

    
Replaces the bits with new values.
Params:
holder – the short data containing the bits we're
 interested in
value – the new value for the specified bits
See Also:
getShortValue(short)
Returns:
the value of holder with the bits from the value
 parameter replacing the old bits/**
     * <p>Replaces the bits with new values.</p>
     *
     * @see #getShortValue(short)
     * @param holder the short data containing the bits we're
     *  interested in
     * @param value the new value for the specified bits
     * @return the value of holder with the bits from the value
     *  parameter replacing the old bits
     */
    public short setShortValue(final short holder, final short value) {
        return (short) setValue(holder, value);
    }

    
Clears the bits.
Params:
holder – the int data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits cleared (set to 0)/**
     * <p>Clears the bits.</p>
     *
     * @param holder the int data containing the bits we're
     *  interested in
     * @return the value of holder with the specified bits cleared
     *  (set to {@code 0})
     */
    public int clear(final int holder) {
        return holder & ~_mask;
    }

    
Clears the bits.
Params:
holder – the short data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits cleared (set to 0)/**
     * <p>Clears the bits.</p>
     *
     * @param holder the short data containing the bits we're
     *  interested in
     * @return the value of holder with the specified bits cleared
     *  (set to {@code 0})
     */
    public short clearShort(final short holder) {
        return (short) clear(holder);
    }

    
Clears the bits.
Params:
holder – the byte data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits cleared (set to 0)/**
     * <p>Clears the bits.</p>
     *
     * @param holder the byte data containing the bits we're
     *  interested in
     *
     * @return the value of holder with the specified bits cleared
     *  (set to {@code 0})
     */
    public byte clearByte(final byte holder) {
        return (byte) clear(holder);
    }

    
Sets the bits.
Params:
holder – the int data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits set to 1/**
     * <p>Sets the bits.</p>
     *
     * @param holder the int data containing the bits we're
     *  interested in
     * @return the value of holder with the specified bits set
     *  to {@code 1}
     */
    public int set(final int holder) {
        return holder | _mask;
    }

    
Sets the bits.
Params:
holder – the short data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits set to 1/**
     * <p>Sets the bits.</p>
     *
     * @param holder the short data containing the bits we're
     *  interested in
     * @return the value of holder with the specified bits set
     *  to {@code 1}
     */
    public short setShort(final short holder) {
        return (short) set(holder);
    }

    
Sets the bits.
Params:
holder – the byte data containing the bits we're
 interested in
Returns:
the value of holder with the specified bits set to 1/**
     * <p>Sets the bits.</p>
     *
     * @param holder the byte data containing the bits we're
     *  interested in
     *
     * @return the value of holder with the specified bits set
     *  to {@code 1}
     */
    public byte setByte(final byte holder) {
        return (byte) set(holder);
    }

    
Sets a boolean BitField.
Params:
holder – the int data containing the bits we're
 interested in
flag – indicating whether to set or clear the bits
Returns:
the value of holder with the specified bits set or
        cleared/**
     * <p>Sets a boolean BitField.</p>
     *
     * @param holder the int data containing the bits we're
     *  interested in
     * @param flag indicating whether to set or clear the bits
     * @return the value of holder with the specified bits set or
     *         cleared
     */
    public int setBoolean(final int holder, final boolean flag) {
        return flag ? set(holder) : clear(holder);
    }

    
Sets a boolean BitField.
Params:
holder – the short data containing the bits we're
 interested in
flag – indicating whether to set or clear the bits
Returns:
the value of holder with the specified bits set or
 cleared/**
     * <p>Sets a boolean BitField.</p>
     *
     * @param holder the short data containing the bits we're
     *  interested in
     * @param flag indicating whether to set or clear the bits
     * @return the value of holder with the specified bits set or
     *  cleared
     */
    public short setShortBoolean(final short holder, final boolean flag) {
        return flag ? setShort(holder) : clearShort(holder);
    }

    
Sets a boolean BitField.
Params:
holder – the byte data containing the bits we're
 interested in
flag – indicating whether to set or clear the bits
Returns:
the value of holder with the specified bits set or
 cleared/**
     * <p>Sets a boolean BitField.</p>
     *
     * @param holder the byte data containing the bits we're
     *  interested in
     * @param flag indicating whether to set or clear the bits
     * @return the value of holder with the specified bits set or
     *  cleared
     */
    public byte setByteBoolean(final byte holder, final boolean flag) {
        return flag ? setByte(holder) : clearByte(holder);
    }

}