KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > 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
Popular Tags