BitField


1   
2   /* ====================================================================
3      Copyright 2002-2004   Apache Software Foundation
4   
5      Licensed under the Apache License, Version 2.0 (the "License");
6      you may not use this file except in compliance with the License.
7      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          
18  
19  package org.apache.poi.util;
20  
21  /**
22   * Manage operations dealing with bit-mapped fields.
23   *
24   * @author Marc Johnson (mjohnson at apache dot org)
25   * @author Andrew C. Oliver (acoliver at apache dot org)
26   */
27  
28  public class BitField
29  {
30      private final int _mask;
31      private final int _shift_count;
32  
33      /**
34       * Create a BitField instance
35       *
36       * @param mask the mask specifying which bits apply to this
37       *             BitField. Bits that are set in this mask are the
38       *             bits that this BitField operates on
39       */
40  
41      public BitField(final int mask)
42      {
43          _mask = mask;
44          int count       = 0;
45          int bit_pattern = mask;
46  
47          if (bit_pattern != 0)
48          {
49              while ((bit_pattern & 1) == 0)
50              {
51                  count++;
52                  bit_pattern >>= 1;
53              }
54          }
55          _shift_count = count;
56      }
57  
58      /**
59       * Obtain the value for the specified BitField, appropriately
60       * shifted right. Many users of a BitField will want to treat the
61       * specified bits as an int value, and will not want to be aware
62       * that the value is stored as a BitField (and so shifted left so
63       * many bits)
64       *
65       * @param holder the int data containing the bits we're interested
66       *               in
67       *
68       * @return the selected bits, shifted right appropriately
69       */
70  
71      public int getValue(final int holder)
72      {
73          return getRawValue(holder) >> _shift_count;
74      }
75  
76      /**
77       * Obtain the value for the specified BitField, appropriately
78       * shifted right, as a short. Many users of a BitField will want
79       * to treat the specified bits as an int value, and will not want
80       * to be aware that the value is stored as a BitField (and so
81       * shifted left so many bits)
82       *
83       * @param holder the short data containing the bits we're
84       *               interested in
85       *
86       * @return the selected bits, shifted right appropriately
87       */
88  
89      public short getShortValue(final short holder)
90      {
91          return ( short ) getValue(holder);
92      }
93  
94      /**
95       * Obtain the value for the specified BitField, unshifted
96       *
97       * @param holder the int data containing the bits we're interested
98       *               in
99       *
100      * @return the selected bits
101      */
102 
103     public int getRawValue(final int holder)
104     {
105         return (holder & _mask);
106     }
107 
108     /**
109      * Obtain the value for the specified BitField, unshifted
110      *
111      * @param holder the short data containing the bits we're
112      *               interested in
113      *
114      * @return the selected bits
115      */
116 
117     public short getShortRawValue(final short holder)
118     {
119         return ( short ) getRawValue(holder);
120     }
121 
122     /**
123      * Is the field set or not? This is most commonly used for a
124      * single-bit field, which is often used to represent a boolean
125      * value; the results of using it for a multi-bit field is to
126      * determine whether *any* of its bits are set
127      *
128      * @param holder the int data containing the bits we're interested
129      *               in
130      *
131      * @return true if any of the bits are set, else false
132      */
133 
134     public boolean isSet(final int holder)
135     {
136         return (holder & _mask) != 0;
137     }
138 
139     /**
140      * Are all of the bits set or not? This is a stricter test than
141      * isSet, in that all of the bits in a multi-bit set must be set
142      * for this method to return true
143      *
144      * @param holder the int data containing the bits we're interested
145      *               in
146      *
147      * @return true if all of the bits are set, else false
148      */
149 
150     public boolean isAllSet(final int holder)
151     {
152         return (holder & _mask) == _mask;
153     }
154 
155     /**
156      * Replace the bits with new values.
157      *
158      * @param holder the int data containint the bits we're interested
159      *               in
160      * @param value the new value for the specified bits
161      *
162      * @return the value of holder with the bits from the value
163      *         parameter replacing the old bits
164      */
165 
166     public int setValue(final int holder, final int value)
167     {
168         return (holder & ~_mask) | ((value << _shift_count) & _mask);
169     }
170 
171     /**
172      * Replace the bits with new values.
173      *
174      * @param holder the short data containing the bits we're
175      *               interested in
176      * @param value the new value for the specified bits
177      *
178      * @return the value of holder with the bits from the value
179      *         parameter replacing the old bits
180      */
181 
182     public short setShortValue(final short holder, final short value)
183     {
184         return ( short ) setValue(holder, value);
185     }
186 
187     /**
188      * Clear the bits.
189      *
190      * @param holder the int data containing the bits we're interested
191      *               in
192      *
193      * @return the value of holder with the specified bits cleared
194      *         (set to 0)
195      */
196 
197     public int clear(final int holder)
198     {
199         return holder & ~_mask;
200     }
201 
202     /**
203      * Clear the bits.
204      *
205      * @param holder the short data containing the bits we're
206      *               interested in
207      *
208      * @return the value of holder with the specified bits cleared
209      *         (set to 0)
210      */
211 
212     public short clearShort(final short holder)
213     {
214         return ( short ) clear(holder);
215     }
216 
217     /**
218      * Clear the bits.
219      *
220      * @param holder the byte data containing the bits we're
221      *               interested in
222      *
223      * @return the value of holder with the specified bits cleared
224      *         (set to 0)
225      */
226 
227     public byte clearByte(final byte holder)
228     {
229         return ( byte ) clear(holder);
230     }
231 
232     /**
233      * Set the bits.
234      *
235      * @param holder the int data containing the bits we're interested
236      *               in
237      *
238      * @return the value of holder with the specified bits set to 1
239      */
240 
241     public int set(final int holder)
242     {
243         return holder | _mask;
244     }
245 
246     /**
247      * Set the bits.
248      *
249      * @param holder the short data containing the bits we're
250      *               interested in
251      *
252      * @return the value of holder with the specified bits set to 1
253      */
254 
255     public short setShort(final short holder)
256     {
257         return ( short ) set(holder);
258     }
259 
260     /**
261      * Set the bits.
262      *
263      * @param holder the byte data containing the bits we're
264      *               interested in
265      *
266      * @return the value of holder with the specified bits set to 1
267      */
268 
269     public byte setByte(final byte holder)
270     {
271         return ( byte ) set(holder);
272     }
273 
274     /**
275      * Set a boolean BitField
276      *
277      * @param holder the int data containing the bits we're interested
278      *               in
279      * @param flag indicating whether to set or clear the bits
280      *
281      * @return the value of holder with the specified bits set or
282      *         cleared
283      */
284 
285     public int setBoolean(final int holder, final boolean flag)
286     {
287         return flag ? set(holder)
288                     : clear(holder);
289     }
290 
291     /**
292      * Set a boolean BitField
293      *
294      * @param holder the short data containing the bits we're
295      *               interested in
296      * @param flag indicating whether to set or clear the bits
297      *
298      * @return the value of holder with the specified bits set or
299      *         cleared
300      */
301 
302     public short setShortBoolean(final short holder, final boolean flag)
303     {
304         return flag ? setShort(holder)
305                     : clearShort(holder);
306     }
307 
308     /**
309      * Set a boolean BitField
310      *
311      * @param holder the byte data containing the bits we're
312      *               interested in
313      * @param flag indicating whether to set or clear the bits
314      *
315      * @return the value of holder with the specified bits set or
316      *         cleared
317      */
318 
319     public byte setByteBoolean(final byte holder, final boolean flag)
320     {
321         return flag ? setByte(holder)
322                     : clearByte(holder);
323     }
324 }   // end public class BitField
325 
326
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags