Coverage Report - org.apache.commons.lang3.BitField
 
Classes in this File Line Coverage Branch Coverage Complexity
BitField
100%
27/27
100%
14/14
1,278
 
 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  24
     public BitField(final int mask) {
 87  24
         _mask = mask;
 88  24
         int count = 0;
 89  24
         int bit_pattern = mask;
 90  
 
 91  24
         if (bit_pattern != 0) {
 92  110
             while ((bit_pattern & 1) == 0) {
 93  89
                 count++;
 94  89
                 bit_pattern >>= 1;
 95  
             }
 96  
         }
 97  24
         _shift_count = count;
 98  24
     }
 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  528
         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  264
         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  540
         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  6
         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  259
         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  257
         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  1036
         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  518
         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  29
         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  9
         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  11
         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  27
         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  9
         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  9
         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  6
         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  6
         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  20
         return flag ? setByte(holder) : clearByte(holder);
 330  
     }
 331  
 
 332  
 }