CharSetUtils


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 <code>CharSet</code>s.</p>
20   *
21   * <p>This class handles <code>null</code> input gracefully.
22   * An exception will not be thrown for a <code>null</code> input.
23   * Each method documents its behaviour in more detail.</p>
24   * 
25   * @see CharSet
26   * @author <a HREF="bayard@generationjava.com">Henri Yandell</a>
27   * @author Stephen Colebourne
28   * @author Phil Steitz
29   * @author Gary Gregory
30   * @since 1.0
31   * @version $Id: CharSetUtils.java 161243 2005-04-14 04:30:28Z ggregory $
32   */
33  public class CharSetUtils {
34  
35      /**
36       * <p>CharSetUtils instances should NOT be constructed in standard programming.
37       * Instead, the class should be used as <code>CharSetUtils.evaluateSet(null);</code>.</p>
38       *
39       * <p>This constructor is public to permit tools that require a JavaBean instance
40       * to operate.</p>
41       */
42      public CharSetUtils() {
43      }
44  
45      // Factory
46      //-----------------------------------------------------------------------
47      /**
48       * <p>Creates a <code>CharSet</code> instance which allows a certain amount of
49       * set logic to be performed.</p>
50       * <p>The syntax is:</p>
51       * <ul>
52       *  <li>&quot;aeio&quot; which implies 'a','e',..</li>
53       *  <li>&quot;^e&quot; implies not e.</li>
54       *  <li>&quot;ej-m&quot; implies e,j-&gt;m. e,j,k,l,m.</li>
55       * </ul>
56       * 
57       * <pre>
58       * CharSetUtils.evaluateSet(null)    = null
59       * CharSetUtils.evaluateSet([])      = CharSet matching nothing
60       * CharSetUtils.evaluateSet(["a-e"]) = CharSet matching a,b,c,d,e
61       * </pre>
62       *
63       * @param set  the set, may be null
64       * @return a CharSet instance, <code>null</code> if null input
65       * @deprecated Use {@link CharSet#getInstance(String)}.
66       *             Method will be removed in Commons Lang 3.0.
67       */
68      public static CharSet evaluateSet(String  [] set) {
69          if (set == null) {
70              return null;
71          }
72          return new CharSet(set); 
73      }
74  
75      // Squeeze
76      //-----------------------------------------------------------------------
77      /**
78       * <p>Squeezes any repetitions of a character that is mentioned in the
79       * supplied set.</p>
80       *
81       * <pre>
82       * CharSetUtils.squeeze(null, *)        = null
83       * CharSetUtils.squeeze("", *)          = ""
84       * CharSetUtils.squeeze(*, null)        = *
85       * CharSetUtils.squeeze(*, "")          = *
86       * CharSetUtils.squeeze("hello", "k-p") = "helo"
87       * CharSetUtils.squeeze("hello", "a-e") = "hello"
88       * </pre>
89       *
90       * @see #evaluateSet(java.lang.String[]) for set-syntax.
91       * @param str  the string to squeeze, may be null
92       * @param set  the character set to use for manipulation, may be null
93       * @return modified String, <code>null</code> if null string input
94       */
95      public static String   squeeze(String   str, String   set) {
96          if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
97              return str;
98          }
99          String  [] strs = new String  [1];
100         strs[0] = set;
101         return squeeze(str, strs);
102     }
103 
104     /**
105      * <p>Squeezes any repetitions of a character that is mentioned in the
106      * supplied set.</p>
107      *
108      * <p>An example is:</p>
109      * <ul>
110      *   <li>squeeze(&quot;hello&quot;, {&quot;el&quot;}) => &quot;helo&quot;</li>
111      * </ul>
112      * 
113      * @see #evaluateSet(java.lang.String[]) for set-syntax.
114      * @param str  the string to squeeze, may be null
115      * @param set  the character set to use for manipulation, may be null
116      * @return modified String, <code>null</code> if null string input
117      */
118     public static String   squeeze(String   str, String  [] set) {
119         if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(set)) {
120             return str;
121         }
122         CharSet chars = evaluateSet(set);
123         StringBuffer   buffer = new StringBuffer  (str.length());
124         char[] chrs = str.toCharArray();
125         int sz = chrs.length;
126         char lastChar = ' ';
127         char ch = ' ';
128         for (int i = 0; i < sz; i++) {
129             ch = chrs[i];
130             if (chars.contains(ch)) {
131                 if ((ch == lastChar) && (i != 0)) {
132                     continue;
133                 }
134             }
135             buffer.append(ch);
136             lastChar = ch;
137         }
138         return buffer.toString();
139     }
140 
141     // Count
142     //-----------------------------------------------------------------------
143     /**
144      * <p>Takes an argument in set-syntax, see evaluateSet,
145      * and returns the number of characters present in the specified string.</p>
146      *
147      * <pre>
148      * CharSetUtils.count(null, *)        = 0
149      * CharSetUtils.count("", *)          = 0
150      * CharSetUtils.count(*, null)        = 0
151      * CharSetUtils.count(*, "")          = 0
152      * CharSetUtils.count("hello", "k-p") = 3
153      * CharSetUtils.count("hello", "a-e") = 1
154      * </pre>
155      *
156      * @see #evaluateSet(java.lang.String[]) for set-syntax.
157      * @param str  String to count characters in, may be null
158      * @param set  String set of characters to count, may be null
159      * @return character count, zero if null string input
160      */
161     public static int count(String   str, String   set) {
162         if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
163             return 0;
164         }
165         String  [] strs = new String  [1];
166         strs[0] = set;
167         return count(str, strs);
168     }
169     
170     /**
171      * <p>Takes an argument in set-syntax, see evaluateSet,
172      * and returns the number of characters present in the specified string.</p>
173      *
174      * <p>An example would be:</p>
175      * <ul>
176      *  <li>count(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;}) returns 2.</li>
177      * </ul>
178      *
179      * @see #evaluateSet(java.lang.String[]) for set-syntax.
180      * @param str  String to count characters in, may be null
181      * @param set  String[] set of characters to count, may be null
182      * @return character count, zero if null string input
183      */
184     public static int count(String   str, String  [] set) {
185         if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(set)) {
186             return 0;
187         }
188         CharSet chars = evaluateSet(set);
189         int count = 0;
190         char[] chrs = str.toCharArray();
191         int sz = chrs.length;
192         for(int i=0; i<sz; i++) {
193             if(chars.contains(chrs[i])) {
194                 count++;
195             }
196         }
197         return count;
198     }
199 
200     // Keep
201     //-----------------------------------------------------------------------
202     /**
203      * <p>Takes an argument in set-syntax, see evaluateSet,
204      * and keeps any of characters present in the specified string.</p>
205      *
206      * <pre>
207      * CharSetUtils.keep(null, *)        = null
208      * CharSetUtils.keep("", *)          = ""
209      * CharSetUtils.keep(*, null)        = ""
210      * CharSetUtils.keep(*, "")          = ""
211      * CharSetUtils.keep("hello", "hl")  = "hll"
212      * CharSetUtils.keep("hello", "le")  = "ell"
213      * </pre>
214      *
215      * @see #evaluateSet(java.lang.String[]) for set-syntax.
216      * @param str  String to keep characters from, may be null
217      * @param set  String set of characters to keep, may be null
218      * @return modified String, <code>null</code> if null string input
219      * @since 2.0
220      */
221     public static String   keep(String   str, String   set) {
222         if (str == null) {
223             return null;
224         }
225         if (str.length() == 0 || StringUtils.isEmpty(set)) {
226             return "";
227         }
228         String  [] strs = new String  [1];
229         strs[0] = set;
230         return keep(str, strs);
231     }
232     
233     /**
234      * <p>Takes an argument in set-syntax, see evaluateSet,
235      * and keeps any of characters present in the specified string.</p>
236      *
237      * <p>An example would be:</p>
238      * <ul>
239      *  <li>keep(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;})
240      *   returns &quot;eo&quot;</li>
241      * </ul>
242      *
243      * @see #evaluateSet(java.lang.String[]) for set-syntax.
244      * @param str  String to keep characters from, may be null
245      * @param set  String[] set of characters to keep, may be null
246      * @return modified String, <code>null</code> if null string input
247      * @since 2.0
248      */
249     public static String   keep(String   str, String  [] set) {
250         if (str == null) {
251             return null;
252         }
253         if (str.length() == 0 || ArrayUtils.isEmpty(set)) {
254             return "";
255         }
256         return modify(str, set, true);
257     }
258 
259     // Delete
260     //-----------------------------------------------------------------------
261     /**
262      * <p>Takes an argument in set-syntax, see evaluateSet,
263      * and deletes any of characters present in the specified string.</p>
264      *
265      * <pre>
266      * CharSetUtils.delete(null, *)        = null
267      * CharSetUtils.delete("", *)          = ""
268      * CharSetUtils.delete(*, null)        = *
269      * CharSetUtils.delete(*, "")          = *
270      * CharSetUtils.delete("hello", "hl")  = "eo"
271      * CharSetUtils.delete("hello", "le")  = "ho"
272      * </pre>
273      *
274      * @see #evaluateSet(java.lang.String[]) for set-syntax.
275      * @param str  String to delete characters from, may be null
276      * @param set  String set of characters to delete, may be null
277      * @return modified String, <code>null</code> if null string input
278      */
279     public static String   delete(String   str, String   set) {
280         if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
281             return str;
282         }
283         String  [] strs = new String  [1];
284         strs[0] = set;
285         return delete(str, strs);
286     }
287     
288     /**
289      * <p>Takes an argument in set-syntax, see evaluateSet,
290      * and deletes any of characters present in the specified string.</p>
291      *
292      * <p>An example would be:</p>
293      * <ul>
294      *  <li>delete(&quot;hello&quot;, {&quot;c-f&quot;, &quot;o&quot;}) returns
295      *   &quot;hll&quot;</li>
296      * </ul>
297      *
298      * @see #evaluateSet(java.lang.String[]) for set-syntax.
299      * @param str  String to delete characters from, may be null
300      * @param set  String[] set of characters to delete, may be null
301      * @return modified String, <code>null</code> if null string input
302      */
303     public static String   delete(String   str, String  [] set) {
304         if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(set)) {
305             return str;
306         }
307         return modify(str, set, false);
308     }
309 
310     //-----------------------------------------------------------------------
311     /**
312      * Implementation of delete and keep
313      *
314      * @param str String to modify characters within
315      * @param set String[] set of characters to modify
316      * @param expect whether to evaluate on match, or non-match
317      * @return modified String
318      */
319     private static String   modify(String   str, String  [] set, boolean expect) {
320         CharSet chars = evaluateSet(set);
321         StringBuffer   buffer = new StringBuffer  (str.length());
322         char[] chrs = str.toCharArray();
323         int sz = chrs.length;
324         for(int i=0; i<sz; i++) {
325             if(chars.contains(chrs[i]) == expect) {
326                 buffer.append(chrs[i]);
327             }
328         }
329         return buffer.toString();
330     }
331 
332     // Translate
333     //-----------------------------------------------------------------------
334     /**
335      * <p>Translate characters in a String.
336      * This is a multi character search and replace routine.</p>
337      *
338      * <p>An example is:</p>
339      * <ul>
340      *   <li>translate(&quot;hello&quot;, &quot;ho&quot;, &quot;jy&quot;)
341      *    =&gt; jelly</li>
342      * </ul>
343      *
344      * <p>If the length of characters to search for is greater than the
345      * length of characters to replace, then the last character is 
346      * used.</p>
347      * 
348      * <pre>
349      * CharSetUtils.translate(null, *, *) = null
350      * CharSetUtils.translate("", *, *)   = ""
351      * </pre>
352      *
353      * @param str  String to replace characters in, may be null
354      * @param searchChars   a set of characters to search for, must not be null
355      * @param replaceChars  a set of characters to replace, must not be null or empty (&quot;&quot;)
356      * @return translated String, <code>null</code> if null string input
357      * @throws NullPointerException if <code>searchChars</code> or <code>replaceChars</code> 
358      *  is <code>null</code>
359      * @throws ArrayIndexOutOfBoundsException if <code>replaceChars</code> is empty (&quot;&quot;)
360      * @deprecated Use {@link StringUtils#replaceChars(String, String, String)}.
361      *             Method will be removed in Commons Lang 3.0.
362      *  NOTE: StringUtils#replaceChars behaves differently when 'searchChars' is longer
363      *  than 'replaceChars'. CharSetUtils#translate will use the last char of the replacement
364      *  string whereas StringUtils#replaceChars will delete
365      */
366     public static String   translate(String   str, String   searchChars, String   replaceChars) {
367         if (StringUtils.isEmpty(str)) {
368             return str;
369         }
370         StringBuffer   buffer = new StringBuffer  (str.length());
371         char[] chrs = str.toCharArray();
372         char[] withChrs = replaceChars.toCharArray();
373         int sz = chrs.length;
374         int withMax = replaceChars.length() - 1;
375         for(int i=0; i<sz; i++) {
376             int idx = searchChars.indexOf(chrs[i]);
377             if(idx != -1) {
378                 if(idx > withMax) {
379                     idx = withMax;
380                 }
381                 buffer.append(withChrs[idx]);
382             } else {
383                 buffer.append(chrs[i]);
384             }
385         }
386         return buffer.toString();
387     }
388 
389 }
390
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags