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 * <p>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}.</p>
023 * 
024 * <p>Each {@code 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 {@code 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 _shift_count;
077
078    /**
079     * <p>Creates a BitField instance.</p>
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        _mask = mask;
087        _shift_count = mask != 0 ? Integer.numberOfTrailingZeros(mask) : 0;
088    }
089
090    /**
091     * <p>Obtains the value for the specified BitField, appropriately
092     * shifted right.</p>
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) >> _shift_count;
106    }
107
108    /**
109     * <p>Obtains the value for the specified BitField, appropriately
110     * shifted right, as a short.</p>
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     * <p>Obtains the value for the specified BitField, unshifted.</p>
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     * <p>Obtains the value for the specified BitField, unshifted.</p>
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     * <p>Returns whether the field is set or not.</p>
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     * <p>Returns whether all of the bits are set or not.</p>
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     * <p>Replaces the bits with new values.</p>
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 << _shift_count) & _mask);
193    }
194
195    /**
196     * <p>Replaces the bits with new values.</p>
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     * <p>Clears the bits.</p>
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     * <p>Clears the bits.</p>
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     * <p>Clears the bits.</p>
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     * <p>Sets the bits.</p>
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     * <p>Sets the bits.</p>
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     * <p>Sets the bits.</p>
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     * <p>Sets a boolean BitField.</p>
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     * <p>Sets a boolean BitField.</p>
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     * <p>Sets a boolean BitField.</p>
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}