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