KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > lang > 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 JavaDoc[] 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 JavaDoc squeeze(String JavaDoc str, String JavaDoc set) {
96         if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
97             return str;
98         }
99         String JavaDoc[] strs = new String JavaDoc[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 JavaDoc squeeze(String JavaDoc str, String JavaDoc[] set) {
119         if (StringUtils.isEmpty(str) || ArrayUtils.isEmpty(set)) {
120             return str;
121         }
122         CharSet chars = evaluateSet(set);
123         StringBuffer JavaDoc buffer = new StringBuffer JavaDoc(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 JavaDoc str, String JavaDoc set) {
162         if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
163             return 0;
164         }
165         String JavaDoc[] strs = new String JavaDoc[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 JavaDoc str, String JavaDoc[] 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 JavaDoc keep(String JavaDoc str, String JavaDoc set) {
222         if (str == null) {
223             return null;
224         }
225         if (str.length() == 0 || StringUtils.isEmpty(set)) {
226             return "";
227         }
228         String JavaDoc[] strs = new String JavaDoc[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 JavaDoc keep(String JavaDoc str, String JavaDoc[] 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 JavaDoc delete(String JavaDoc str, String JavaDoc set) {
280         if (StringUtils.isEmpty(str) || StringUtils.isEmpty(set)) {
281             return str;
282         }
283         String JavaDoc[] strs = new String JavaDoc[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 JavaDoc delete(String JavaDoc str, String JavaDoc[] 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 JavaDoc modify(String JavaDoc str, String JavaDoc[] set, boolean expect) {
320         CharSet chars = evaluateSet(set);
321         StringBuffer JavaDoc buffer = new StringBuffer JavaDoc(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 JavaDoc translate(String JavaDoc str, String JavaDoc searchChars, String JavaDoc replaceChars) {
367         if (StringUtils.isEmpty(str)) {
368             return str;
369         }
370         StringBuffer JavaDoc buffer = new StringBuffer JavaDoc(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
Popular Tags