commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject cvs commit: jakarta-commons/lang/src/java/org/apache/commons/lang StringUtils.java
Date Mon, 14 Jul 2003 22:26:51 GMT
scolebourne    2003/07/14 15:26:51

  Modified:    lang/src/java/org/apache/commons/lang StringUtils.java
  Log:
  Add and rework isEmpty, isNotEmpty, isEmptyTrimmed, isNotEmptyTrimmed
  Javadoc methods, adding example code
  
  Revision  Changes    Path
  1.54      +224 -67   jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java
  
  Index: StringUtils.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/lang/src/java/org/apache/commons/lang/StringUtils.java,v
  retrieving revision 1.53
  retrieving revision 1.54
  diff -u -r1.53 -r1.54
  --- StringUtils.java	9 Jul 2003 23:54:16 -0000	1.53
  +++ StringUtils.java	14 Jul 2003 22:26:51 -0000	1.54
  @@ -131,8 +131,8 @@
        * </pre>
        *
        * @see java.lang.String#trim()
  -     * @param str the String to check
  -     * @return the trimmed text (never <code>null</code>)
  +     * @param str  the String to clean, may be null
  +     * @return the trimmed text, never <code>null</code>
        * @deprecated Use the clearer named {@link #trimToEmpty(String)}.
        *             Method will be removed in Commons Lang 3.0.
        */
  @@ -156,8 +156,9 @@
        * </pre>
        *
        * @see java.lang.String#trim()
  -     * @param str the String to be trimmed
  -     * @return the trimmed text (or <code>null</code>)
  +     * @param str  the String to be trimmed, may be null
  +     * @return the trimmed text, 
  +     *  <code>null</code> if a null string input
        */
       public static String trim(String str) {
           return (str == null ? null : str.trim());
  @@ -179,8 +180,9 @@
        * </pre>
        *  
        * @see java.lang.String#trim()
  -     * @param str the String to be trimmed.
  -     * @return the trimmed string, or null if it's empty or null
  +     * @param str  the String to be trimmed, may be null
  +     * @return the trimmed string, 
  +     *  <code>null</code> if a whitespace, empty or null string input
        */
       public static String trimToNull(String str) {
           String ts = trim(str);
  @@ -189,8 +191,8 @@
   
       /** 
        * <p>Removes control characters, including whitespace, from both 
  -     * ends of this string returning an empty string if the string is
  -     * empty after the trim or if it is <code>null</code>.
  +     * ends of this string returning an empty string ("") if the string
  +     * is empty after the trim or if it is <code>null</code>.
        * 
        * <p>The string is trimmed using {@link String#trim()}.</p>
        * 
  @@ -203,8 +205,8 @@
        * </pre>
        *  
        * @see java.lang.String#trim()
  -     * @param str the String to be trimmed
  -     * @return the trimmed string, or an empty string if it's empty or null
  +     * @param str  the String to be trimmed, may be null
  +     * @return the trimmed string, or an empty string if null input
        */
       public static String trimToEmpty(String str) {
           return (str == null ? "" : str.trim());
  @@ -216,11 +218,13 @@
        * <p>Spaces are defined as <code>{' ', '\t', '\r', '\n', '\b'}</code>
        * in line with the deprecated {@link Character#isSpace(char)}.</p>
        *
  -     * @param str String target to delete spaces from
  -     * @return the String without spaces
  -     * @throws NullPointerException
  +     * @param str  the String to delete spaces from, may be null
  +     * @return the String without spaces, <code>null</code> if null string
input
        */
       public static String deleteSpaces(String str) {
  +        if (str == null) {
  +            return null;
  +        }
           return CharSetUtils.delete(str, " \t\r\n\b");
       }
   
  @@ -230,43 +234,106 @@
        * <p>Whitespace is defined by
        * {@link Character#isWhitespace(char)}.</p>
        *
  -     * @param str String target to delete whitespace from
  -     * @return the String without whitespaces
  -     * @throws NullPointerException
  +     * @param str  the String to delete whitespace from, may be null
  +     * @return the String without whitespaces, <code>null</code> if null string
input
        */
       public static String deleteWhitespace(String str) {
  +        if (str == null) {
  +            return null;
  +        }
           StringBuffer buffer = new StringBuffer();
           int sz = str.length();
  -        for (int i=0; i<sz; i++) {
  -            if(!Character.isWhitespace(str.charAt(i))) {
  +        for (int i = 0; i < sz; i++) {
  +            if (!Character.isWhitespace(str.charAt(i))) {
                   buffer.append(str.charAt(i));
               }
           }
           return buffer.toString();
       }
   
  +    // Empty checks
  +    //--------------------------------------------------------------------------
  +
  +    /**
  +     * <p>Checks if a String is <code>null</code> or empty ("").</p>
  +     * 
  +     * <pre>
  +     * StringUtils.isEmpty(null)      = true
  +     * StringUtils.isEmpty("")        = true
  +     * StringUtils.isEmpty(" ")       = false
  +     * StringUtils.isEmpty("bob")     = false
  +     * StringUtils.isEmpty("  bob  ") = false
  +     * </pre>
  +     *
  +     * <p>NOTE: This method changed in version 2.0.
  +     * It no longer trims the String.
  +     * That functionality is available in isEmptyTrimmed().</p>
  +     * 
  +     * @param str  the String to check, may be null
  +     * @return <code>true</code> if the String is <code>null</code>
or empty
  +     */
  +    public static boolean isEmpty(String str) {
  +        return (str == null || str.length() == 0);
  +    }
  +
       /**
  -     * <p>Checks if a String is non <code>null</code> and is
  -     * not empty (<code>length > 0</code>).</p>
  +     * <p>Checks if a String is not <code>null</code> and not empty ("").</p>
  +     * 
  +     * <pre>
  +     * StringUtils.isNotEmpty(null)      = false
  +     * StringUtils.isNotEmpty("")        = false
  +     * StringUtils.isNotEmpty(" ")       = true
  +     * StringUtils.isNotEmpty("bob")     = true
  +     * StringUtils.isNotEmpty("  bob  ") = true
  +     * </pre>
        *
  -     * @param str the String to check
  -     * @return true if the String is non-null, and not length zero
  +     * @param str  the String to check, may be null
  +     * @return <code>true</code> if the String is not <code>null</code>
and not empty
        */
       public static boolean isNotEmpty(String str) {
           return (str != null && str.length() > 0);
       }
   
       /**
  -     * <p>Checks if a (trimmed) String is <code>null</code> or empty.</p>
  +     * <p>Checks if a trimmed String is <code>null</code> or empty ("").</p>
        *
  -     * @param str the String to check
  -     * @return <code>true</code> if the String is <code>null</code>,
or
  -     *  length zero once trimmed
  +     * <pre>
  +     * StringUtils.isNotEmpty(null)      = true
  +     * StringUtils.isNotEmpty("")        = true
  +     * StringUtils.isNotEmpty(" ")       = true
  +     * StringUtils.isNotEmpty("bob")     = false
  +     * StringUtils.isNotEmpty("  bob  ") = false
  +     * </pre>
  +     *
  +     * @see java.lang.String#trim()
  +     * @param str  the String to check, may be null
  +     * @return <code>true</code> if the String is <code>null</code>
  +     *  or empty after trim()
        */
  -    public static boolean isEmpty(String str) {
  +    public static boolean isEmptyTrimmed(String str) {
           return (str == null || str.trim().length() == 0);
       }
   
  +    /**
  +     * <p>Checks if a trimmed String is not <code>null</code> and not
empty ("").</p>
  +     *
  +     * <pre>
  +     * StringUtils.isNotEmpty(null)      = false
  +     * StringUtils.isNotEmpty("")        = false
  +     * StringUtils.isNotEmpty(" ")       = false
  +     * StringUtils.isNotEmpty("bob")     = true
  +     * StringUtils.isNotEmpty("  bob  ") = true
  +     * </pre>
  +     *
  +     * @see java.lang.String#trim()
  +     * @param str  the String to check, may be null
  +     * @return <code>true</code> if the String is not <code>null</code>
  +     *  and not empty after trim()
  +     */
  +    public static boolean isNotEmptyTrimmed(String str) {
  +        return (str != null && str.trim().length() > 0);
  +    }
  +
       // Equals and IndexOf
       //--------------------------------------------------------------------------
   
  @@ -276,9 +343,17 @@
        * <p><code>null</code>s are handled without exceptions. Two <code>null</code>
        * references are considered to be equal. The comparison is case sensitive.</p>
        *
  +     * <pre>
  +     * StringUtils.equals(null, null)   = true
  +     * StringUtils.equals(null, "abc")  = false
  +     * StringUtils.equals("abc", null)  = false
  +     * StringUtils.equals("abc", "abc") = true
  +     * StringUtils.equals("abc", "ABC") = false
  +     * </pre>
  +     *  
        * @see java.lang.String#equals(Object)
  -     * @param str1 the first string
  -     * @param str2 the second string
  +     * @param str1  the first string, may be null
  +     * @param str2  the second string, may be null
        * @return <code>true</code> if the Strings are equal, case sensitive,
or
        *  both <code>null</code>
        */
  @@ -293,9 +368,17 @@
        * <p><code>Nulls</code> are handled without exceptions. Two <code>null</code>
        * references are considered equal. Comparison is case insensitive.</p>
        *
  +     * <pre>
  +     * StringUtils.equalsIgnoreCase(null, null)   = true
  +     * StringUtils.equalsIgnoreCase(null, "abc")  = false
  +     * StringUtils.equalsIgnoreCase("abc", null)  = false
  +     * StringUtils.equalsIgnoreCase("abc", "abc") = true
  +     * StringUtils.equalsIgnoreCase("abc", "ABC") = true
  +     * </pre>
  +     * 
        * @see java.lang.String#equalsIgnoreCase(String)
  -     * @param str1  the first string
  -     * @param str2  the second string
  +     * @param str1  the first string, may be null
  +     * @param str2  the second string, may be null
        * @return <code>true</code> if the Strings are equal, case insensitive,
or
        *  both <code>null</code>
        */
  @@ -308,9 +391,9 @@
        *
        * <p><code>null</code> String will return <code>-1</code>.</p>
        * 
  -     * @param str the String to check
  -     * @param searchStrs the Strings to search for
  -     * @return the first index of any of the searchStrs in str
  +     * @param str  the String to check, may be null
  +     * @param searchStrs  the Strings to search for, may be null
  +     * @return the first index of any of the searchStrs in str, -1 if no match
        * @throws NullPointerException if any of searchStrs[i] is <code>null</code>
        */
       public static int indexOfAny(String str, String[] searchStrs) {
  @@ -342,9 +425,9 @@
        *
        * <p><code>null</code> string will return <code>-1</code>.</p>
        * 
  -     * @param str  the String to check
  -     * @param searchStrs  the Strings to search for
  -     * @return the last index of any of the Strings
  +     * @param str  the String to check, may be null
  +     * @param searchStrs  the Strings to search for, may be null
  +     * @return the last index of any of the Strings, -1 if no match
        * @throws NullPointerException if any of searchStrs[i] is <code>null</code>
        */
       public static int lastIndexOfAny(String str, String[] searchStrs) {
  @@ -372,10 +455,19 @@
        * <p>A negative start position can be used to start <code>n</code>
        * characters from the end of the String.</p>
        * 
  -     * @param str the String to get the substring from
  -     * @param start the position to start from, negative means
  +     * <pre>
  +     * StringUtils.substring(null, 0)   = null
  +     * StringUtils.substring("abc", 0)  = "abc"
  +     * StringUtils.substring("abc", 2)  = "c"
  +     * StringUtils.substring("abc", 4)  = ""
  +     * StringUtils.substring("abc", -2) = "bc"
  +     * StringUtils.substring("abc", -4) = "abc"
  +     * </pre>
  +     * 
  +     * @param str  the String to get the substring from, may be null
  +     * @param start  the position to start from, negative means
        *  count back from the end of the String by this many characters
  -     * @return substring from start position
  +     * @return substring from start position, <code>null</code> if null string
input
        */
       public static String substring(String str, int start) {
           if (str == null) {
  @@ -403,12 +495,22 @@
        * <p>A negative start position can be used to start/end <code>n</code>
        * characters from the end of the String.</p>
        * 
  -     * @param str the String to get the substring from
  -     * @param start the position to start from, negative means
  +     * <pre>
  +     * StringUtils.substring(null, 0, 2)    = null
  +     * StringUtils.substring("abc", 0, 2)   = "ab"
  +     * StringUtils.substring("abc", 2, 0)   = ""
  +     * StringUtils.substring("abc", 2, 4)   = "c"
  +     * StringUtils.substring("abc", 4, 6)   = ""
  +     * StringUtils.substring("abc", -2, -1) = "b"
  +     * StringUtils.substring("abc", -4, 2)  = "ab"
  +     * </pre>
  +     * 
  +     * @param str  the String to get the substring from, may be null
  +     * @param start  the position to start from, negative means
        *  count back from the end of the string by this many characters
  -     * @param end the position to end at (exclusive), negative means
  +     * @param end  the position to end at (exclusive), negative means
        *  count back from the end of the String by this many characters
  -     * @return substring from start position to end positon
  +     * @return substring from start position to end positon, <code>null</code>
if null string input
        */
       public static String substring(String str, int start, int end) {
           if (str == null) {
  @@ -451,9 +553,17 @@
        * String is <code>null</code>, the String will be returned without
        * an exception.</p>
        *
  -     * @param str the String to get the leftmost characters from
  -     * @param len the length of the required String
  -     * @return the leftmost characters
  +     * <pre>
  +     * StringUtils.left(null, 0)    = null
  +     * StringUtils.left("abc", 0)   = ""
  +     * StringUtils.left("abc", 2)   = "ab"
  +     * StringUtils.left("abc", 4)   = "abc"
  +     * StringUtils.left("abc", -2)  = IllegalArgumentException
  +     * </pre>
  +     * 
  +     * @param str  the String to get the leftmost characters from, may be null
  +     * @param len  the length of the required String, must be zero or positive
  +     * @return the leftmost characters, <code>null</code> if null string input
        * @throws IllegalArgumentException if len is less than zero
        */
       public static String left(String str, int len) {
  @@ -474,9 +584,17 @@
        * is <code>null</code>, the String will be returned without an
        * exception.</p>
        *
  -     * @param str the String to get the rightmost characters from
  -     * @param len the length of the required String
  -     * @return the leftmost characters
  +     * <pre>
  +     * StringUtils.right(null, 0)    = null
  +     * StringUtils.right("abc", 0)   = ""
  +     * StringUtils.right("abc", 2)   = "bc"
  +     * StringUtils.right("abc", 4)   = "abc"
  +     * StringUtils.right("abc", -2)  = IllegalArgumentException
  +     * </pre>
  +     * 
  +     * @param str  the String to get the rightmost characters from, may be null
  +     * @param len  the length of the required String, must be zero or positive
  +     * @return the rightmost characters, <code>null</code> if null string input
        * @throws IllegalArgumentException if len is less than zero
        */
       public static String right(String str, int len) {
  @@ -497,10 +615,20 @@
        * of the String will be returned without an exception. If the
        * String is <code>null</code>, <code>null</code> will be returned.</p>
        *
  -     * @param str the String to get the characters from
  -     * @param pos the position to start from
  -     * @param len the length of the required String
  -     * @return the leftmost characters
  +     * <pre>
  +     * StringUtils.mid(null, 0, 0)    = null
  +     * StringUtils.mid("abc", 0, 2)   = "ab"
  +     * StringUtils.mid("abc", 0, 4)   = "abc"
  +     * StringUtils.mid("abc", 2, 4)   = "c"
  +     * StringUtils.mid("abc", 4, 2)   = StringIndexOutOfBoundsException
  +     * StringUtils.mid("abc", -2, -2) = StringIndexOutOfBoundsException
  +     * StringUtils.mid("abc", 0, -2)  = IllegalArgumentException
  +     * </pre>
  +     * 
  +     * @param str  the String to get the characters from, may be null
  +     * @param pos  the position to start from, must be valid
  +     * @param len  the length of the required String, must be zero or positive
  +     * @return the middle characters, <code>null</code> if null string input
        * @throws IndexOutOfBoundsException if pos is out of bounds
        * @throws IllegalArgumentException if len is less than zero
        */
  @@ -526,23 +654,42 @@
       //--------------------------------------------------------------------------
       
       /**
  -     * <p>Splits the provided text into a array, using whitespace as the
  +     * <p>Splits the provided text into an array, using whitespace as the
        * separator.</p>
        *
        * <p>The separator is not included in the returned String array.</p>
        *
  -     * @param str the String to parse
  -     * @return an array of parsed Strings 
  +     * <pre>
  +     * StringUtils.split(null)      = []
  +     * StringUtils.split("abc def") = [abc, def]
  +     * </pre>
  +     * 
  +     * @param str  the String to parse, may be null
  +     * @return an array of parsed Strings, empty array if null input
        */
       public static String[] split(String str) {
           return split(str, null, -1);
       }
   
       /**
  -     * @see #split(String, String, int)
  +     * <p>Splits the provided text into an array, using the specified separators.</p>
  +     *
  +     * <p>The separator is not included in the returned String array.</p>
  +     *
  +     * <pre>
  +     * StringUtils.split(null, null)      = []
  +     * StringUtils.split("abc def", null) = [abc, def]
  +     * StringUtils.split("abc def", " ")  = [abc, def]
  +     * StringUtils.split("ab:cd:ef", ":") = [ab, cd, ef]
  +     * </pre>
  +     * 
  +     * @param str  the String to parse, may be null
  +     * @param separators  the characters used as the delimiters,
  +     *  <code>null</code> splits on whitespace
  +     * @return an array of parsed Strings, empty array if null input
        */
  -    public static String[] split(String text, String separator) {
  -        return split(text, separator, -1);
  +    public static String[] split(String str, String separators) {
  +        return split(str, separators, -1);
       }
   
       /**
  @@ -556,14 +703,24 @@
        * an array of tokens, instead of an enumeration of tokens (as
        * <code>StringTokenizer</code> does).</p>
        *
  -     * @param str The string to parse.
  -     * @param separator Characters used as the delimiters. If
  -     *  <code>null</code>, splits on whitespace.
  -     * @param max The maximum number of elements to include in the
  -     *  array.  A zero or negative value implies no limit.
  -     * @return an array of parsed Strings 
  +     * <pre>
  +     * StringUtils.split(null, null, 0)       = []
  +     * StringUtils.split("ab de fg", null, 0) = [ab, cd, ef]
  +     * StringUtils.split("ab:cd:ef", ":", 0)  = [ab, cd, ef]
  +     * StringUtils.split("ab:cd:ef", ":", 2)  = [ab, cdef]
  +     * </pre>
  +     * 
  +     * @param str  the string to parse, may be null
  +     * @param separators  the characters used as the delimiters,
  +     *  <code>null</code> splits on whitespace
  +     * @param max  the maximum number of elements to include in the
  +     *  array. A zero or negative value implies no limit.
  +     * @return an array of parsed Strings, empty array if null input
        */
       public static String[] split(String str, String separator, int max) {
  +        if (str == null) {
  +            return ArrayUtils.EMPTY_STRING_ARRAY;
  +        }
           StringTokenizer tok = null;
           if (separator == null) {
               // Null separator means we're using StringTokenizer's default
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message