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     * Clears the bits.
092     *
093     * @param holder the int data containing the bits we're
094     *  interested in
095     * @return the value of holder with the specified bits cleared
096     *  (set to {@code 0})
097     */
098    public int clear(final int holder) {
099        return holder & ~mask;
100    }
101
102    /**
103     * Clears the bits.
104     *
105     * @param holder the byte data containing the bits we're
106     *  interested in
107     *
108     * @return the value of holder with the specified bits cleared
109     *  (set to {@code 0})
110     */
111    public byte clearByte(final byte holder) {
112        return (byte) clear(holder);
113    }
114
115    /**
116     * Clears the bits.
117     *
118     * @param holder the short data containing the bits we're
119     *  interested in
120     * @return the value of holder with the specified bits cleared
121     *  (set to {@code 0})
122     */
123    public short clearShort(final short holder) {
124        return (short) clear(holder);
125    }
126
127    /**
128     * Obtains the value for the specified BitField, unshifted.
129     *
130     * @param holder the int data containing the bits we're
131     *  interested in
132     * @return the selected bits
133     */
134    public int getRawValue(final int holder) {
135        return holder & mask;
136    }
137
138    /**
139     * Obtains the value for the specified BitField, unshifted.
140     *
141     * @param holder the short data containing the bits we're
142     *  interested in
143     * @return the selected bits
144     */
145    public short getShortRawValue(final short holder) {
146        return (short) getRawValue(holder);
147    }
148
149    /**
150     * Obtains the value for the specified BitField, appropriately
151     * shifted right, as a short.
152     *
153     * <p>Many users of a BitField will want to treat the specified
154     * bits as an int value, and will not want to be aware that the
155     * value is stored as a BitField (and so shifted left so many
156     * bits).</p>
157     *
158     * @see #setShortValue(short,short)
159     * @param holder the short data containing the bits we're
160     *  interested in
161     * @return the selected bits, shifted right appropriately
162     */
163    public short getShortValue(final short holder) {
164        return (short) getValue(holder);
165    }
166
167    /**
168     * Obtains the value for the specified BitField, appropriately
169     * shifted right.
170     *
171     * <p>Many users of a BitField will want to treat the specified
172     * bits as an int value, and will not want to be aware that the
173     * value is stored as a BitField (and so shifted left so many
174     * bits).</p>
175     *
176     * @see #setValue(int,int)
177     * @param holder the int data containing the bits we're interested
178     *  in
179     * @return the selected bits, shifted right appropriately
180     */
181    public int getValue(final int holder) {
182        return getRawValue(holder) >> shiftCount;
183    }
184
185    /**
186     * Returns whether all of the bits are set or not.
187     *
188     * <p>This is a stricter test than {@link #isSet(int)},
189     * in that all of the bits in a multi-bit set must be set
190     * for this method to return {@code true}.</p>
191     *
192     * @param holder the int data containing the bits we're
193     *  interested in
194     * @return {@code true} if all of the bits are set,
195     *  else {@code false}
196     */
197    public boolean isAllSet(final int holder) {
198        return (holder & mask) == mask;
199    }
200
201    /**
202     * Returns whether the field is set or not.
203     *
204     * <p>This is most commonly used for a single-bit field, which is
205     * often used to represent a boolean value; the results of using
206     * it for a multi-bit field is to determine whether *any* of its
207     * bits are set.</p>
208     *
209     * @param holder the int data containing the bits we're interested
210     *  in
211     * @return {@code true} if any of the bits are set,
212     *  else {@code false}
213     */
214    public boolean isSet(final int holder) {
215        return (holder & mask) != 0;
216    }
217
218    /**
219     * Sets the bits.
220     *
221     * @param holder the int data containing the bits we're
222     *  interested in
223     * @return the value of holder with the specified bits set
224     *  to {@code 1}
225     */
226    public int set(final int holder) {
227        return holder | mask;
228    }
229
230    /**
231     * Sets a boolean BitField.
232     *
233     * @param holder the int data containing the bits we're
234     *  interested in
235     * @param flag indicating whether to set or clear the bits
236     * @return the value of holder with the specified bits set or
237     *         cleared
238     */
239    public int setBoolean(final int holder, final boolean flag) {
240        return flag ? set(holder) : clear(holder);
241    }
242
243    /**
244     * Sets the bits.
245     *
246     * @param holder the byte data containing the bits we're
247     *  interested in
248     *
249     * @return the value of holder with the specified bits set
250     *  to {@code 1}
251     */
252    public byte setByte(final byte holder) {
253        return (byte) set(holder);
254    }
255
256    /**
257     * Sets a boolean BitField.
258     *
259     * @param holder the byte data containing the bits we're
260     *  interested in
261     * @param flag indicating whether to set or clear the bits
262     * @return the value of holder with the specified bits set or
263     *  cleared
264     */
265    public byte setByteBoolean(final byte holder, final boolean flag) {
266        return flag ? setByte(holder) : clearByte(holder);
267    }
268
269    /**
270     * Sets the bits.
271     *
272     * @param holder the short data containing the bits we're
273     *  interested in
274     * @return the value of holder with the specified bits set
275     *  to {@code 1}
276     */
277    public short setShort(final short holder) {
278        return (short) set(holder);
279    }
280
281    /**
282     * Sets a boolean BitField.
283     *
284     * @param holder the short data containing the bits we're
285     *  interested in
286     * @param flag indicating whether to set or clear the bits
287     * @return the value of holder with the specified bits set or
288     *  cleared
289     */
290    public short setShortBoolean(final short holder, final boolean flag) {
291        return flag ? setShort(holder) : clearShort(holder);
292    }
293
294    /**
295     * Replaces the bits with new values.
296     *
297     * @see #getShortValue(short)
298     * @param holder the short data containing the bits we're
299     *  interested in
300     * @param value the new value for the specified bits
301     * @return the value of holder with the bits from the value
302     *  parameter replacing the old bits
303     */
304    public short setShortValue(final short holder, final short value) {
305        return (short) setValue(holder, value);
306    }
307
308    /**
309     * Replaces the bits with new values.
310     *
311     * @see #getValue(int)
312     * @param holder the int data containing the bits we're
313     *  interested in
314     * @param value the new value for the specified bits
315     * @return the value of holder with the bits from the value
316     *  parameter replacing the old bits
317     */
318    public int setValue(final int holder, final int value) {
319        return (holder & ~mask) | ((value << shiftCount) & mask);
320    }
321
322}