BitField


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.lang;
17  
18  /**
19   * <p>Operations on bit-mapped fields.</p>
20   *
21   * @author Apache Jakarta POI
22   * @author Scott Sanders (sanders at apache dot org)
23   * @author Marc Johnson (mjohnson at apache dot org)
24   * @author Andrew C. Oliver (acoliver at apache dot org)
25   * @author Stephen Colebourne
26   * @author Pete Gieser
27   * @author Gary Gregory
28   * @since 2.0
29   * @version $Id: BitField.java 161243 2005-04-14 04:30:28Z ggregory $
30   */
31  public class BitField {
32      
33      private final int _mask;
34      private final int _shift_count;
35  
36      /**
37       * <p>Creates a BitField instance.</p>
38       *
39       * @param mask the mask specifying which bits apply to this
40       *  BitField. Bits that are set in this mask are the bits
41       *  that this BitField operates on
42       */
43      public BitField(int mask) {
44          _mask = mask;
45          int count = 0;
46          int bit_pattern = mask;
47  
48          if (bit_pattern != 0) {
49              while ((bit_pattern & 1) == 0) {
50                  count++;
51                  bit_pattern >>= 1;
52              }
53          }
54          _shift_count = count;
55      }
56  
57      /**
58       * <p>Obtains the value for the specified BitField, appropriately
59       * shifted right.</p>
60       *
61       * <p>Many users of a BitField will want to treat the specified
62       * bits as an int value, and will not want to be aware that the
63       * value is stored as a BitField (and so shifted left so many
64       * bits).</p>
65       *
66       * @see #setValue(int,int)
67       * @param holder the int data containing the bits we're interested
68       *  in
69       * @return the selected bits, shifted right appropriately
70       */
71      public int getValue(int holder) {
72          return getRawValue(holder) >> _shift_count;
73      }
74  
75      /**
76       * <p>Obtains the value for the specified BitField, appropriately
77       * shifted right, as a short.</p>
78       *
79       * <p>Many users of a BitField will want to treat the specified
80       * bits as an int value, and will not want to be aware that the
81       * value is stored as a BitField (and so shifted left so many
82       * bits).</p>
83       *
84       * @see #setShortValue(short,short)
85       * @param holder the short data containing the bits we're
86       *  interested in
87       * @return the selected bits, shifted right appropriately
88       */
89      public short getShortValue(short holder) {
90          return (short) getValue(holder);
91      }
92  
93      /**
94       * <p>Obtains the value for the specified BitField, unshifted.</p>
95       *
96       * @param holder the int data containing the bits we're
97       *  interested in
98       * @return the selected bits
99       */
100     public int getRawValue(int holder) {
101         return holder & _mask;
102     }
103 
104     /**
105      * <p>Obtains the value for the specified BitField, unshifted.</p>
106      *
107      * @param holder the short data containing the bits we're
108      *  interested in
109      * @return the selected bits
110      */
111     public short getShortRawValue(short holder) {
112         return (short) getRawValue(holder);
113     }
114 
115     /**
116      * <p>Returns whether the field is set or not.</p>
117      *
118      * <p>This is most commonly used for a single-bit field, which is
119      * often used to represent a boolean value; the results of using
120      * it for a multi-bit field is to determine whether *any* of its
121      * bits are set.</p>
122      *
123      * @param holder the int data containing the bits we're interested
124      *  in
125      * @return <code>true</code> if any of the bits are set,
126      *  else <code>false</code>
127      */
128     public boolean isSet(int holder) {
129         return (holder & _mask) != 0;
130     }
131 
132     /**
133      * <p>Returns whether all of the bits are set or not.</p>
134      *
135      * <p>This is a stricter test than {@link #isSet(int)},
136      * in that all of the bits in a multi-bit set must be set
137      * for this method to return <code>true</code>.</p>
138      *
139      * @param holder the int data containing the bits we're
140      *  interested in
141      * @return <code>true</code> if all of the bits are set,
142      *  else <code>false</code>
143      */
144     public boolean isAllSet(int holder) {
145         return (holder & _mask) == _mask;
146     }
147 
148     /**
149      * <p>Replaces the bits with new values.</p>
150      *
151      * @see #getValue(int)
152      * @param holder the int data containing the bits we're
153      *  interested in
154      * @param value the new value for the specified bits
155      * @return the value of holder with the bits from the value
156      *  parameter replacing the old bits
157      */
158     public int setValue(int holder, int value) {
159         return (holder & ~_mask) | ((value << _shift_count) & _mask);
160     }
161 
162     /**
163      * <p>Replaces the bits with new values.</p>
164      *
165      * @see #getShortValue(short)
166      * @param holder the short data containing the bits we're
167      *  interested in
168      * @param value the new value for the specified bits
169      * @return the value of holder with the bits from the value
170      *  parameter replacing the old bits
171      */
172     public short setShortValue(short holder, short value) {
173         return (short) setValue(holder, value);
174     }
175 
176     /**
177      * <p>Clears the bits.</p>
178      *
179      * @param holder the int data containing the bits we're
180      *  interested in
181      * @return the value of holder with the specified bits cleared
182      *  (set to <code>0</code>)
183      */
184     public int clear(int holder) {
185         return holder & ~_mask;
186     }
187 
188     /**
189      * <p>Clears the bits.</p>
190      *
191      * @param holder the short data containing the bits we're
192      *  interested in
193      * @return the value of holder with the specified bits cleared
194      *  (set to <code>0</code>)
195      */
196     public short clearShort(short holder) {
197         return (short) clear(holder);
198     }
199 
200     /**
201      * <p>Clears the bits.</p>
202      *
203      * @param holder the byte data containing the bits we're
204      *  interested in
205      *
206      * @return the value of holder with the specified bits cleared
207      *  (set to <code>0</code>)
208      */
209     public byte clearByte(byte holder) {
210         return (byte) clear(holder);
211     }
212 
213     /**
214      * <p>Sets the bits.</p>
215      *
216      * @param holder the int data containing the bits we're
217      *  interested in
218      * @return the value of holder with the specified bits set
219      *  to <code>1</code>
220      */
221     public int set(int holder) {
222         return holder | _mask;
223     }
224 
225     /**
226      * <p>Sets the bits.</p>
227      *
228      * @param holder the short data containing the bits we're
229      *  interested in
230      * @return the value of holder with the specified bits set
231      *  to <code>1</code>
232      */
233     public short setShort(short holder) {
234         return (short) set(holder);
235     }
236 
237     /**
238      * <p>Sets the bits.</p>
239      *
240      * @param holder the byte data containing the bits we're
241      *  interested in
242      *
243      * @return the value of holder with the specified bits set
244      *  to <code>1</code>
245      */
246     public byte setByte(byte holder) {
247         return (byte) set(holder);
248     }
249 
250     /**
251      * <p>Sets a boolean BitField.</p>
252      *
253      * @param holder the int data containing the bits we're
254      *  interested in
255      * @param flag indicating whether to set or clear the bits
256      * @return the value of holder with the specified bits set or
257      *         cleared
258      */
259     public int setBoolean(int holder, boolean flag) {
260         return flag ? set(holder) : clear(holder);
261     }
262 
263     /**
264      * <p>Sets a boolean BitField.</p>
265      *
266      * @param holder the short data containing the bits we're
267      *  interested in
268      * @param flag indicating whether to set or clear the bits
269      * @return the value of holder with the specified bits set or
270      *  cleared
271      */
272     public short setShortBoolean(short holder, boolean flag) {
273         return flag ? setShort(holder) : clearShort(holder);
274     }
275 
276     /**
277      * <p>Sets a boolean BitField.</p>
278      *
279      * @param holder the byte data containing the bits we're
280      *  interested in
281      * @param flag indicating whether to set or clear the bits
282      * @return the value of holder with the specified bits set or
283      *  cleared
284      */
285     public byte setByteBoolean(byte holder, boolean flag) {
286         return flag ? setByte(holder) : clearByte(holder);
287     }
288 
289 }
290
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags