View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3;
18  
19  /**
20   * <p>Supports operations on bit-mapped fields. Instances of this class can be 
21   * used to store a flag or data within an {@code int}, {@code short} or 
22   * {@code byte}.</p>
23   * 
24   * <p>Each {@code BitField} is constructed with a mask value, which indicates
25   * the bits that will be used to store and retrieve the data for that field. 
26   * For instance, the mask {@code 0xFF} indicates the least-significant byte 
27   * should be used to store the data.</p>
28   * 
29   * <p>As an example, consider a car painting machine that accepts
30   * paint instructions as integers. Bit fields can be used to encode this:</p>
31   *
32   *<pre>
33   *    // blue, green and red are 1 byte values (0-255) stored in the three least 
34   *    // significant bytes
35   *    BitField blue = new BitField(0xFF);
36   *    BitField green = new BitField(0xFF00);
37   *    BitField red = new BitField(0xFF0000);
38   * 
39   *    // anyColor is a flag triggered if any color is used
40   *    BitField anyColor = new BitField(0xFFFFFF);
41   * 
42   *    // isMetallic is a single bit flag
43   *    BitField isMetallic = new BitField(0x1000000);
44   *</pre>
45   *
46   * <p>Using these {@code BitField} instances, a paint instruction can be
47   * encoded into an integer:</p>
48   *
49   *<pre>
50   *    int paintInstruction = 0;
51   *    paintInstruction = red.setValue(paintInstruction, 35);
52   *    paintInstruction = green.setValue(paintInstruction, 100);
53   *    paintInstruction = blue.setValue(paintInstruction, 255);
54   *</pre>
55   *
56   * <p>Flags and data can be retrieved from the integer:</p>
57   * 
58   *<pre>
59   *    // Prints true if red, green or blue is non-zero
60   *    System.out.println(anyColor.isSet(paintInstruction));   // prints true
61   *   
62   *    // Prints value of red, green and blue
63   *    System.out.println(red.getValue(paintInstruction));     // prints 35
64   *    System.out.println(green.getValue(paintInstruction));   // prints 100
65   *    System.out.println(blue.getValue(paintInstruction));    // prints 255
66   *   
67   *    // Prints true if isMetallic was set 
68   *    System.out.println(isMetallic.isSet(paintInstruction)); // prints false
69   *</pre>
70   *
71   * @since 2.0
72   */
73  public class BitField {
74      
75      private final int _mask;
76      private final int _shift_count;
77  
78      /**
79       * <p>Creates a BitField instance.</p>
80       *
81       * @param mask the mask specifying which bits apply to this
82       *  BitField. Bits that are set in this mask are the bits
83       *  that this BitField operates on
84       */
85      public BitField(final int mask) {
86          _mask = mask;
87          int count = 0;
88          int bit_pattern = mask;
89  
90          if (bit_pattern != 0) {
91              while ((bit_pattern & 1) == 0) {
92                  count++;
93                  bit_pattern >>= 1;
94              }
95          }
96          _shift_count = count;
97      }
98  
99      /**
100      * <p>Obtains the value for the specified BitField, appropriately
101      * shifted right.</p>
102      *
103      * <p>Many users of a BitField will want to treat the specified
104      * bits as an int value, and will not want to be aware that the
105      * value is stored as a BitField (and so shifted left so many
106      * bits).</p>
107      *
108      * @see #setValue(int,int)
109      * @param holder the int data containing the bits we're interested
110      *  in
111      * @return the selected bits, shifted right appropriately
112      */
113     public int getValue(final int holder) {
114         return getRawValue(holder) >> _shift_count;
115     }
116 
117     /**
118      * <p>Obtains the value for the specified BitField, appropriately
119      * shifted right, as a short.</p>
120      *
121      * <p>Many users of a BitField will want to treat the specified
122      * bits as an int value, and will not want to be aware that the
123      * value is stored as a BitField (and so shifted left so many
124      * bits).</p>
125      *
126      * @see #setShortValue(short,short)
127      * @param holder the short data containing the bits we're
128      *  interested in
129      * @return the selected bits, shifted right appropriately
130      */
131     public short getShortValue(final short holder) {
132         return (short) getValue(holder);
133     }
134 
135     /**
136      * <p>Obtains the value for the specified BitField, unshifted.</p>
137      *
138      * @param holder the int data containing the bits we're
139      *  interested in
140      * @return the selected bits
141      */
142     public int getRawValue(final int holder) {
143         return holder & _mask;
144     }
145 
146     /**
147      * <p>Obtains the value for the specified BitField, unshifted.</p>
148      *
149      * @param holder the short data containing the bits we're
150      *  interested in
151      * @return the selected bits
152      */
153     public short getShortRawValue(final short holder) {
154         return (short) getRawValue(holder);
155     }
156 
157     /**
158      * <p>Returns whether the field is set or not.</p>
159      *
160      * <p>This is most commonly used for a single-bit field, which is
161      * often used to represent a boolean value; the results of using
162      * it for a multi-bit field is to determine whether *any* of its
163      * bits are set.</p>
164      *
165      * @param holder the int data containing the bits we're interested
166      *  in
167      * @return {@code true} if any of the bits are set,
168      *  else {@code false}
169      */
170     public boolean isSet(final int holder) {
171         return (holder & _mask) != 0;
172     }
173 
174     /**
175      * <p>Returns whether all of the bits are set or not.</p>
176      *
177      * <p>This is a stricter test than {@link #isSet(int)},
178      * in that all of the bits in a multi-bit set must be set
179      * for this method to return {@code true}.</p>
180      *
181      * @param holder the int data containing the bits we're
182      *  interested in
183      * @return {@code true} if all of the bits are set,
184      *  else {@code false}
185      */
186     public boolean isAllSet(final int holder) {
187         return (holder & _mask) == _mask;
188     }
189 
190     /**
191      * <p>Replaces the bits with new values.</p>
192      *
193      * @see #getValue(int)
194      * @param holder the int data containing the bits we're
195      *  interested in
196      * @param value the new value for the specified bits
197      * @return the value of holder with the bits from the value
198      *  parameter replacing the old bits
199      */
200     public int setValue(final int holder, final int value) {
201         return (holder & ~_mask) | ((value << _shift_count) & _mask);
202     }
203 
204     /**
205      * <p>Replaces the bits with new values.</p>
206      *
207      * @see #getShortValue(short)
208      * @param holder the short data containing the bits we're
209      *  interested in
210      * @param value the new value for the specified bits
211      * @return the value of holder with the bits from the value
212      *  parameter replacing the old bits
213      */
214     public short setShortValue(final short holder, final short value) {
215         return (short) setValue(holder, value);
216     }
217 
218     /**
219      * <p>Clears the bits.</p>
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 cleared
224      *  (set to {@code 0})
225      */
226     public int clear(final int holder) {
227         return holder & ~_mask;
228     }
229 
230     /**
231      * <p>Clears the bits.</p>
232      *
233      * @param holder the short data containing the bits we're
234      *  interested in
235      * @return the value of holder with the specified bits cleared
236      *  (set to {@code 0})
237      */
238     public short clearShort(final short holder) {
239         return (short) clear(holder);
240     }
241 
242     /**
243      * <p>Clears the bits.</p>
244      *
245      * @param holder the byte data containing the bits we're
246      *  interested in
247      *
248      * @return the value of holder with the specified bits cleared
249      *  (set to {@code 0})
250      */
251     public byte clearByte(final byte holder) {
252         return (byte) clear(holder);
253     }
254 
255     /**
256      * <p>Sets the bits.</p>
257      *
258      * @param holder the int data containing the bits we're
259      *  interested in
260      * @return the value of holder with the specified bits set
261      *  to {@code 1}
262      */
263     public int set(final int holder) {
264         return holder | _mask;
265     }
266 
267     /**
268      * <p>Sets the bits.</p>
269      *
270      * @param holder the short data containing the bits we're
271      *  interested in
272      * @return the value of holder with the specified bits set
273      *  to {@code 1}
274      */
275     public short setShort(final short holder) {
276         return (short) set(holder);
277     }
278 
279     /**
280      * <p>Sets the bits.</p>
281      *
282      * @param holder the byte data containing the bits we're
283      *  interested in
284      *
285      * @return the value of holder with the specified bits set
286      *  to {@code 1}
287      */
288     public byte setByte(final byte holder) {
289         return (byte) set(holder);
290     }
291 
292     /**
293      * <p>Sets a boolean BitField.</p>
294      *
295      * @param holder the int data containing the bits we're
296      *  interested in
297      * @param flag indicating whether to set or clear the bits
298      * @return the value of holder with the specified bits set or
299      *         cleared
300      */
301     public int setBoolean(final int holder, final boolean flag) {
302         return flag ? set(holder) : clear(holder);
303     }
304 
305     /**
306      * <p>Sets a boolean BitField.</p>
307      *
308      * @param holder the short data containing the bits we're
309      *  interested in
310      * @param flag indicating whether to set or clear the bits
311      * @return the value of holder with the specified bits set or
312      *  cleared
313      */
314     public short setShortBoolean(final short holder, final boolean flag) {
315         return flag ? setShort(holder) : clearShort(holder);
316     }
317 
318     /**
319      * <p>Sets a boolean BitField.</p>
320      *
321      * @param holder the byte data containing the bits we're
322      *  interested in
323      * @param flag indicating whether to set or clear the bits
324      * @return the value of holder with the specified bits set or
325      *  cleared
326      */
327     public byte setByteBoolean(final byte holder, final boolean flag) {
328         return flag ? setByte(holder) : clearByte(holder);
329     }
330 
331 }