Coverage Report - org.apache.commons.lang3.CharUtils
 
Classes in this File Line Coverage Branch Coverage Complexity
CharUtils
100%
60/60
100%
54/54
2,292
 
 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  
 /**
 20  
  * <p>Operations on char primitives and Character objects.</p>
 21  
  *
 22  
  * <p>This class tries to handle {@code null} input gracefully.
 23  
  * An exception will not be thrown for a {@code null} input.
 24  
  * Each method documents its behaviour in more detail.</p>
 25  
  * 
 26  
  * <p>#ThreadSafe#</p>
 27  
  * @since 2.1
 28  
  * @version $Id: CharUtils.java 1666535 2015-03-13 18:18:59Z britter $
 29  
  */
 30  
 public class CharUtils {
 31  
     
 32  1
     private static final String[] CHAR_STRING_ARRAY = new String[128];
 33  
     
 34  1
     private static final char[] HEX_DIGITS = new char[] {'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'};
 35  
 
 36  
     /**
 37  
      * {@code \u000a} linefeed LF ('\n').
 38  
      * 
 39  
      * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
 40  
      *      for Character and String Literals</a>
 41  
      * @since 2.2
 42  
      */
 43  
     public static final char LF = '\n';
 44  
 
 45  
     /**
 46  
      * {@code \u000d} carriage return CR ('\r').
 47  
      * 
 48  
      * @see <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.6">JLF: Escape Sequences
 49  
      *      for Character and String Literals</a>
 50  
      * @since 2.2
 51  
      */
 52  
     public static final char CR = '\r';
 53  
     
 54  
 
 55  
     static {
 56  129
         for (char c = 0; c < CHAR_STRING_ARRAY.length; c++) {
 57  128
             CHAR_STRING_ARRAY[c] = String.valueOf(c);
 58  
         }
 59  1
     }
 60  
 
 61  
     /**
 62  
      * <p>{@code CharUtils} instances should NOT be constructed in standard programming.
 63  
      * Instead, the class should be used as {@code CharUtils.toString('c');}.</p>
 64  
      *
 65  
      * <p>This constructor is public to permit tools that require a JavaBean instance
 66  
      * to operate.</p>
 67  
      */
 68  
     public CharUtils() {
 69  1
       super();
 70  1
     }
 71  
 
 72  
     //-----------------------------------------------------------------------
 73  
     /**
 74  
      * <p>Converts the character to a Character.</p>
 75  
      * 
 76  
      * <p>For ASCII 7 bit characters, this uses a cache that will return the
 77  
      * same Character object each time.</p>
 78  
      *
 79  
      * <pre>
 80  
      *   CharUtils.toCharacterObject(' ')  = ' '
 81  
      *   CharUtils.toCharacterObject('A')  = 'A'
 82  
      * </pre>
 83  
      *
 84  
      * @deprecated Java 5 introduced {@link Character#valueOf(char)} which caches chars 0 through 127.
 85  
      * @param ch  the character to convert
 86  
      * @return a Character of the specified character
 87  
      */
 88  
     @Deprecated
 89  
     public static Character toCharacterObject(final char ch) {
 90  396
         return Character.valueOf(ch);
 91  
     }
 92  
     
 93  
     /**
 94  
      * <p>Converts the String to a Character using the first character, returning
 95  
      * null for empty Strings.</p>
 96  
      * 
 97  
      * <p>For ASCII 7 bit characters, this uses a cache that will return the
 98  
      * same Character object each time.</p>
 99  
      * 
 100  
      * <pre>
 101  
      *   CharUtils.toCharacterObject(null) = null
 102  
      *   CharUtils.toCharacterObject("")   = null
 103  
      *   CharUtils.toCharacterObject("A")  = 'A'
 104  
      *   CharUtils.toCharacterObject("BA") = 'B'
 105  
      * </pre>
 106  
      *
 107  
      * @param str  the character to convert
 108  
      * @return the Character value of the first letter of the String
 109  
      */
 110  
     public static Character toCharacterObject(final String str) {
 111  7
         if (StringUtils.isEmpty(str)) {
 112  2
             return null;
 113  
         }
 114  5
         return Character.valueOf(str.charAt(0));
 115  
     }
 116  
     
 117  
     //-----------------------------------------------------------------------
 118  
     /**
 119  
      * <p>Converts the Character to a char throwing an exception for {@code null}.</p>
 120  
      * 
 121  
      * <pre>
 122  
      *   CharUtils.toChar(' ')  = ' '
 123  
      *   CharUtils.toChar('A')  = 'A'
 124  
      *   CharUtils.toChar(null) throws IllegalArgumentException
 125  
      * </pre>
 126  
      *
 127  
      * @param ch  the character to convert
 128  
      * @return the char value of the Character
 129  
      * @throws IllegalArgumentException if the Character is null
 130  
      */
 131  
     public static char toChar(final Character ch) {
 132  3
         if (ch == null) {
 133  1
             throw new IllegalArgumentException("The Character must not be null");
 134  
         }
 135  2
         return ch.charValue();
 136  
     }
 137  
     
 138  
     /**
 139  
      * <p>Converts the Character to a char handling {@code null}.</p>
 140  
      * 
 141  
      * <pre>
 142  
      *   CharUtils.toChar(null, 'X') = 'X'
 143  
      *   CharUtils.toChar(' ', 'X')  = ' '
 144  
      *   CharUtils.toChar('A', 'X')  = 'A'
 145  
      * </pre>
 146  
      *
 147  
      * @param ch  the character to convert
 148  
      * @param defaultValue  the value to use if the  Character is null
 149  
      * @return the char value of the Character or the default if null
 150  
      */
 151  
     public static char toChar(final Character ch, final char defaultValue) {
 152  3
         if (ch == null) {
 153  1
             return defaultValue;
 154  
         }
 155  2
         return ch.charValue();
 156  
     }
 157  
     
 158  
     //-----------------------------------------------------------------------
 159  
     /**
 160  
      * <p>Converts the String to a char using the first character, throwing
 161  
      * an exception on empty Strings.</p>
 162  
      * 
 163  
      * <pre>
 164  
      *   CharUtils.toChar("A")  = 'A'
 165  
      *   CharUtils.toChar("BA") = 'B'
 166  
      *   CharUtils.toChar(null) throws IllegalArgumentException
 167  
      *   CharUtils.toChar("")   throws IllegalArgumentException
 168  
      * </pre>
 169  
      *
 170  
      * @param str  the character to convert
 171  
      * @return the char value of the first letter of the String
 172  
      * @throws IllegalArgumentException if the String is empty
 173  
      */
 174  
     public static char toChar(final String str) {
 175  4
         if (StringUtils.isEmpty(str)) {
 176  2
             throw new IllegalArgumentException("The String must not be empty");
 177  
         }
 178  2
         return str.charAt(0);
 179  
     }
 180  
     
 181  
     /**
 182  
      * <p>Converts the String to a char using the first character, defaulting
 183  
      * the value on empty Strings.</p>
 184  
      * 
 185  
      * <pre>
 186  
      *   CharUtils.toChar(null, 'X') = 'X'
 187  
      *   CharUtils.toChar("", 'X')   = 'X'
 188  
      *   CharUtils.toChar("A", 'X')  = 'A'
 189  
      *   CharUtils.toChar("BA", 'X') = 'B'
 190  
      * </pre>
 191  
      *
 192  
      * @param str  the character to convert
 193  
      * @param defaultValue  the value to use if the  Character is null
 194  
      * @return the char value of the first letter of the String or the default if null
 195  
      */
 196  
     public static char toChar(final String str, final char defaultValue) {
 197  4
         if (StringUtils.isEmpty(str)) {
 198  2
             return defaultValue;
 199  
         }
 200  2
         return str.charAt(0);
 201  
     }
 202  
     
 203  
     //-----------------------------------------------------------------------
 204  
     /**
 205  
      * <p>Converts the character to the Integer it represents, throwing an
 206  
      * exception if the character is not numeric.</p>
 207  
      * 
 208  
      * <p>This method coverts the char '1' to the int 1 and so on.</p>
 209  
      *
 210  
      * <pre>
 211  
      *   CharUtils.toIntValue('3')  = 3
 212  
      *   CharUtils.toIntValue('A')  throws IllegalArgumentException
 213  
      * </pre>
 214  
      *
 215  
      * @param ch  the character to convert
 216  
      * @return the int value of the character
 217  
      * @throws IllegalArgumentException if the character is not ASCII numeric
 218  
      */
 219  
     public static int toIntValue(final char ch) {
 220  14
         if (isAsciiNumeric(ch) == false) {
 221  2
             throw new IllegalArgumentException("The character " + ch + " is not in the range '0' - '9'");
 222  
         }
 223  12
         return ch - 48;
 224  
     }
 225  
     
 226  
     /**
 227  
      * <p>Converts the character to the Integer it represents, throwing an
 228  
      * exception if the character is not numeric.</p>
 229  
      * 
 230  
      * <p>This method coverts the char '1' to the int 1 and so on.</p>
 231  
      *
 232  
      * <pre>
 233  
      *   CharUtils.toIntValue('3', -1)  = 3
 234  
      *   CharUtils.toIntValue('A', -1)  = -1
 235  
      * </pre>
 236  
      *
 237  
      * @param ch  the character to convert
 238  
      * @param defaultValue  the default value to use if the character is not numeric
 239  
      * @return the int value of the character
 240  
      */
 241  
     public static int toIntValue(final char ch, final int defaultValue) {
 242  6
         if (isAsciiNumeric(ch) == false) {
 243  2
             return defaultValue;
 244  
         }
 245  4
         return ch - 48;
 246  
     }
 247  
     
 248  
     /**
 249  
      * <p>Converts the character to the Integer it represents, throwing an
 250  
      * exception if the character is not numeric.</p>
 251  
      * 
 252  
      * <p>This method coverts the char '1' to the int 1 and so on.</p>
 253  
      *
 254  
      * <pre>
 255  
      *   CharUtils.toIntValue('3')  = 3
 256  
      *   CharUtils.toIntValue(null) throws IllegalArgumentException
 257  
      *   CharUtils.toIntValue('A')  throws IllegalArgumentException
 258  
      * </pre>
 259  
      *
 260  
      * @param ch  the character to convert, not null
 261  
      * @return the int value of the character
 262  
      * @throws IllegalArgumentException if the Character is not ASCII numeric or is null
 263  
      */
 264  
     public static int toIntValue(final Character ch) {
 265  4
         if (ch == null) {
 266  1
             throw new IllegalArgumentException("The character must not be null");
 267  
         }
 268  3
         return toIntValue(ch.charValue());
 269  
     }
 270  
     
 271  
     /**
 272  
      * <p>Converts the character to the Integer it represents, throwing an
 273  
      * exception if the character is not numeric.</p>
 274  
      * 
 275  
      * <p>This method coverts the char '1' to the int 1 and so on.</p>
 276  
      *
 277  
      * <pre>
 278  
      *   CharUtils.toIntValue(null, -1) = -1
 279  
      *   CharUtils.toIntValue('3', -1)  = 3
 280  
      *   CharUtils.toIntValue('A', -1)  = -1
 281  
      * </pre>
 282  
      *
 283  
      * @param ch  the character to convert
 284  
      * @param defaultValue  the default value to use if the character is not numeric
 285  
      * @return the int value of the character
 286  
      */
 287  
     public static int toIntValue(final Character ch, final int defaultValue) {
 288  4
         if (ch == null) {
 289  1
             return defaultValue;
 290  
         }
 291  3
         return toIntValue(ch.charValue(), defaultValue);
 292  
     }
 293  
     
 294  
     //-----------------------------------------------------------------------
 295  
     /**
 296  
      * <p>Converts the character to a String that contains the one character.</p>
 297  
      * 
 298  
      * <p>For ASCII 7 bit characters, this uses a cache that will return the
 299  
      * same String object each time.</p>
 300  
      *
 301  
      * <pre>
 302  
      *   CharUtils.toString(' ')  = " "
 303  
      *   CharUtils.toString('A')  = "A"
 304  
      * </pre>
 305  
      *
 306  
      * @param ch  the character to convert
 307  
      * @return a String containing the one specified character
 308  
      */
 309  
     public static String toString(final char ch) {
 310  398
         if (ch < 128) {
 311  262
             return CHAR_STRING_ARRAY[ch];
 312  
         }
 313  136
         return new String(new char[] {ch});
 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} is passed in, {@code null} 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 toString(final Character ch) {
 334  4
         if (ch == null) {
 335  1
             return null;
 336  
         }
 337  3
         return toString(ch.charValue());
 338  
     }
 339  
     
 340  
     //--------------------------------------------------------------------------
 341  
     /**
 342  
      * <p>Converts the string to the Unicode format '\u0020'.</p>
 343  
      * 
 344  
      * <p>This format is the Java source code format.</p>
 345  
      *
 346  
      * <pre>
 347  
      *   CharUtils.unicodeEscaped(' ') = "\u0020"
 348  
      *   CharUtils.unicodeEscaped('A') = "\u0041"
 349  
      * </pre>
 350  
      * 
 351  
      * @param ch  the character to convert
 352  
      * @return the escaped Unicode string
 353  
      */
 354  
     public static String unicodeEscaped(final char ch) {
 355  201
         StringBuilder sb = new StringBuilder(6);
 356  201
         sb.append("\\u");
 357  201
         sb.append(HEX_DIGITS[(ch >> 12) & 15]);
 358  201
         sb.append(HEX_DIGITS[(ch >> 8) & 15]);
 359  201
         sb.append(HEX_DIGITS[(ch >> 4) & 15]);
 360  201
         sb.append(HEX_DIGITS[(ch) & 15]);
 361  201
         return sb.toString();
 362  
     }
 363  
     
 364  
     /**
 365  
      * <p>Converts the string to the Unicode format '\u0020'.</p>
 366  
      * 
 367  
      * <p>This format is the Java source code format.</p>
 368  
      * 
 369  
      * <p>If {@code null} is passed in, {@code null} will be returned.</p>
 370  
      *
 371  
      * <pre>
 372  
      *   CharUtils.unicodeEscaped(null) = null
 373  
      *   CharUtils.unicodeEscaped(' ')  = "\u0020"
 374  
      *   CharUtils.unicodeEscaped('A')  = "\u0041"
 375  
      * </pre>
 376  
      * 
 377  
      * @param ch  the character to convert, may be null
 378  
      * @return the escaped Unicode string, null if null input
 379  
      */
 380  
     public static String unicodeEscaped(final Character ch) {
 381  2
         if (ch == null) {
 382  1
             return null;
 383  
         }
 384  1
         return unicodeEscaped(ch.charValue());
 385  
     }
 386  
     
 387  
     //--------------------------------------------------------------------------
 388  
     /**
 389  
      * <p>Checks whether the character is ASCII 7 bit.</p>
 390  
      *
 391  
      * <pre>
 392  
      *   CharUtils.isAscii('a')  = true
 393  
      *   CharUtils.isAscii('A')  = true
 394  
      *   CharUtils.isAscii('3')  = true
 395  
      *   CharUtils.isAscii('-')  = true
 396  
      *   CharUtils.isAscii('\n') = true
 397  
      *   CharUtils.isAscii('&copy;') = false
 398  
      * </pre>
 399  
      * 
 400  
      * @param ch  the character to check
 401  
      * @return true if less than 128
 402  
      */
 403  
     public static boolean isAscii(final char ch) {
 404  135
         return ch < 128;
 405  
     }
 406  
     
 407  
     /**
 408  
      * <p>Checks whether the character is ASCII 7 bit printable.</p>
 409  
      *
 410  
      * <pre>
 411  
      *   CharUtils.isAsciiPrintable('a')  = true
 412  
      *   CharUtils.isAsciiPrintable('A')  = true
 413  
      *   CharUtils.isAsciiPrintable('3')  = true
 414  
      *   CharUtils.isAsciiPrintable('-')  = true
 415  
      *   CharUtils.isAsciiPrintable('\n') = false
 416  
      *   CharUtils.isAsciiPrintable('&copy;') = false
 417  
      * </pre>
 418  
      * 
 419  
      * @param ch  the character to check
 420  
      * @return true if between 32 and 126 inclusive
 421  
      */
 422  
     public static boolean isAsciiPrintable(final char ch) {
 423  318
         return ch >= 32 && ch < 127;
 424  
     }
 425  
     
 426  
     /**
 427  
      * <p>Checks whether the character is ASCII 7 bit control.</p>
 428  
      *
 429  
      * <pre>
 430  
      *   CharUtils.isAsciiControl('a')  = false
 431  
      *   CharUtils.isAsciiControl('A')  = false
 432  
      *   CharUtils.isAsciiControl('3')  = false
 433  
      *   CharUtils.isAsciiControl('-')  = false
 434  
      *   CharUtils.isAsciiControl('\n') = true
 435  
      *   CharUtils.isAsciiControl('&copy;') = false
 436  
      * </pre>
 437  
      * 
 438  
      * @param ch  the character to check
 439  
      * @return true if less than 32 or equals 127
 440  
      */
 441  
     public static boolean isAsciiControl(final char ch) {
 442  202
         return ch < 32 || ch == 127;
 443  
     }
 444  
     
 445  
     /**
 446  
      * <p>Checks whether the character is ASCII 7 bit alphabetic.</p>
 447  
      *
 448  
      * <pre>
 449  
      *   CharUtils.isAsciiAlpha('a')  = true
 450  
      *   CharUtils.isAsciiAlpha('A')  = true
 451  
      *   CharUtils.isAsciiAlpha('3')  = false
 452  
      *   CharUtils.isAsciiAlpha('-')  = false
 453  
      *   CharUtils.isAsciiAlpha('\n') = false
 454  
      *   CharUtils.isAsciiAlpha('&copy;') = false
 455  
      * </pre>
 456  
      * 
 457  
      * @param ch  the character to check
 458  
      * @return true if between 65 and 90 or 97 and 122 inclusive
 459  
      */
 460  
     public static boolean isAsciiAlpha(final char ch) {
 461  404
         return isAsciiAlphaUpper(ch) || isAsciiAlphaLower(ch);
 462  
     }
 463  
     
 464  
     /**
 465  
      * <p>Checks whether the character is ASCII 7 bit alphabetic upper case.</p>
 466  
      *
 467  
      * <pre>
 468  
      *   CharUtils.isAsciiAlphaUpper('a')  = false
 469  
      *   CharUtils.isAsciiAlphaUpper('A')  = true
 470  
      *   CharUtils.isAsciiAlphaUpper('3')  = false
 471  
      *   CharUtils.isAsciiAlphaUpper('-')  = false
 472  
      *   CharUtils.isAsciiAlphaUpper('\n') = false
 473  
      *   CharUtils.isAsciiAlphaUpper('&copy;') = false
 474  
      * </pre>
 475  
      * 
 476  
      * @param ch  the character to check
 477  
      * @return true if between 65 and 90 inclusive
 478  
      */
 479  
     public static boolean isAsciiAlphaUpper(final char ch) {
 480  606
         return ch >= 'A' && ch <= 'Z';
 481  
     }
 482  
     
 483  
     /**
 484  
      * <p>Checks whether the character is ASCII 7 bit alphabetic lower case.</p>
 485  
      *
 486  
      * <pre>
 487  
      *   CharUtils.isAsciiAlphaLower('a')  = true
 488  
      *   CharUtils.isAsciiAlphaLower('A')  = false
 489  
      *   CharUtils.isAsciiAlphaLower('3')  = false
 490  
      *   CharUtils.isAsciiAlphaLower('-')  = false
 491  
      *   CharUtils.isAsciiAlphaLower('\n') = false
 492  
      *   CharUtils.isAsciiAlphaLower('&copy;') = false
 493  
      * </pre>
 494  
      * 
 495  
      * @param ch  the character to check
 496  
      * @return true if between 97 and 122 inclusive
 497  
      */
 498  
     public static boolean isAsciiAlphaLower(final char ch) {
 499  552
         return ch >= 'a' && ch <= 'z';
 500  
     }
 501  
     
 502  
     /**
 503  
      * <p>Checks whether the character is ASCII 7 bit numeric.</p>
 504  
      *
 505  
      * <pre>
 506  
      *   CharUtils.isAsciiNumeric('a')  = false
 507  
      *   CharUtils.isAsciiNumeric('A')  = false
 508  
      *   CharUtils.isAsciiNumeric('3')  = true
 509  
      *   CharUtils.isAsciiNumeric('-')  = false
 510  
      *   CharUtils.isAsciiNumeric('\n') = false
 511  
      *   CharUtils.isAsciiNumeric('&copy;') = false
 512  
      * </pre>
 513  
      * 
 514  
      * @param ch  the character to check
 515  
      * @return true if between 48 and 57 inclusive
 516  
      */
 517  
     public static boolean isAsciiNumeric(final char ch) {
 518  370
         return ch >= '0' && ch <= '9';
 519  
     }
 520  
     
 521  
     /**
 522  
      * <p>Checks whether the character is ASCII 7 bit numeric.</p>
 523  
      *
 524  
      * <pre>
 525  
      *   CharUtils.isAsciiAlphanumeric('a')  = true
 526  
      *   CharUtils.isAsciiAlphanumeric('A')  = true
 527  
      *   CharUtils.isAsciiAlphanumeric('3')  = true
 528  
      *   CharUtils.isAsciiAlphanumeric('-')  = false
 529  
      *   CharUtils.isAsciiAlphanumeric('\n') = false
 530  
      *   CharUtils.isAsciiAlphanumeric('&copy;') = false
 531  
      * </pre>
 532  
      * 
 533  
      * @param ch  the character to check
 534  
      * @return true if between 48 and 57 or 65 and 90 or 97 and 122 inclusive
 535  
      */
 536  
     public static boolean isAsciiAlphanumeric(final char ch) {
 537  202
         return isAsciiAlpha(ch) || isAsciiNumeric(ch);
 538  
     }
 539  
 
 540  
     /**
 541  
      * <p>Compares two {@code char} values numerically. This is the same functionality as provided in Java 7.</p>
 542  
      *
 543  
      * @param x the first {@code char} to compare
 544  
      * @param y the second {@code char} to compare
 545  
      * @return the value {@code 0} if {@code x == y};
 546  
      *         a value less than {@code 0} if {@code x < y}; and
 547  
      *         a value greater than {@code 0} if {@code x > y}
 548  
      * @since 3.4
 549  
      */
 550  
     public static int compare(char x, char y) {
 551  7
         return x-y;
 552  
     }
 553  
 }