KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright 2004-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 char primitives and Character objects.</p>
20  *
21  * <p>This class tries to handle <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  * @author Stephen Colebourne
26  * @since 2.1
27  * @version $Id: CharUtils.java 161243 2005-04-14 04:30:28Z ggregory $
28  */
29 public class CharUtils {
30     
31     private static final String JavaDoc CHAR_STRING =
32         "\u0000\u0001\u0002\u0003\u0004\u0005\u0006\u0007" +
33         "\b\t\n\u000b\f\r\u000e\u000f" +
34         "\u0010\u0011\u0012\u0013\u0014\u0015\u0016\u0017" +
35         "\u0018\u0019\u001a\u001b\u001c\u001d\u001e\u001f" +
36         "\u0020\u0021\"\u0023\u0024\u0025\u0026\u0027" +
37         "\u0028\u0029\u002a\u002b\u002c\u002d\u002e\u002f" +
38         "\u0030\u0031\u0032\u0033\u0034\u0035\u0036\u0037" +
39         "\u0038\u0039\u003a\u003b\u003c\u003d\u003e\u003f" +
40         "\u0040\u0041\u0042\u0043\u0044\u0045\u0046\u0047" +
41         "\u0048\u0049\u004a\u004b\u004c\u004d\u004e\u004f" +
42         "\u0050\u0051\u0052\u0053\u0054\u0055\u0056\u0057" +
43         "\u0058\u0059\u005a\u005b\\\u005d\u005e\u005f" +
44         "\u0060\u0061\u0062\u0063\u0064\u0065\u0066\u0067" +
45         "\u0068\u0069\u006a\u006b\u006c\u006d\u006e\u006f" +
46         "\u0070\u0071\u0072\u0073\u0074\u0075\u0076\u0077" +
47         "\u0078\u0079\u007a\u007b\u007c\u007d\u007e\u007f";
48     
49     private static final String JavaDoc[] CHAR_STRING_ARRAY = new String JavaDoc[128];
50     private static final Character JavaDoc[] CHAR_ARRAY = new Character JavaDoc[128];
51     
52     static {
53         for (int i = 127; i >= 0; i--) {
54             CHAR_STRING_ARRAY[i] = CHAR_STRING.substring(i, i + 1);
55             CHAR_ARRAY[i] = new Character JavaDoc((char) i);
56         }
57     }
58     
59     /**
60      * <p><code>CharUtils</code> instances should NOT be constructed in standard programming.
61      * Instead, the class should be used as <code>CharUtils.toString('c');</code>.</p>
62      *
63      * <p>This constructor is public to permit tools that require a JavaBean instance
64      * to operate.</p>
65      */
66     public CharUtils() {
67     }
68
69     //-----------------------------------------------------------------------
70 /**
71      * <p>Converts the character to a Character.</p>
72      *
73      * <p>For ASCII 7 bit characters, this uses a cache that will return the
74      * same Character object each time.</p>
75      *
76      * <pre>
77      * CharUtils.toCharacterObject(' ') = ' '
78      * CharUtils.toCharacterObject('A') = 'A'
79      * </pre>
80      *
81      * @param ch the character to convert
82      * @return a Character of the specified character
83      */
84     public static Character JavaDoc toCharacterObject(char ch) {
85         if (ch < CHAR_ARRAY.length) {
86             return CHAR_ARRAY[ch];
87         } else {
88             return new Character JavaDoc(ch);
89         }
90     }
91     
92     /**
93      * <p>Converts the String to a Character using the first character, returning
94      * null for empty Strings.</p>
95      *
96      * <p>For ASCII 7 bit characters, this uses a cache that will return the
97      * same Character object each time.</p>
98      *
99      * <pre>
100      * CharUtils.toCharacterObject(null) = null
101      * CharUtils.toCharacterObject("") = null
102      * CharUtils.toCharacterObject("A") = 'A'
103      * CharUtils.toCharacterObject("BA") = 'B'
104      * </pre>
105      *
106      * @param str the character to convert
107      * @return the Character value of the first letter of the String
108      */
109     public static Character JavaDoc toCharacterObject(String JavaDoc str) {
110         if (StringUtils.isEmpty(str)) {
111             return null;
112         }
113         return toCharacterObject(str.charAt(0));
114     }
115     
116     //-----------------------------------------------------------------------
117 /**
118      * <p>Converts the Character to a char throwing an exception for <code>null</code>.</p>
119      *
120      * <pre>
121      * CharUtils.toChar(null) = IllegalArgumentException
122      * CharUtils.toChar(' ') = ' '
123      * CharUtils.toChar('A') = 'A'
124      * </pre>
125      *
126      * @param ch the character to convert
127      * @return the char value of the Character
128      * @throws IllegalArgumentException if the Character is null
129      */
130     public static char toChar(Character JavaDoc ch) {
131         if (ch == null) {
132             throw new IllegalArgumentException JavaDoc("The Character must not be null");
133         }
134         return ch.charValue();
135     }
136     
137     /**
138      * <p>Converts the Character to a char handling <code>null</code>.</p>
139      *
140      * <pre>
141      * CharUtils.toChar(null, 'X') = 'X'
142      * CharUtils.toChar(' ', 'X') = ' '
143      * CharUtils.toChar('A', 'X') = 'A'
144      * </pre>
145      *
146      * @param ch the character to convert
147      * @param defaultValue the value to use if the Character is null
148      * @return the char value of the Character or the default if null
149      */
150     public static char toChar(Character JavaDoc ch, char defaultValue) {
151         if (ch == null) {
152             return defaultValue;
153         }
154         return ch.charValue();
155     }
156     
157     //-----------------------------------------------------------------------
158 /**
159      * <p>Converts the String to a char using the first character, throwing
160      * an exception on empty Strings.</p>
161      *
162      * <pre>
163      * CharUtils.toChar(null) = IllegalArgumentException
164      * CharUtils.toChar("") = IllegalArgumentException
165      * CharUtils.toChar("A") = 'A'
166      * CharUtils.toChar("BA") = 'B'
167      * </pre>
168      *
169      * @param str the character to convert
170      * @return the char value of the first letter of the String
171      * @throws IllegalArgumentException if the String is empty
172      */
173     public static char toChar(String JavaDoc str) {
174         if (StringUtils.isEmpty(str)) {
175             throw new IllegalArgumentException JavaDoc("The String must not be empty");
176         }
177         return str.charAt(0);
178     }
179     
180     /**
181      * <p>Converts the String to a char using the first character, defaulting
182      * the value on empty Strings.</p>
183      *
184      * <pre>
185      * CharUtils.toChar(null, 'X') = 'X'
186      * CharUtils.toChar("", 'X') = 'X'
187      * CharUtils.toChar("A", 'X') = 'A'
188      * CharUtils.toChar("BA", 'X') = 'B'
189      * </pre>
190      *
191      * @param str the character to convert
192      * @param defaultValue the value to use if the Character is null
193      * @return the char value of the first letter of the String or the default if null
194      */
195     public static char toChar(String JavaDoc str, char defaultValue) {
196         if (StringUtils.isEmpty(str)) {
197             return defaultValue;
198         }
199         return str.charAt(0);
200     }
201     
202     //-----------------------------------------------------------------------
203 /**
204      * <p>Converts the character to the Integer it represents, throwing an
205      * exception if the character is not numeric.</p>
206      *
207      * <p>This method coverts the char '1' to the int 1 and so on.</p>
208      *
209      * <pre>
210      * CharUtils.toIntValue('3') = 3
211      * CharUtils.toIntValue('A') = IllegalArgumentException
212      * </pre>
213      *
214      * @param ch the character to convert
215      * @return the int value of the character
216      * @throws IllegalArgumentException if the character is not ASCII numeric
217      */
218     public static int toIntValue(char ch) {
219         if (isAsciiNumeric(ch) == false) {
220             throw new IllegalArgumentException JavaDoc("The character " + ch + " is not in the range '0' - '9'");
221         }
222         return ch - 48;
223     }
224     
225     /**
226      * <p>Converts the character to the Integer it represents, throwing an
227      * exception if the character is not numeric.</p>
228      *
229      * <p>This method coverts the char '1' to the int 1 and so on.</p>
230      *
231      * <pre>
232      * CharUtils.toIntValue('3', -1) = 3
233      * CharUtils.toIntValue('A', -1) = -1
234      * </pre>
235      *
236      * @param ch the character to convert
237      * @param defaultValue the default value to use if the character is not numeric
238      * @return the int value of the character
239      */
240     public static int toIntValue(char ch, int defaultValue) {
241         if (isAsciiNumeric(ch) == false) {
242             return defaultValue;
243         }
244         return ch - 48;
245     }
246     
247     /**
248      * <p>Converts the character to the Integer it represents, throwing an
249      * exception if the character is not numeric.</p>
250      *
251      * <p>This method coverts the char '1' to the int 1 and so on.</p>
252      *
253      * <pre>
254      * CharUtils.toIntValue(null) = IllegalArgumentException
255      * CharUtils.toIntValue('3') = 3
256      * CharUtils.toIntValue('A') = IllegalArgumentException
257      * </pre>
258      *
259      * @param ch the character to convert, not null
260      * @return the int value of the character
261      * @throws IllegalArgumentException if the Character is not ASCII numeric or is null
262      */
263     public static int toIntValue(Character JavaDoc ch) {
264         if (ch == null) {
265             throw new IllegalArgumentException JavaDoc("The character must not be null");
266         }
267         return toIntValue(ch.charValue());
268     }
269     
270     /**
271      * <p>Converts the character to the Integer it represents, throwing an
272      * exception if the character is not numeric.</p>
273      *
274      * <p>This method coverts the char '1' to the int 1 and so on.</p>
275      *
276      * <pre>
277      * CharUtils.toIntValue(null, -1) = -1
278      * CharUtils.toIntValue('3', -1) = 3
279      * CharUtils.toIntValue('A', -1) = -1
280      * </pre>
281      *
282      * @param ch the character to convert
283      * @param defaultValue the default value to use if the character is not numeric
284      * @return the int value of the character
285      */
286     public static int toIntValue(Character JavaDoc ch, int defaultValue) {
287         if (ch == null) {
288             return defaultValue;
289         }
290         return toIntValue(ch.charValue(), defaultValue);
291     }
292     
293     //-----------------------------------------------------------------------
294 /**
295      * <p>Converts the character to a String that contains the one character.</p>
296      *
297      * <p>For ASCII 7 bit characters, this uses a cache that will return the
298      * same String object each time.</p>
299      *
300      * <pre>
301      * CharUtils.toString(' ') = " "
302      * CharUtils.toString('A') = "A"
303      * </pre>
304      *
305      * @param ch the character to convert
306      * @return a String containing the one specified character
307      */
308     public static String JavaDoc toString(char ch) {
309         if (ch < 128) {
310             return CHAR_STRING_ARRAY[ch];
311         } else {
312             return new String JavaDoc(new char[] {ch});
313         }
314     }
315     
316     /**
317      * <p>Converts the character to a String that contains the one character.</p>
318      *
319      * <p>For ASCII 7 bit characters, this uses a cache that will return the
320      * same String object each time.</p>
321      *
322      * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
323      *
324      * <pre>
325      * CharUtils.toString(null) = null
326      * CharUtils.toString(' ') = " "
327      * CharUtils.toString('A') = "A"
328      * </pre>
329      *
330      * @param ch the character to convert
331      * @return a String containing the one specified character
332      */
333     public static String JavaDoc toString(Character JavaDoc ch) {
334         if (ch == null) {
335             return null;
336         } else {
337             return toString(ch.charValue());
338         }
339     }
340     
341     //--------------------------------------------------------------------------
342 /**
343      * <p>Converts the string to the unicode format ' '.</p>
344      *
345      * <p>This format is the Java source code format.</p>
346      *
347      * <pre>
348      * CharUtils.unicodeEscaped(' ') = " "
349      * CharUtils.unicodeEscaped('A') = "A"
350      * </pre>
351      *
352      * @param ch the character to convert
353      * @return the escaped unicode string
354      */
355     public static String JavaDoc unicodeEscaped(char ch) {
356         if (ch < 0x10) {
357             return "\\u000" + Integer.toHexString(ch);
358         } else if (ch < 0x100) {
359             return "\\u00" + Integer.toHexString(ch);
360         } else if (ch < 0x1000) {
361             return "\\u0" + Integer.toHexString(ch);
362         }
363         return "\\u" + Integer.toHexString(ch);
364     }
365     
366     /**
367      * <p>Converts the string to the unicode format ' '.</p>
368      *
369      * <p>This format is the Java source code format.</p>
370      *
371      * <p>If <code>null</code> is passed in, <code>null</code> will be returned.</p>
372      *
373      * <pre>
374      * CharUtils.unicodeEscaped(null) = null
375      * CharUtils.unicodeEscaped(' ') = " "
376      * CharUtils.unicodeEscaped('A') = "A"
377      * </pre>
378      *
379      * @param ch the character to convert, may be null
380      * @return the escaped unicode string, null if null input
381      */
382     public static String JavaDoc unicodeEscaped(Character JavaDoc ch) {
383         if (ch == null) {
384             return null;
385         }
386         return unicodeEscaped(ch.charValue());
387     }
388     
389     //--------------------------------------------------------------------------
390 /**
391      * <p>Checks whether the character is ASCII 7 bit.</p>
392      *
393      * <pre>
394      * CharUtils.isAscii('a') = true
395      * CharUtils.isAscii('A') = true
396      * CharUtils.isAscii('3') = true
397      * CharUtils.isAscii('-') = true
398      * CharUtils.isAscii('\n') = true
399      * CharUtils.isAscii('&copy;') = false
400      * </pre>
401      *
402      * @param ch the character to check
403      * @return true if less than 128
404      */
405     public static boolean isAscii(char ch) {
406         return ch < 128;
407     }
408     
409     /**
410      * <p>Checks whether the character is ASCII 7 bit printable.</p>
411      *
412      * <pre>
413      * CharUtils.isAsciiPrintable('a') = true
414      * CharUtils.isAsciiPrintable('A') = true
415      * CharUtils.isAsciiPrintable('3') = true
416      * CharUtils.isAsciiPrintable('-') = true
417      * CharUtils.isAsciiPrintable('\n') = false
418      * CharUtils.isAsciiPrintable('&copy;') = false
419      * </pre>
420      *
421      * @param ch the character to check
422      * @return true if between 32 and 126 inclusive
423      */
424     public static boolean isAsciiPrintable(char ch) {
425         return ch >= 32 && ch < 127;
426     }
427     
428     /**
429      * <p>Checks whether the character is ASCII 7 bit control.</p>
430      *
431      * <pre>
432      * CharUtils.isAsciiControl('a') = false
433      * CharUtils.isAsciiControl('A') = false
434      * CharUtils.isAsciiControl('3') = false
435      * CharUtils.isAsciiControl('-') = false
436      * CharUtils.isAsciiControl('\n') = true
437      * CharUtils.isAsciiControl('&copy;') = false
438      * </pre>
439      *
440      * @param ch the character to check
441      * @return true if less than 32 or equals 127
442      */
443     public static boolean isAsciiControl(char ch) {
444         return ch < 32 || ch == 127;
445     }
446     
447     /**
448      * <p>Checks whether the character is ASCII 7 bit alphabetic.</p>
449      *
450      * <pre>
451      * CharUtils.isAsciiAlpha('a') = true
452      * CharUtils.isAsciiAlpha('A') = true
453      * CharUtils.isAsciiAlpha('3') = false
454      * CharUtils.isAsciiAlpha('-') = false
455      * CharUtils.isAsciiAlpha('\n') = false
456      * CharUtils.isAsciiAlpha('&copy;') = false
457      * </pre>
458      *
459      * @param ch the character to check
460      * @return true if between 65 and 90 or 97 and 122 inclusive
461      */
462     public static boolean isAsciiAlpha(char ch) {
463         return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z');
464     }
465     
466     /**
467      * <p>Checks whether the character is ASCII 7 bit alphabetic upper case.</p>
468      *
469      * <pre>
470      * CharUtils.isAsciiAlphaUpper('a') = false
471      * CharUtils.isAsciiAlphaUpper('A') = true
472      * CharUtils.isAsciiAlphaUpper('3') = false
473      * CharUtils.isAsciiAlphaUpper('-') = false
474      * CharUtils.isAsciiAlphaUpper('\n') = false
475      * CharUtils.isAsciiAlphaUpper('&copy;') = false
476      * </pre>
477      *
478      * @param ch the character to check
479      * @return true if between 65 and 90 inclusive
480      */
481     public static boolean isAsciiAlphaUpper(char ch) {
482         return ch >= 'A' && ch <= 'Z';
483     }
484     
485     /**
486      * <p>Checks whether the character is ASCII 7 bit alphabetic lower case.</p>
487      *
488      * <pre>
489      * CharUtils.isAsciiAlphaLower('a') = true
490      * CharUtils.isAsciiAlphaLower('A') = false
491      * CharUtils.isAsciiAlphaLower('3') = false
492      * CharUtils.isAsciiAlphaLower('-') = false
493      * CharUtils.isAsciiAlphaLower('\n') = false
494      * CharUtils.isAsciiAlphaLower('&copy;') = false
495      * </pre>
496      *
497      * @param ch the character to check
498      * @return true if between 97 and 122 inclusive
499      */
500     public static boolean isAsciiAlphaLower(char ch) {
501         return ch >= 'a' && ch <= 'z';
502     }
503     
504     /**
505      * <p>Checks whether the character is ASCII 7 bit numeric.</p>
506      *
507      * <pre>
508      * CharUtils.isAsciiNumeric('a') = false
509      * CharUtils.isAsciiNumeric('A') = false
510      * CharUtils.isAsciiNumeric('3') = true
511      * CharUtils.isAsciiNumeric('-') = false
512      * CharUtils.isAsciiNumeric('\n') = false
513      * CharUtils.isAsciiNumeric('&copy;') = false
514      * </pre>
515      *
516      * @param ch the character to check
517      * @return true if between 48 and 57 inclusive
518      */
519     public static boolean isAsciiNumeric(char ch) {
520         return ch >= '0' && ch <= '9';
521     }
522     
523     /**
524      * <p>Checks whether the character is ASCII 7 bit numeric.</p>
525      *
526      * <pre>
527      * CharUtils.isAsciiAlphanumeric('a') = true
528      * CharUtils.isAsciiAlphanumeric('A') = true
529      * CharUtils.isAsciiAlphanumeric('3') = true
530      * CharUtils.isAsciiAlphanumeric('-') = false
531      * CharUtils.isAsciiAlphanumeric('\n') = false
532      * CharUtils.isAsciiAlphanumeric('&copy;') = false
533      * </pre>
534      *
535      * @param ch the character to check
536      * @return true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
537      */
538     public static boolean isAsciiAlphanumeric(char ch) {
539         return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9');
540     }
541     
542 }
543
Popular Tags