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 * https://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
18 package org.apache.commons.lang3;
19
20 /**
21 * Supports operations on bit-mapped fields. Instances of this class can be used to store a flag or data within an {@code int}, {@code short} or {@code byte}.
22 * <p>
23 * Each {@link BitField} is constructed with a mask value, which indicates the bits that will be used to store and retrieve the data for that field. For
24 * instance, the mask {@code 0xFF} indicates the least-significant byte should be used to store the data.
25 * </p>
26 * <p>
27 * As an example, consider a car painting machine that accepts paint instructions as integers. Bit fields can be used to encode this:
28 * </p>
29 *
30 * <pre>
31 *
32 * // blue, green and red are 1 byte values (0-255) stored in the three least
33 * // significant bytes
34 * BitField blue = new BitField(0xFF);
35 *
36 * BitField green = new BitField(0xFF00);
37 *
38 * BitField red = new BitField(0xFF0000);
39 *
40 * // anyColor is a flag triggered if any color is used
41 * BitField anyColor = new BitField(0xFFFFFF);
42 *
43 * // isMetallic is a single bit flag
44 * BitField isMetallic = new BitField(0x1000000);
45 * </pre>
46 * <p>
47 * Using these {@link BitField} instances, a paint instruction can be encoded into an integer:
48 * </p>
49 *
50 * <pre>
51 * int paintInstruction = 0;
52 * paintInstruction = red.setValue(paintInstruction, 35);
53 * paintInstruction = green.setValue(paintInstruction, 100);
54 * paintInstruction = blue.setValue(paintInstruction, 255);
55 * </pre>
56 * <p>
57 * Flags and data can be retrieved from the integer:
58 * </p>
59 *
60 * <pre>
61 * // Prints true if red, green or blue is non-zero
62 * System.out.println(anyColor.isSet(paintInstruction)); // prints true
63 * // Prints value of red, green and blue
64 * System.out.println(red.getValue(paintInstruction)); // prints 35
65 * System.out.println(green.getValue(paintInstruction)); // prints 100
66 * System.out.println(blue.getValue(paintInstruction)); // prints 255
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 long mask;
76
77 private final int shiftCount;
78
79 /**
80 * Creates a BitField instance.
81 *
82 * @param mask the mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
83 */
84 public BitField(final int mask) {
85 this.mask = mask;
86 this.shiftCount = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask);
87 }
88
89 /**
90 * Creates a BitField instance.
91 *
92 * @param mask the mask specifying which bits apply to this BitField. Bits that are set in this mask are the bits that this BitField operates on.
93 * @since 3.21.0
94 */
95 public BitField(final long mask) {
96 this.mask = mask;
97 this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask);
98 }
99
100 /**
101 * Clears the bits.
102 *
103 * @param holder the int data containing the bits we're interested in.
104 * @return the value of holder with the specified bits cleared (set to {@code 0}).
105 */
106 public int clear(final int holder) {
107 return (int) (holder & ~mask);
108 }
109
110 /**
111 * Clears the bits.
112 *
113 * @param holder the long data containing the bits we're interested in.
114 * @return the value of holder with the specified bits cleared (set to {@code 0}).
115 * @since 3.21.0
116 */
117 public long clear(final long holder) {
118 return holder & ~mask;
119 }
120
121 /**
122 * Clears the bits.
123 *
124 * @param holder the byte data containing the bits we're interested in.
125 * @return the value of holder with the specified bits cleared (set to {@code 0}).
126 */
127 public byte clearByte(final byte holder) {
128 return (byte) clear(holder);
129 }
130
131 /**
132 * Clears the bits.
133 *
134 * @param holder the short data containing the bits we're interested in.
135 * @return the value of holder with the specified bits cleared (set to {@code 0}).
136 */
137 public short clearShort(final short holder) {
138 return (short) clear(holder);
139 }
140
141 /**
142 * Gets the value for the specified BitField, unshifted.
143 *
144 * @param holder the int data containing the bits we're interested in.
145 * @return the selected bits.
146 */
147 public int getRawValue(final int holder) {
148 return (int) (holder & mask);
149 }
150
151 /**
152 * Gets the value for the specified BitField, unshifted.
153 *
154 * @param holder the long data containing the bits we're interested in.
155 * @return the selected bits.
156 * @since 3.21.0
157 */
158 public long getRawValue(final long holder) {
159 return holder & mask;
160 }
161
162 /**
163 * Obtains the value for the specified BitField, unshifted.
164 *
165 * @param holder the short data containing the bits we're interested in.
166 * @return the selected bits.
167 */
168 public short getShortRawValue(final short holder) {
169 return (short) getRawValue(holder);
170 }
171
172 /**
173 * Gets the value for the specified BitField, appropriately shifted right, as a short.
174 * <p>
175 * Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and
176 * so shifted left so many bits).
177 * </p>
178 *
179 * @param holder the short data containing the bits we're interested in.
180 * @return the selected bits, shifted right appropriately.
181 * @see #setShortValue(short,short)
182 */
183 public short getShortValue(final short holder) {
184 return (short) getValue(holder);
185 }
186
187 /**
188 * Gets the value for the specified BitField, appropriately shifted right.
189 * <p>
190 * Many users of a BitField will want to treat the specified bits as an int value, and will not want to be aware that the value is stored as a BitField (and
191 * so shifted left so many bits).
192 * </p>
193 *
194 * @param holder the int data containing the bits we're interested in.
195 * @return the selected bits, shifted right appropriately.
196 * @see #setValue(int,int)
197 */
198 public int getValue(final int holder) {
199 return getRawValue(holder) >> shiftCount;
200 }
201
202 /**
203 * Gets the value for the specified BitField, appropriately shifted right.
204 * <p>
205 * Many users of a BitField will want to treat the specified bits as an long value, and will not want to be aware that the value is stored as a BitField (and
206 * so shifted left so many bits).
207 * </p>
208 *
209 * @param holder the long data containing the bits we're interested in.
210 * @return the selected bits, shifted right appropriately.
211 * @see #setValue(long,long)
212 * @since 3.21.0
213 */
214 public long getValue(final long holder) {
215 return getRawValue(holder) >> shiftCount;
216 }
217
218 /**
219 * Tests whether all of the bits are set or not.
220 * <p>
221 * This is a stricter test than {@link #isSet(int)}, in that all of the bits in a multi-bit set must be set for this method to return {@code true}.
222 * </p>
223 *
224 * @param holder the int data containing the bits we're interested in.
225 * @return {@code true} if all of the bits are set, else {@code false}.
226 */
227 public boolean isAllSet(final int holder) {
228 return (holder & mask) == mask;
229 }
230
231 /**
232 * Tests whether all of the bits are set or not.
233 * <p>
234 * This is a stricter test than {@link #isSet(long)}, in that all of the bits in a multi-bit set must be set for this method to return {@code true}.
235 * </p>
236 *
237 * @param holder the long data containing the bits we're interested in.
238 * @return {@code true} if all of the bits are set, else {@code false}.
239 * @since 3.21.0
240 */
241 public boolean isAllSet(final long holder) {
242 return (holder & mask) == mask;
243 }
244
245 /**
246 * Tests whether the field is set or not.
247 * <p>
248 * This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to
249 * determine whether <em>any</em> of its bits are set.
250 * </p>
251 *
252 * @param holder the int data containing the bits we're interested in
253 * @return {@code true} if any of the bits are set, else {@code false}
254 */
255 public boolean isSet(final int holder) {
256 return (holder & mask) != 0;
257 }
258
259 /**
260 * Tests whether the field is set or not.
261 * <p>
262 * This is most commonly used for a single-bit field, which is often used to represent a boolean value; the results of using it for a multi-bit field is to
263 * determine whether <em>any</em> of its bits are set.
264 * </p>
265 *
266 * @param holder the long data containing the bits we're interested in
267 * @return {@code true} if any of the bits are set, else {@code false}
268 * @since 3.21.0
269 */
270 public boolean isSet(final long holder) {
271 return (holder & mask) != 0;
272 }
273
274 /**
275 * Sets the bits.
276 *
277 * @param holder the int data containing the bits we're interested in.
278 * @return the value of holder with the specified bits set to {@code 1}.
279 */
280 public int set(final int holder) {
281 return (int) (holder | mask);
282 }
283
284 /**
285 * Sets the bits.
286 *
287 * @param holder the long data containing the bits we're interested in.
288 * @return the value of holder with the specified bits set to {@code 1}.
289 * @since 3.21.0
290 */
291 public long set(final long holder) {
292 return holder | mask;
293 }
294
295 /**
296 * Sets a boolean BitField.
297 *
298 * @param holder the int data containing the bits we're interested in.
299 * @param flag indicating whether to set or clear the bits.
300 * @return the value of holder with the specified bits set or cleared.
301 */
302 public int setBoolean(final int holder, final boolean flag) {
303 return flag ? set(holder) : clear(holder);
304 }
305
306 /**
307 * Sets a boolean BitField.
308 *
309 * @param holder the long data containing the bits we're 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 cleared.
312 * @since 3.21.0
313 */
314 public long setBoolean(final long holder, final boolean flag) {
315 return flag ? set(holder) : clear(holder);
316 }
317
318 /**
319 * Sets the bits.
320 *
321 * @param holder the byte data containing the bits we're interested in
322 * @return the value of holder with the specified bits set to {@code 1}
323 */
324 public byte setByte(final byte holder) {
325 return (byte) set(holder);
326 }
327
328 /**
329 * Sets a boolean BitField.
330 *
331 * @param holder the byte data containing the bits we're interested in.
332 * @param flag indicating whether to set or clear the bits.
333 * @return the value of holder with the specified bits set or cleared.
334 */
335 public byte setByteBoolean(final byte holder, final boolean flag) {
336 return flag ? setByte(holder) : clearByte(holder);
337 }
338
339 /**
340 * Sets the bits.
341 *
342 * @param holder the short data containing the bits we're interested in.
343 * @return the value of holder with the specified bits set to {@code 1}.
344 */
345 public short setShort(final short holder) {
346 return (short) set(holder);
347 }
348
349 /**
350 * Sets a boolean BitField.
351 *
352 * @param holder the short data containing the bits we're interested in.
353 * @param flag indicating whether to set or clear the bits.
354 * @return the value of holder with the specified bits set or cleared.
355 */
356 public short setShortBoolean(final short holder, final boolean flag) {
357 return flag ? setShort(holder) : clearShort(holder);
358 }
359
360 /**
361 * Sets the bits with new values.
362 *
363 * @param holder the short data containing the bits we're interested in
364 * @param value the new value for the specified bits
365 * @return the value of holder with the bits from the value parameter replacing the old bits
366 * @see #getShortValue(short)
367 */
368 public short setShortValue(final short holder, final short value) {
369 return (short) setValue(holder, value);
370 }
371
372 /**
373 * Sets the bits with new values.
374 *
375 * @param holder the int data containing the bits we're interested in.
376 * @param value the new value for the specified bits.
377 * @return the value of holder with the bits from the value parameter replacing the old bits.
378 * @see #getValue(int)
379 */
380 public int setValue(final int holder, final int value) {
381 return (int) (holder & ~mask | value << shiftCount & mask);
382 }
383
384 /**
385 * Sets the bits with new values.
386 *
387 * @param holder the long data containing the bits we're interested in.
388 * @param value the new value for the specified bits.
389 * @return the value of holder with the bits from the value parameter replacing the old bits.
390 * @see #getValue(long)
391 * @since 3.21.0
392 */
393 public long setValue(final long holder, final long value) {
394 return holder & ~mask | value << shiftCount & mask;
395 }
396 }