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 * 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}. 23 * 24 * <p>Each {@link 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 {@link 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 shiftCount; 77 78 /** 79 * Creates a BitField instance. 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 */ BitField(final int mask)85 public BitField(final int mask) { 86 this.mask = mask; 87 this.shiftCount = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask); 88 } 89 90 /** 91 * Obtains the value for the specified BitField, appropriately 92 * shifted right. 93 * 94 * <p>Many users of a BitField will want to treat the specified 95 * bits as an int value, and will not want to be aware that the 96 * value is stored as a BitField (and so shifted left so many 97 * bits).</p> 98 * 99 * @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 */ getValue(final int holder)104 public int getValue(final int holder) { 105 return getRawValue(holder) >> shiftCount; 106 } 107 108 /** 109 * Obtains the value for the specified BitField, appropriately 110 * shifted right, as a short. 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 */ getShortValue(final short holder)122 public short getShortValue(final short holder) { 123 return (short) getValue(holder); 124 } 125 126 /** 127 * Obtains the value for the specified BitField, unshifted. 128 * 129 * @param holder the int data containing the bits we're 130 * interested in 131 * @return the selected bits 132 */ getRawValue(final int holder)133 public int getRawValue(final int holder) { 134 return holder & mask; 135 } 136 137 /** 138 * Obtains the value for the specified BitField, unshifted. 139 * 140 * @param holder the short data containing the bits we're 141 * interested in 142 * @return the selected bits 143 */ getShortRawValue(final short holder)144 public short getShortRawValue(final short holder) { 145 return (short) getRawValue(holder); 146 } 147 148 /** 149 * Returns whether the field is set or not. 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 */ isSet(final int holder)161 public boolean isSet(final int holder) { 162 return (holder & mask) != 0; 163 } 164 165 /** 166 * Returns whether all of the bits are set or not. 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 */ isAllSet(final int holder)177 public boolean isAllSet(final int holder) { 178 return (holder & mask) == mask; 179 } 180 181 /** 182 * Replaces the bits with new values. 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 */ setValue(final int holder, final int value)191 public int setValue(final int holder, final int value) { 192 return (holder & ~mask) | ((value << shiftCount) & mask); 193 } 194 195 /** 196 * Replaces the bits with new values. 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 */ setShortValue(final short holder, final short value)205 public short setShortValue(final short holder, final short value) { 206 return (short) setValue(holder, value); 207 } 208 209 /** 210 * Clears the bits. 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 */ clear(final int holder)217 public int clear(final int holder) { 218 return holder & ~mask; 219 } 220 221 /** 222 * Clears the bits. 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 */ clearShort(final short holder)229 public short clearShort(final short holder) { 230 return (short) clear(holder); 231 } 232 233 /** 234 * Clears the bits. 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 */ clearByte(final byte holder)242 public byte clearByte(final byte holder) { 243 return (byte) clear(holder); 244 } 245 246 /** 247 * Sets the bits. 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 */ set(final int holder)254 public int set(final int holder) { 255 return holder | mask; 256 } 257 258 /** 259 * Sets the bits. 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 */ setShort(final short holder)266 public short setShort(final short holder) { 267 return (short) set(holder); 268 } 269 270 /** 271 * Sets the bits. 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 */ setByte(final byte holder)279 public byte setByte(final byte holder) { 280 return (byte) set(holder); 281 } 282 283 /** 284 * Sets a boolean BitField. 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 */ setBoolean(final int holder, final boolean flag)292 public int setBoolean(final int holder, final boolean flag) { 293 return flag ? set(holder) : clear(holder); 294 } 295 296 /** 297 * Sets a boolean BitField. 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 */ setShortBoolean(final short holder, final boolean flag)305 public short setShortBoolean(final short holder, final boolean flag) { 306 return flag ? setShort(holder) : clearShort(holder); 307 } 308 309 /** 310 * Sets a boolean BitField. 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 */ setByteBoolean(final byte holder, final boolean flag)318 public byte setByteBoolean(final byte holder, final boolean flag) { 319 return flag ? setByte(holder) : clearByte(holder); 320 } 321 322 } 323