KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > CharRange


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 import java.io.Serializable JavaDoc;
19
20 /**
21  * <p>A contiguous range of characters, optionally negated.</p>
22  *
23  * <p>Instances are immutable.</p>
24  *
25  * @author Henri Yandell
26  * @author Stephen Colebourne
27  * @author Chris Feldhacker
28  * @author Gary Gregory
29  * @since 1.0
30  * @version $Id: CharRange.java 161243 2005-04-14 04:30:28Z ggregory $
31  */
32 public final class CharRange implements Serializable JavaDoc {
33
34     /** Serialization lock, Lang version 2.0. */
35     private static final long serialVersionUID = 8270183163158333422L;
36     
37     /** The first character, inclusive, in the range. */
38     private final char start;
39     /** The last character, inclusive, in the range. */
40     private final char end;
41     /** True if the range is everything except the characters specified. */
42     private final boolean negated;
43     
44     /** Cached toString. */
45     private transient String JavaDoc iToString;
46
47     //-----------------------------------------------------------------------
48 /**
49      * <p>Constructs a <code>CharRange</code> over a single character.</p>
50      *
51      * @param ch only character in this range
52      */
53     public CharRange(char ch) {
54         this(ch, ch, false);
55     }
56
57     /**
58      * <p>Constructs a <code>CharRange</code> over a single character,
59      * optionally negating the range.</p>
60      *
61      * <p>A negated range includes everything except the specified char.</p>
62      *
63      * @param ch only character in this range
64      * @param negated true to express everything except the range
65      */
66     public CharRange(char ch, boolean negated) {
67         this(ch, ch, negated);
68     }
69
70     /**
71      * <p>Constructs a <code>CharRange</code> over a set of characters.</p>
72      *
73      * @param start first character, inclusive, in this range
74      * @param end last character, inclusive, in this range
75      */
76     public CharRange(char start, char end) {
77         this(start, end, false);
78     }
79
80     /**
81      * <p>Constructs a <code>CharRange</code> over a set of characters,
82      * optionally negating the range.</p>
83      *
84      * <p>A negated range includes everything except that defined by the
85      * start and end characters.</p>
86      *
87      * <p>If start and end are in the wrong order, they are reversed.
88      * Thus <code>a-e</code> is the same as <code>e-a</code>.</p>
89      *
90      * @param start first character, inclusive, in this range
91      * @param end last character, inclusive, in this range
92      * @param negated true to express everything except the range
93      */
94     public CharRange(char start, char end, boolean negated) {
95         super();
96         if (start > end) {
97             char temp = start;
98             start = end;
99             end = temp;
100         }
101         
102         this.start = start;
103         this.end = end;
104         this.negated = negated;
105     }
106
107     // Accessors
108 //-----------------------------------------------------------------------
109 /**
110      * <p>Gets the start character for this character range.</p>
111      *
112      * @return the start char (inclusive)
113      */
114     public char getStart() {
115         return this.start;
116     }
117
118     /**
119      * <p>Gets the end character for this character range.</p>
120      *
121      * @return the end char (inclusive)
122      */
123     public char getEnd() {
124         return this.end;
125     }
126
127     /**
128      * <p>Is this <code>CharRange</code> negated.</p>
129      *
130      * <p>A negated range includes everything except that defined by the
131      * start and end characters.</p>
132      *
133      * @return <code>true</code> is negated
134      */
135     public boolean isNegated() {
136         return negated;
137     }
138
139     // Contains
140 //-----------------------------------------------------------------------
141 /**
142      * <p>Is the character specified contained in this range.</p>
143      *
144      * @param ch the character to check
145      * @return <code>true</code> if this range contains the input character
146      */
147     public boolean contains(char ch) {
148         return (ch >= start && ch <= end) != negated;
149     }
150
151     /**
152      * <p>Are all the characters of the passed in range contained in
153      * this range.</p>
154      *
155      * @param range the range to check against
156      * @return <code>true</code> if this range entirely contains the input range
157      * @throws IllegalArgumentException if <code>null</code> input
158      */
159     public boolean contains(CharRange range) {
160         if (range == null) {
161             throw new IllegalArgumentException JavaDoc("The Range must not be null");
162         }
163         if (negated) {
164             if (range.negated) {
165                 return start >= range.start && end <= range.end;
166             } else {
167                 return range.end < start || range.start > end;
168             }
169         } else {
170             if (range.negated) {
171                 return start == 0 && end == Character.MAX_VALUE;
172             } else {
173                 return start <= range.start && end >= range.end;
174             }
175         }
176     }
177
178     // Basics
179 //-----------------------------------------------------------------------
180 /**
181      * <p>Compares two CharRange objects, returning true if they represent
182      * exactly the same range of characters defined in the same way.</p>
183      *
184      * @param obj the object to compare to
185      * @return true if equal
186      */
187     public boolean equals(Object JavaDoc obj) {
188         if (obj == this) {
189             return true;
190         }
191         if (obj instanceof CharRange == false) {
192             return false;
193         }
194         CharRange other = (CharRange) obj;
195         return start == other.start && end == other.end && negated == other.negated;
196     }
197
198     /**
199      * <p>Gets a hashCode compatible with the equals method.</p>
200      *
201      * @return a suitable hashCode
202      */
203     public int hashCode() {
204         return 83 + start + 7 * end + (negated ? 1 : 0);
205     }
206     
207     /**
208      * <p>Gets a string representation of the character range.</p>
209      *
210      * @return string representation of this range
211      */
212     public String JavaDoc toString() {
213         if (iToString == null) {
214             StringBuffer JavaDoc buf = new StringBuffer JavaDoc(4);
215             if (isNegated()) {
216                 buf.append('^');
217             }
218             buf.append(start);
219             if (start != end) {
220                 buf.append('-');
221                 buf.append(end);
222             }
223             iToString = buf.toString();
224         }
225         return iToString;
226     }
227     
228 }
229
Popular Tags