001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.commons.lang;
018:
019: import java.io.Serializable;
020:
021: /**
022: * <p>A contiguous range of characters, optionally negated.</p>
023: *
024: * <p>Instances are immutable.</p>
025: *
026: * @author Stephen Colebourne
027: * @author Chris Feldhacker
028: * @author Gary Gregory
029: * @since 1.0
030: * @version $Id: CharRange.java 471626 2006-11-06 04:02:09Z bayard $
031: */
032: public final class CharRange implements Serializable {
033:
034: /**
035: * Required for serialization support. Lang version 2.0.
036: *
037: * @see java.io.Serializable
038: */
039: private static final long serialVersionUID = 8270183163158333422L;
040:
041: /** The first character, inclusive, in the range. */
042: private final char start;
043: /** The last character, inclusive, in the range. */
044: private final char end;
045: /** True if the range is everything except the characters specified. */
046: private final boolean negated;
047:
048: /** Cached toString. */
049: private transient String iToString;
050:
051: //-----------------------------------------------------------------------
052: /**
053: * <p>Constructs a <code>CharRange</code> over a single character.</p>
054: *
055: * @param ch only character in this range
056: */
057: public CharRange(char ch) {
058: this (ch, ch, false);
059: }
060:
061: /**
062: * <p>Constructs a <code>CharRange</code> over a single character,
063: * optionally negating the range.</p>
064: *
065: * <p>A negated range includes everything except the specified char.</p>
066: *
067: * @param ch only character in this range
068: * @param negated true to express everything except the range
069: */
070: public CharRange(char ch, boolean negated) {
071: this (ch, ch, negated);
072: }
073:
074: /**
075: * <p>Constructs a <code>CharRange</code> over a set of characters.</p>
076: *
077: * @param start first character, inclusive, in this range
078: * @param end last character, inclusive, in this range
079: */
080: public CharRange(char start, char end) {
081: this (start, end, false);
082: }
083:
084: /**
085: * <p>Constructs a <code>CharRange</code> over a set of characters,
086: * optionally negating the range.</p>
087: *
088: * <p>A negated range includes everything except that defined by the
089: * start and end characters.</p>
090: *
091: * <p>If start and end are in the wrong order, they are reversed.
092: * Thus <code>a-e</code> is the same as <code>e-a</code>.</p>
093: *
094: * @param start first character, inclusive, in this range
095: * @param end last character, inclusive, in this range
096: * @param negated true to express everything except the range
097: */
098: public CharRange(char start, char end, boolean negated) {
099: super ();
100: if (start > end) {
101: char temp = start;
102: start = end;
103: end = temp;
104: }
105:
106: this .start = start;
107: this .end = end;
108: this .negated = negated;
109: }
110:
111: // Accessors
112: //-----------------------------------------------------------------------
113: /**
114: * <p>Gets the start character for this character range.</p>
115: *
116: * @return the start char (inclusive)
117: */
118: public char getStart() {
119: return this .start;
120: }
121:
122: /**
123: * <p>Gets the end character for this character range.</p>
124: *
125: * @return the end char (inclusive)
126: */
127: public char getEnd() {
128: return this .end;
129: }
130:
131: /**
132: * <p>Is this <code>CharRange</code> negated.</p>
133: *
134: * <p>A negated range includes everything except that defined by the
135: * start and end characters.</p>
136: *
137: * @return <code>true</code> is negated
138: */
139: public boolean isNegated() {
140: return negated;
141: }
142:
143: // Contains
144: //-----------------------------------------------------------------------
145: /**
146: * <p>Is the character specified contained in this range.</p>
147: *
148: * @param ch the character to check
149: * @return <code>true</code> if this range contains the input character
150: */
151: public boolean contains(char ch) {
152: return (ch >= start && ch <= end) != negated;
153: }
154:
155: /**
156: * <p>Are all the characters of the passed in range contained in
157: * this range.</p>
158: *
159: * @param range the range to check against
160: * @return <code>true</code> if this range entirely contains the input range
161: * @throws IllegalArgumentException if <code>null</code> input
162: */
163: public boolean contains(CharRange range) {
164: if (range == null) {
165: throw new IllegalArgumentException(
166: "The Range must not be null");
167: }
168: if (negated) {
169: if (range.negated) {
170: return start >= range.start && end <= range.end;
171: } else {
172: return range.end < start || range.start > end;
173: }
174: } else {
175: if (range.negated) {
176: return start == 0 && end == Character.MAX_VALUE;
177: } else {
178: return start <= range.start && end >= range.end;
179: }
180: }
181: }
182:
183: // Basics
184: //-----------------------------------------------------------------------
185: /**
186: * <p>Compares two CharRange objects, returning true if they represent
187: * exactly the same range of characters defined in the same way.</p>
188: *
189: * @param obj the object to compare to
190: * @return true if equal
191: */
192: public boolean equals(Object obj) {
193: if (obj == this ) {
194: return true;
195: }
196: if (obj instanceof CharRange == false) {
197: return false;
198: }
199: CharRange other = (CharRange) obj;
200: return start == other.start && end == other.end
201: && negated == other.negated;
202: }
203:
204: /**
205: * <p>Gets a hashCode compatible with the equals method.</p>
206: *
207: * @return a suitable hashCode
208: */
209: public int hashCode() {
210: return 83 + start + 7 * end + (negated ? 1 : 0);
211: }
212:
213: /**
214: * <p>Gets a string representation of the character range.</p>
215: *
216: * @return string representation of this range
217: */
218: public String toString() {
219: if (iToString == null) {
220: StringBuffer buf = new StringBuffer(4);
221: if (isNegated()) {
222: buf.append('^');
223: }
224: buf.append(start);
225: if (start != end) {
226: buf.append('-');
227: buf.append(end);
228: }
229: iToString = buf.toString();
230: }
231: return iToString;
232: }
233:
234: }
|