1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. 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 package org.apache.commons.lang3; 18 19 import java.io.Serializable; 20 import java.util.Collections; 21 import java.util.HashMap; 22 import java.util.HashSet; 23 import java.util.Map; 24 import java.util.Set; 25 import java.util.stream.Stream; 26 27 /** 28 * A set of characters. 29 * 30 * <p>Instances are immutable, but instances of subclasses may not be.</p> 31 * 32 * <p>#ThreadSafe#</p> 33 * @since 1.0 34 */ 35 public class CharSet implements Serializable { 36 37 /** 38 * Required for serialization support. Lang version 2.0. 39 * 40 * @see java.io.Serializable 41 */ 42 private static final long serialVersionUID = 5947847346149275958L; 43 44 /** 45 * A CharSet defining no characters. 46 * @since 2.0 47 */ 48 public static final CharSet EMPTY = new CharSet((String) null); 49 50 /** 51 * A CharSet defining ASCII alphabetic characters "a-zA-Z". 52 * @since 2.0 53 */ 54 public static final CharSet ASCII_ALPHA = new CharSet("a-zA-Z"); 55 56 /** 57 * A CharSet defining ASCII alphabetic characters "a-z". 58 * @since 2.0 59 */ 60 public static final CharSet ASCII_ALPHA_LOWER = new CharSet("a-z"); 61 62 /** 63 * A CharSet defining ASCII alphabetic characters "A-Z". 64 * @since 2.0 65 */ 66 public static final CharSet ASCII_ALPHA_UPPER = new CharSet("A-Z"); 67 68 /** 69 * A CharSet defining ASCII alphabetic characters "0-9". 70 * @since 2.0 71 */ 72 public static final CharSet ASCII_NUMERIC = new CharSet("0-9"); 73 74 /** 75 * A Map of the common cases used in the factory. 76 * Subclasses can add more common patterns if desired 77 * @since 2.0 78 */ 79 protected static final Map<String, CharSet> COMMON = Collections.synchronizedMap(new HashMap<>()); 80 81 static { 82 COMMON.put(null, EMPTY); 83 COMMON.put(StringUtils.EMPTY, EMPTY); 84 COMMON.put("a-zA-Z", ASCII_ALPHA); 85 COMMON.put("A-Za-z", ASCII_ALPHA); 86 COMMON.put("a-z", ASCII_ALPHA_LOWER); 87 COMMON.put("A-Z", ASCII_ALPHA_UPPER); 88 COMMON.put("0-9", ASCII_NUMERIC); 89 } 90 91 /** The set of CharRange objects. */ 92 private final Set<CharRange> set = Collections.synchronizedSet(new HashSet<>()); 93 94 /** 95 * Factory method to create a new CharSet using a special syntax. 96 * 97 * <ul> 98 * <li>{@code null} or empty string ("") 99 * - set containing no characters</li> 100 * <li>Single character, such as "a" 101 * - set containing just that character</li> 102 * <li>Multi character, such as "a-e" 103 * - set containing characters from one character to the other</li> 104 * <li>Negated, such as "^a" or "^a-e" 105 * - set containing all characters except those defined</li> 106 * <li>Combinations, such as "abe-g" 107 * - set containing all the characters from the individual sets</li> 108 * </ul> 109 * 110 * <p>The matching order is:</p> 111 * <ol> 112 * <li>Negated multi character range, such as "^a-e" 113 * <li>Ordinary multi character range, such as "a-e" 114 * <li>Negated single character, such as "^a" 115 * <li>Ordinary single character, such as "a" 116 * </ol> 117 * 118 * <p>Matching works left to right. Once a match is found the 119 * search starts again from the next character.</p> 120 * 121 * <p>If the same range is defined twice using the same syntax, only 122 * one range will be kept. 123 * Thus, "a-ca-c" creates only one range of "a-c".</p> 124 * 125 * <p>If the start and end of a range are in the wrong order, 126 * they are reversed. Thus "a-e" is the same as "e-a". 127 * As a result, "a-ee-a" would create only one range, 128 * as the "a-e" and "e-a" are the same.</p> 129 * 130 * <p>The set of characters represented is the union of the specified ranges.</p> 131 * 132 * <p>There are two ways to add a literal negation character ({@code ^}):</p> 133 * <ul> 134 * <li>As the last character in a string, e.g. {@code CharSet.getInstance("a-z^")}</li> 135 * <li>As a separate element, e.g. {@code CharSet.getInstance("^", "a-z")}</li> 136 * </ul> 137 * 138 * <p>Examples using the negation character:</p> 139 * <pre> 140 * CharSet.getInstance("^a-c").contains('a') = false 141 * CharSet.getInstance("^a-c").contains('d') = true 142 * CharSet.getInstance("^^a-c").contains('a') = true // (only '^' is negated) 143 * CharSet.getInstance("^^a-c").contains('^') = false 144 * CharSet.getInstance("^a-cd-f").contains('d') = true 145 * CharSet.getInstance("a-c^").contains('^') = true 146 * CharSet.getInstance("^", "a-c").contains('^') = true 147 * </pre> 148 * 149 * <p>All CharSet objects returned by this method will be immutable.</p> 150 * 151 * @param setStrs Strings to merge into the set, may be null 152 * @return a CharSet instance 153 * @since 2.4 154 */ 155 public static CharSet getInstance(final String... setStrs) { 156 if (setStrs == null) { 157 return null; 158 } 159 if (setStrs.length == 1) { 160 final CharSet common = COMMON.get(setStrs[0]); 161 if (common != null) { 162 return common; 163 } 164 } 165 return new CharSet(setStrs); 166 } 167 168 /** 169 * Constructs a new CharSet using the set syntax. 170 * Each string is merged in with the set. 171 * 172 * @param set Strings to merge into the initial set 173 * @throws NullPointerException if set is {@code null} 174 */ 175 protected CharSet(final String... set) { 176 Stream.of(set).forEach(this::add); 177 } 178 179 /** 180 * Add a set definition string to the {@link CharSet}. 181 * 182 * @param str set definition string 183 */ 184 protected void add(final String str) { 185 if (str == null) { 186 return; 187 } 188 189 final int len = str.length(); 190 int pos = 0; 191 while (pos < len) { 192 final int remainder = len - pos; 193 if (remainder >= 4 && str.charAt(pos) == '^' && str.charAt(pos + 2) == '-') { 194 // negated range 195 set.add(CharRange.isNotIn(str.charAt(pos + 1), str.charAt(pos + 3))); 196 pos += 4; 197 } else if (remainder >= 3 && str.charAt(pos + 1) == '-') { 198 // range 199 set.add(CharRange.isIn(str.charAt(pos), str.charAt(pos + 2))); 200 pos += 3; 201 } else if (remainder >= 2 && str.charAt(pos) == '^') { 202 // negated char 203 set.add(CharRange.isNot(str.charAt(pos + 1))); 204 pos += 2; 205 } else { 206 // char 207 set.add(CharRange.is(str.charAt(pos))); 208 pos += 1; 209 } 210 } 211 } 212 213 /** 214 * Gets the internal set as an array of CharRange objects. 215 * 216 * @return an array of immutable CharRange objects 217 * @since 2.0 218 */ 219 // NOTE: This is no longer public as CharRange is no longer a public class. 220 // It may be replaced when CharSet moves to Range. 221 /*public*/ CharRange[] getCharRanges() { 222 return set.toArray(CharRange.EMPTY_ARRAY); 223 } 224 225 /** 226 * Does the {@link CharSet} contain the specified 227 * character {@code ch}. 228 * 229 * @param ch the character to check for 230 * @return {@code true} if the set contains the characters 231 */ 232 public boolean contains(final char ch) { 233 synchronized (set) { 234 return set.stream().anyMatch(range -> range.contains(ch)); 235 } 236 } 237 238 // Basics 239 /** 240 * Compares two {@link CharSet} objects, returning true if they represent 241 * exactly the same set of characters defined in the same way. 242 * 243 * <p>The two sets {@code abc} and {@code a-c} are <i>not</i> 244 * equal according to this method.</p> 245 * 246 * @param obj the object to compare to 247 * @return true if equal 248 * @since 2.0 249 */ 250 @Override 251 public boolean equals(final Object obj) { 252 if (obj == this) { 253 return true; 254 } 255 if (!(obj instanceof CharSet)) { 256 return false; 257 } 258 final CharSet other = (CharSet) obj; 259 return set.equals(other.set); 260 } 261 262 /** 263 * Gets a hash code compatible with the equals method. 264 * 265 * @return a suitable hash code 266 * @since 2.0 267 */ 268 @Override 269 public int hashCode() { 270 return 89 + set.hashCode(); 271 } 272 273 /** 274 * Gets a string representation of the set. 275 * 276 * @return string representation of the set 277 */ 278 @Override 279 public String toString() { 280 return set.toString(); 281 } 282 283 }