    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;
    018
    019/**
    020 * Supports operations on bit-mapped fields. Instances of this class can be
    021 * used to store a flag or data within an {@code int}, {@code short} or
    022 * {@code byte}.
    023 *
    024 * <p>Each {@link BitField} is constructed with a mask value, which indicates
    025 * the bits that will be used to store and retrieve the data for that field.
    026 * For instance, the mask {@code 0xFF} indicates the least-significant byte
    027 * should be used to store the data.</p>
    028 *
    029 * <p>As an example, consider a car painting machine that accepts
    030 * paint instructions as integers. Bit fields can be used to encode this:</p>
    031 *
    032 *<pre>
    033 *    // blue, green and red are 1 byte values (0-255) stored in the three least
    034 *    // significant bytes
    035 *    BitField blue = new BitField(0xFF);
    036 *    BitField green = new BitField(0xFF00);
    037 *    BitField red = new BitField(0xFF0000);
    038 *
    039 *    // anyColor is a flag triggered if any color is used
    040 *    BitField anyColor = new BitField(0xFFFFFF);
    041 *
    042 *    // isMetallic is a single bit flag
    043 *    BitField isMetallic = new BitField(0x1000000);
    044 *</pre>
    045 *
    046 * <p>Using these {@link BitField} instances, a paint instruction can be
    047 * encoded into an integer:</p>
    048 *
    049 *<pre>
    050 *    int paintInstruction = 0;
    051 *    paintInstruction = red.setValue(paintInstruction, 35);
    052 *    paintInstruction = green.setValue(paintInstruction, 100);
    053 *    paintInstruction = blue.setValue(paintInstruction, 255);
    054 *</pre>
    055 *
    056 * <p>Flags and data can be retrieved from the integer:</p>
    057 *
    058 *<pre>
    059 *    // Prints true if red, green or blue is non-zero
    060 *    System.out.println(anyColor.isSet(paintInstruction));   // prints true
    061 *
    062 *    // Prints value of red, green and blue
    063 *    System.out.println(red.getValue(paintInstruction));     // prints 35
    064 *    System.out.println(green.getValue(paintInstruction));   // prints 100
    065 *    System.out.println(blue.getValue(paintInstruction));    // prints 255
    066 *
    067 *    // Prints true if isMetallic was set
    068 *    System.out.println(isMetallic.isSet(paintInstruction)); // prints false
    069 *</pre>
    070 *
    071 * @since 2.0
    072 */
    073public class BitField {
    074
    075    private final int mask;
    076    private final int shiftCount;
    077
    078    /**
    079     * Creates a BitField instance.
    080     *
    081     * @param mask the mask specifying which bits apply to this
    082     *  BitField. Bits that are set in this mask are the bits
    083     *  that this BitField operates on
    084     */
    085    public BitField(final int mask) {
    086        this.mask = mask;
    087        this.shiftCount = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask);
    088    }
    089
    090    /**
    091     * Obtains the value for the specified BitField, appropriately
    092     * shifted right.
    093     *
    094     * <p>Many users of a BitField will want to treat the specified
    095     * bits as an int value, and will not want to be aware that the
    096     * value is stored as a BitField (and so shifted left so many
    097     * bits).</p>
    098     *
    099     * @see #setValue(int,int)
    100     * @param holder the int data containing the bits we're interested
    101     *  in
    102     * @return the selected bits, shifted right appropriately
    103     */
    104    public int getValue(final int holder) {
    105        return getRawValue(holder) >> shiftCount;
    106    }
    107
    108    /**
    109     * Obtains the value for the specified BitField, appropriately
    110     * shifted right, as a short.
    111     *
    112     * <p>Many users of a BitField will want to treat the specified
    113     * bits as an int value, and will not want to be aware that the
    114     * value is stored as a BitField (and so shifted left so many
    115     * bits).</p>
    116     *
    117     * @see #setShortValue(short,short)
    118     * @param holder the short data containing the bits we're
    119     *  interested in
    120     * @return the selected bits, shifted right appropriately
    121     */
    122    public short getShortValue(final short holder) {
    123        return (short) getValue(holder);
    124    }
    125
    126    /**
    127     * Obtains the value for the specified BitField, unshifted.
    128     *
    129     * @param holder the int data containing the bits we're
    130     *  interested in
    131     * @return the selected bits
    132     */
    133    public int getRawValue(final int holder) {
    134        return holder & mask;
    135    }
    136
    137    /**
    138     * Obtains the value for the specified BitField, unshifted.
    139     *
    140     * @param holder the short data containing the bits we're
    141     *  interested in
    142     * @return the selected bits
    143     */
    144    public short getShortRawValue(final short holder) {
    145        return (short) getRawValue(holder);
    146    }
    147
    148    /**
    149     * Returns whether the field is set or not.
    150     *
    151     * <p>This is most commonly used for a single-bit field, which is
    152     * often used to represent a boolean value; the results of using
    153     * it for a multi-bit field is to determine whether *any* of its
    154     * bits are set.</p>
    155     *
    156     * @param holder the int data containing the bits we're interested
    157     *  in
    158     * @return {@code true} if any of the bits are set,
    159     *  else {@code false}
    160     */
    161    public boolean isSet(final int holder) {
    162        return (holder & mask) != 0;
    163    }
    164
    165    /**
    166     * Returns whether all of the bits are set or not.
    167     *
    168     * <p>This is a stricter test than {@link #isSet(int)},
    169     * in that all of the bits in a multi-bit set must be set
    170     * for this method to return {@code true}.</p>
    171     *
    172     * @param holder the int data containing the bits we're
    173     *  interested in
    174     * @return {@code true} if all of the bits are set,
    175     *  else {@code false}
    176     */
    177    public boolean isAllSet(final int holder) {
    178        return (holder & mask) == mask;
    179    }
    180
    181    /**
    182     * Replaces the bits with new values.
    183     *
    184     * @see #getValue(int)
    185     * @param holder the int data containing the bits we're
    186     *  interested in
    187     * @param value the new value for the specified bits
    188     * @return the value of holder with the bits from the value
    189     *  parameter replacing the old bits
    190     */
    191    public int setValue(final int holder, final int value) {
    192        return (holder & ~mask) | ((value << shiftCount) & mask);
    193    }
    194
    195    /**
    196     * Replaces the bits with new values.
    197     *
    198     * @see #getShortValue(short)
    199     * @param holder the short data containing the bits we're
    200     *  interested in
    201     * @param value the new value for the specified bits
    202     * @return the value of holder with the bits from the value
    203     *  parameter replacing the old bits
    204     */
    205    public short setShortValue(final short holder, final short value) {
    206        return (short) setValue(holder, value);
    207    }
    208
    209    /**
    210     * Clears the bits.
    211     *
    212     * @param holder the int data containing the bits we're
    213     *  interested in
    214     * @return the value of holder with the specified bits cleared
    215     *  (set to {@code 0})
    216     */
    217    public int clear(final int holder) {
    218        return holder & ~mask;
    219    }
    220
    221    /**
    222     * Clears the bits.
    223     *
    224     * @param holder the short data containing the bits we're
    225     *  interested in
    226     * @return the value of holder with the specified bits cleared
    227     *  (set to {@code 0})
    228     */
    229    public short clearShort(final short holder) {
    230        return (short) clear(holder);
    231    }
    232
    233    /**
    234     * Clears the bits.
    235     *
    236     * @param holder the byte data containing the bits we're
    237     *  interested in
    238     *
    239     * @return the value of holder with the specified bits cleared
    240     *  (set to {@code 0})
    241     */
    242    public byte clearByte(final byte holder) {
    243        return (byte) clear(holder);
    244    }
    245
    246    /**
    247     * Sets the bits.
    248     *
    249     * @param holder the int data containing the bits we're
    250     *  interested in
    251     * @return the value of holder with the specified bits set
    252     *  to {@code 1}
    253     */
    254    public int set(final int holder) {
    255        return holder | mask;
    256    }
    257
    258    /**
    259     * Sets the bits.
    260     *
    261     * @param holder the short data containing the bits we're
    262     *  interested in
    263     * @return the value of holder with the specified bits set
    264     *  to {@code 1}
    265     */
    266    public short setShort(final short holder) {
    267        return (short) set(holder);
    268    }
    269
    270    /**
    271     * Sets the bits.
    272     *
    273     * @param holder the byte data containing the bits we're
    274     *  interested in
    275     *
    276     * @return the value of holder with the specified bits set
    277     *  to {@code 1}
    278     */
    279    public byte setByte(final byte holder) {
    280        return (byte) set(holder);
    281    }
    282
    283    /**
    284     * Sets a boolean BitField.
    285     *
    286     * @param holder the int data containing the bits we're
    287     *  interested in
    288     * @param flag indicating whether to set or clear the bits
    289     * @return the value of holder with the specified bits set or
    290     *         cleared
    291     */
    292    public int setBoolean(final int holder, final boolean flag) {
    293        return flag ? set(holder) : clear(holder);
    294    }
    295
    296    /**
    297     * Sets a boolean BitField.
    298     *
    299     * @param holder the short data containing the bits we're
    300     *  interested in
    301     * @param flag indicating whether to set or clear the bits
    302     * @return the value of holder with the specified bits set or
    303     *  cleared
    304     */
    305    public short setShortBoolean(final short holder, final boolean flag) {
    306        return flag ? setShort(holder) : clearShort(holder);
    307    }
    308
    309    /**
    310     * Sets a boolean BitField.
    311     *
    312     * @param holder the byte data containing the bits we're
    313     *  interested in
    314     * @param flag indicating whether to set or clear the bits
    315     * @return the value of holder with the specified bits set or
    316     *  cleared
    317     */
    318    public byte setByteBoolean(final byte holder, final boolean flag) {
    319        return flag ? setByte(holder) : clearByte(holder);
    320    }
    321
    322}