BitField.java

  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;

  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 {

  75.     private final int mask;
  76.     private final int shiftCount;

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  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.     }

  322. }
Created with JaCoCo 0.8.12.202403310830