Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      https://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.lang3;
019
020/**
021 * 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}.
022 * <p>
023 * 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
024 * instance, the mask {@code 0xFF} indicates the least-significant byte should be used to store the data.
025 * </p>
026 * <p>
027 * As an example, consider a car painting machine that accepts paint instructions as integers. Bit fields can be used to encode this:
028 * </p>
029 *
030 * <pre>
031 *
032 * // blue, green and red are 1 byte values (0-255) stored in the three least
033 * // significant bytes
034 * BitField blue = new BitField(0xFF);
035 *
036 * BitField green = new BitField(0xFF00);
037 *
038 * BitField red = new BitField(0xFF0000);
039 *
040 * // anyColor is a flag triggered if any color is used
041 * BitField anyColor = new BitField(0xFFFFFF);
042 *
043 * // isMetallic is a single bit flag
044 * BitField isMetallic = new BitField(0x1000000);
045 * </pre>
046 * <p>
047 * Using these {@link BitField} instances, a paint instruction can be encoded into an integer:
048 * </p>
049 *
050 * <pre>
051 * int paintInstruction = 0;
052 * paintInstruction = red.setValue(paintInstruction, 35);
053 * paintInstruction = green.setValue(paintInstruction, 100);
054 * paintInstruction = blue.setValue(paintInstruction, 255);
055 * </pre>
056 * <p>
057 * Flags and data can be retrieved from the integer:
058 * </p>
059 *
060 * <pre>
061 * // Prints true if red, green or blue is non-zero
062 * System.out.println(anyColor.isSet(paintInstruction)); // prints true
063 * // Prints value of red, green and blue
064 * System.out.println(red.getValue(paintInstruction)); // prints 35
065 * System.out.println(green.getValue(paintInstruction)); // prints 100
066 * System.out.println(blue.getValue(paintInstruction)); // prints 255
067 * // Prints true if isMetallic was set
068 * System.out.println(isMetallic.isSet(paintInstruction)); // prints false
069 * </pre>
070 *
071 * @since 2.0
072 */
073public class BitField {
074
075    private final long mask;
076
077    private final int shiftCount;
078
079    /**
080     * Creates a BitField instance.
081     *
082     * @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.
083     */
084    public BitField(final int mask) {
085        this.mask = mask;
086        this.shiftCount = mask == 0 ? 0 : Integer.numberOfTrailingZeros(mask);
087    }
088
089    /**
090     * Creates a BitField instance.
091     *
092     * @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.
093     * @since 3.21.0
094     */
095    public BitField(final long mask) {
096        this.mask = mask;
097        this.shiftCount = mask == 0 ? 0 : Long.numberOfTrailingZeros(mask);
098    }
099
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}