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