ProgramixGenericLib v5.0.1

com.programix.util
Class StringTools

java.lang.Object
  extended by com.programix.util.StringTools

public class StringTools
extends Object

All sorts of tools for working with Strings.

Author:
Paul Hyde

Field Summary
static Comparator<String> NULL_FIRST_CASE_INSENSITIVE_ASC
          This Comparator sorts String's in case-insensitive ordering, but with any null's that may be present sorted to the top.
static Comparator<String> NULL_FIRST_CASE_INSENSITIVE_DESC
          This Comparator sorts String's in reverse case-insensitive ordering, but with any null's that may be present sorted to the top.
static Comparator<String> NULL_FIRST_CASE_SENSITIVE_ASC
          This Comparator sorts String's in their normal case-sensitive ordering, but with any null's that may be present sorted to the top.
static Comparator<String> NULL_FIRST_CASE_SENSITIVE_DESC
          This Comparator sorts String's in reverse case-sensitive ordering, but with any null's that may be present sorted to the top.
static Comparator<String> NULL_LAST_CASE_INSENSITIVE_ASC
          This Comparator sorts String's in case-insensitive ordering, but with any null's that may be present sorted to the bottom.
static Comparator<String> NULL_LAST_CASE_INSENSITIVE_DESC
          This Comparator sorts String's in reverse case-insensitive ordering, but with any null's that may be present sorted to the bottom.
static Comparator<String> NULL_LAST_CASE_SENSITIVE_ASC
          This Comparator sorts String's in their normal case-sensitive ordering, but with any null's that may be present sorted to the bottom.
static Comparator<String> NULL_LAST_CASE_SENSITIVE_DESC
          This Comparator sorts String's in reverse case-sensitive ordering, but with any null's that may be present sorted to the bottom.
static String[] ZERO_LEN_ARRAY
          An array of String with a zero-slots in the array.
static String ZERO_LEN_STRING
          A zero-length String, that is: "".
 
Method Summary
static String blankToNull(String str)
          Returns null if the passed String is null or has a length of 0.
static int compare(String s1, String s2)
          Like String's compareTo, but null is considered "less than" any other string except null.
static String filter(String source, String validChar)
          Deprecated. Use winnow(String, String) instead.
static String formatCommaDelimited(String... itemList)
          Takes the passed strings and formats them into a comma and space delimited string.
static String hash(String plainText)
          Does an MD5 hash on the source text, then converts the 16 bytes to hex.
static boolean isDifferent(String a, String b)
          Compares two strings to see if they are "different".
static boolean isDifferentIgnoreCase(String a, String b)
          Compares two strings to see if they are "different" (other than any case differences).
static boolean isEmpty(Object obj)
          Returns true if obj is null, a zero-length string, or if its toString() method returns a String that trims down to a zero-length string.
static boolean isEmpty(String str)
          Returns true if str is null, a zero-length string, or trims down to a zero-length string.
static boolean isEmpty(String[] strList)
          Returns true if the passed strList is null, is a zero-length array, or if every String in the array is "empty" (as defined by isEmpty(String).
static boolean isEmptyTrimmed(Object obj)
          Deprecated. Use isEmpty(Object) instead.
static boolean isEmptyTrimmed(String str)
          Deprecated. Use isEmpty(String) instead.
static boolean isEmptyWithoutTrim(Object obj)
          Returns true if obj is null or if its toString() method returns a zero-length string.
static boolean isEmptyWithoutTrim(String str)
          Returns true if str is null or if it is a zero-length string.
static boolean isNotEmpty(Object obj)
          Returns true if obj is not null and its toString() methods returns a String that has at least 1 character left after trimming.
static boolean isNotEmpty(String str)
          Returns true if str is not null and points to a String that has at least 1 character left after trimming.
static boolean isNotEmpty(String[] strList)
          Returns false if the passed strList is null, is a zero-length array, or if every String in the array is "empty" (as defined by isEmpty(String).
static boolean isNotEmptyTrimmed(Object obj)
          Deprecated. Use isNotEmpty(Object) instead.
static boolean isNotEmptyTrimmed(String str)
          Deprecated. Use isNotEmpty(String) instead.
static boolean isNotEmptyWithoutTrim(Object obj)
          Returns true if obj is not null and its toString() method returns a String with a length of at least 1 character.
static boolean isNotEmptyWithoutTrim(String str)
          Returns true if str is not null and points to a String with a length of at least 1 character.
static boolean isSame(String a, String b)
          Compares two strings to see if they are "the same".
static boolean isSameIgnoreCase(String a, String b)
          Compares two strings to see if they are "the same" (ignoring any case differences).
static String nullToBlank(Object obj)
          If the supplied obj is null, a zero-length string is returned instead (ZERO_LEN_STRING).
static String nullToBlank(String str)
          If the supplied String is null, a zero-length string is returned instead (ZERO_LEN_STRING).
static String padClip(String str, int resultingLength)
          Pads or clips str so the the String returned is exactly resultingLength long.
static String paramEmptyCheck(String param)
          Used as a helper to check passed parameters for prohibited "empty" values in other methods.
static String paramEmptyCheck(String param, String paramName)
          Used as a helper to check passed parameters for prohibited "empty" values in other methods.
static byte[] parseHexString(String srcStr)
          Converts the string of hex digits into an array of bytes.
static String quoteWrap(Object source)
          Returns the toString() version of the source Object wrapped with double-quotes.
static String quoteWrap(String source)
          Returns the source String wrapped with double-quotes.
static String[] sortUnique(String[] source)
          Returns a sorted copy of the original list of strings.
static String[] split(String source, char delimiter)
          Splits up the specified source into multiple String's based on the specified delimiter.
static String[] split(String source, String delimiter)
          Splits up the specified source into multiple String's based on the specified delimiter.
static String[] stackTraceToStringArray(Throwable t)
          Performs a stack trace on the passed Throwable and returns each line as an element in the array.
static String[] toArray(Collection<String> strings)
          Takes the passed Collection of String's and returns a snapshot of it as a String[].
static String toHexString(byte[] data)
          Converts the passed byte[] into a string.
static char[] toSortedCharArray(char[] source)
          Returns a new char[] sorted in Unicode order representing all of the characters in the source char[].
static char[] toSortedCharArray(String source)
          Returns a char[] sorted in Unicode order representing all of the characters in the source String.
static String trim(Object obj)
          Trims the String returned by the toString() method on obj, or if obj is null, returns a zero-length string instead of null.
static String trim(String str)
          Trims the supplied string, or if null, returns a zero-length string instead of null.
static String trimToNull(Object obj)
          Trims the String returned by the toString() method on obj.
static String trimToNull(String str)
          Trims the passed string and returns null if the resulting string has a length of 0.
static String winnow(String source, char[] sortedValidChar)
          Winnows out invalid characters from the source String keeping only the characters specified in sortedValidChar.
static String winnow(String source, String validChar)
          Winnows the source String keeping only the characters specified in validChar.
static String winnowAlpha(String source)
          Winnows the source String keeping only the English alphabet characters (A-Z, a-z).
static String winnowAlphaNumeric(String source)
          Winnows the source String keeping only the alphanumeric characters (A-Z, a-z, 0-9).
static String winnowDecimal(String source)
          Winnows the passed String keeping only the characters that make up the string version of a decimal number.
static String winnowDigit(String source)
          Winnows the source String keeping only the digit characters (0-9).
static String winnowHexDigit(String source)
          Winnows the source String keeping only the hexadecimal digit characters (0-9, A-F, a-f).
static String winnowInteger(String source)
          Winnows the passed String keeping only the characters that make up the string version of an integer number.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ZERO_LEN_STRING

public static final String ZERO_LEN_STRING
A zero-length String, that is: "". Many of the methods on StringTools may return a reference to this exact instance as there is really no need for more than one zero-length string per VM (String is immutable after all). Use of this constant can also help improve code readability.

See Also:
Constant Field Values

ZERO_LEN_ARRAY

public static final String[] ZERO_LEN_ARRAY
An array of String with a zero-slots in the array.


NULL_FIRST_CASE_SENSITIVE_ASC

public static final Comparator<String> NULL_FIRST_CASE_SENSITIVE_ASC
This Comparator sorts String's in their normal case-sensitive ordering, but with any null's that may be present sorted to the top.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_FIRST_CASE_SENSITIVE_DESC

public static final Comparator<String> NULL_FIRST_CASE_SENSITIVE_DESC
This Comparator sorts String's in reverse case-sensitive ordering, but with any null's that may be present sorted to the top.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_FIRST_CASE_INSENSITIVE_ASC

public static final Comparator<String> NULL_FIRST_CASE_INSENSITIVE_ASC
This Comparator sorts String's in case-insensitive ordering, but with any null's that may be present sorted to the top.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_FIRST_CASE_INSENSITIVE_DESC

public static final Comparator<String> NULL_FIRST_CASE_INSENSITIVE_DESC
This Comparator sorts String's in reverse case-insensitive ordering, but with any null's that may be present sorted to the top.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_LAST_CASE_SENSITIVE_ASC

public static final Comparator<String> NULL_LAST_CASE_SENSITIVE_ASC
This Comparator sorts String's in their normal case-sensitive ordering, but with any null's that may be present sorted to the bottom.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_LAST_CASE_SENSITIVE_DESC

public static final Comparator<String> NULL_LAST_CASE_SENSITIVE_DESC
This Comparator sorts String's in reverse case-sensitive ordering, but with any null's that may be present sorted to the bottom.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_LAST_CASE_INSENSITIVE_ASC

public static final Comparator<String> NULL_LAST_CASE_INSENSITIVE_ASC
This Comparator sorts String's in case-insensitive ordering, but with any null's that may be present sorted to the bottom.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator

NULL_LAST_CASE_INSENSITIVE_DESC

public static final Comparator<String> NULL_LAST_CASE_INSENSITIVE_DESC
This Comparator sorts String's in reverse case-insensitive ordering, but with any null's that may be present sorted to the bottom.

See Also:
NullFirstComparator, NullLastComparator, ReverseComparator, ComparableComparator
Method Detail

isEmpty

public static boolean isEmpty(String str)
Returns true if str is null, a zero-length string, or trims down to a zero-length string. Equivalent to:
 return (str == null) ||
        (str.length() == 0) ||
        (str.trim().length() == 0);
 


isNotEmpty

public static boolean isNotEmpty(String str)
Returns true if str is not null and points to a String that has at least 1 character left after trimming. Equivalent to: !isEmpty(str)).


isEmpty

public static boolean isEmpty(Object obj)
Returns true if obj is null, a zero-length string, or if its toString() method returns a String that trims down to a zero-length string. Equivalent to (except that toString() is not really called twice):
 return (obj == null) ||
        (obj.toString().length() == 0) ||
        (obj.toString().trim().length() == 0);
 


isNotEmpty

public static boolean isNotEmpty(Object obj)
Returns true if obj is not null and its toString() methods returns a String that has at least 1 character left after trimming. Equivalent to: !isEmpty(obj)).


isEmptyTrimmed

public static boolean isEmptyTrimmed(String str)
Deprecated. Use isEmpty(String) instead.


isNotEmptyTrimmed

public static boolean isNotEmptyTrimmed(String str)
Deprecated. Use isNotEmpty(String) instead.


isEmptyTrimmed

public static boolean isEmptyTrimmed(Object obj)
Deprecated. Use isEmpty(Object) instead.


isNotEmptyTrimmed

public static boolean isNotEmptyTrimmed(Object obj)
Deprecated. Use isNotEmpty(Object) instead.


isEmptyWithoutTrim

public static boolean isEmptyWithoutTrim(String str)
Returns true if str is null or if it is a zero-length string. No trimming of whitespace is done.


isNotEmptyWithoutTrim

public static boolean isNotEmptyWithoutTrim(String str)
Returns true if str is not null and points to a String with a length of at least 1 character. No trimming of whitespace is done. Equivalent to: !isEmptyWithoutTrim(str).


isEmptyWithoutTrim

public static boolean isEmptyWithoutTrim(Object obj)
Returns true if obj is null or if its toString() method returns a zero-length string. No trimming of whitespace is done.


isNotEmptyWithoutTrim

public static boolean isNotEmptyWithoutTrim(Object obj)
Returns true if obj is not null and its toString() method returns a String with a length of at least 1 character. No trimming of whitespace is done. Equivalent to: !isEmptyWithoutTrim(obj).


isEmpty

public static boolean isEmpty(String[] strList)
Returns true if the passed strList is null, is a zero-length array, or if every String in the array is "empty" (as defined by isEmpty(String).


isNotEmpty

public static boolean isNotEmpty(String[] strList)
Returns false if the passed strList is null, is a zero-length array, or if every String in the array is "empty" (as defined by isEmpty(String).

Equivalent to:

 return !isEmpty(strList);
 


trim

public static String trim(String str)
Trims the supplied string, or if null, returns a zero-length string instead of null. Returned value is never null. When the return value would be a zero-length string, a reference to ZERO_LEN_STRING is returned to help reduce the number of zero-length strings floating around the VM.


trim

public static String trim(Object obj)
Trims the String returned by the toString() method on obj, or if obj is null, returns a zero-length string instead of null. Returned value is never null. When the return value would be a zero-length string, a reference to ZERO_LEN_STRING is returned to help reduce the number of zero-length strings floating around the VM.


trimToNull

public static String trimToNull(String str)
Trims the passed string and returns null if the resulting string has a length of 0. Returns null if the source string is null. If the trimmed string has a length greater than 0, then the trimmed string is returned.

See Also:
blankToNull(java.lang.String)

trimToNull

public static String trimToNull(Object obj)
Trims the String returned by the toString() method on obj. If obj is null, a null is returned. null. If the trimmed String has a length of zero, a null is returned. Returned value is never zero-length String.


nullToBlank

public static String nullToBlank(String str)
If the supplied String is null, a zero-length string is returned instead (ZERO_LEN_STRING). If not null, the string itself is returned unmodified.


nullToBlank

public static String nullToBlank(Object obj)
If the supplied obj is null, a zero-length string is returned instead (ZERO_LEN_STRING). If not null, the toString() method is invoked on obj and that String is returned.


blankToNull

public static String blankToNull(String str)
Returns null if the passed String is null or has a length of 0. Otherwise, the original string is returned unchanged.

See Also:
trimToNull(java.lang.String)

padClip

public static String padClip(String str,
                             int resultingLength)
Pads or clips str so the the String returned is exactly resultingLength long. If padding is necessary, spaces are added to the end. If null is passed in, it is accepted and treated as a zero-length string.


toArray

public static String[] toArray(Collection<String> strings)
Takes the passed Collection of String's and returns a snapshot of it as a String[].


isSame

public static boolean isSame(String a,
                             String b)
Compares two strings to see if they are "the same". Returns true if a is the same as b. Specifically, they considered to be the same if any of the following are true:

Parameters:
a - the first String
b - the second String
Returns:
true if the strings are the same.
See Also:
isDifferent(String, String), isSameIgnoreCase(String, String), isDifferentIgnoreCase(String, String)

isDifferent

public static boolean isDifferent(String a,
                                  String b)
Compares two strings to see if they are "different". Returns true if a is different than b. Specifically, they considered to be different if any of the following are true:

Parameters:
a - the first String
b - the second String
Returns:
true if the strings are different.
See Also:
isSame(String, String), isSameIgnoreCase(String, String), isDifferentIgnoreCase(String, String)

isSameIgnoreCase

public static boolean isSameIgnoreCase(String a,
                                       String b)
Compares two strings to see if they are "the same" (ignoring any case differences). Returns true if a is the same as b (ignoreing case differences). Specifically, they considered to be the same if any of the following are true:

Parameters:
a - the first String
b - the second String
Returns:
true if the strings are the same (ignoring case differences).
See Also:
isDifferentIgnoreCase(String, String), isSame(String, String), isDifferent(String, String)

isDifferentIgnoreCase

public static boolean isDifferentIgnoreCase(String a,
                                            String b)
Compares two strings to see if they are "different" (other than any case differences). Returns true if a is different than b (other than any case differences). Specifically, they considered to be different if any of the following are true:

Parameters:
a - the first String
b - the second String
Returns:
true if the strings are different beyond any case differences.
See Also:
isSameIgnoreCase(String, String), isSame(String, String), isDifferent(String, String)

compare

public static int compare(String s1,
                          String s2)
Like String's compareTo, but null is considered "less than" any other string except null. If both are null, then 0 is returned. If both are NOT null, the result of s1.compareTo(s2) is returned.


hash

public static String hash(String plainText)
Does an MD5 hash on the source text, then converts the 16 bytes to hex. The result is always exactly 32 characters long.


toHexString

public static String toHexString(byte[] data)
Converts the passed byte[] into a string. The length of the returned String is always (2 * data.length) [leading zeros are preserved].

Parameters:
data - bytes to convert
Returns:
formatted hex string
See Also:
parseHexString(java.lang.String)

parseHexString

public static byte[] parseHexString(String srcStr)
Converts the string of hex digits into an array of bytes. This method always returns a byte[] (never returns null and never throws an exception regardless of how poorly the source string is formatted). All characters which are not hex digits are silently ignored (including leading and trailing whitespace—no need to pre-trim). If the number of hex digits found is an odd number, a leading 0 is automatically prefixed. NOTE: Do NOT include a leading 0x that you would include in Java source code.

Examples:

 "3bfe"                   byte[] length is 2
                          data[0] = 0x3B;
                          data[1] = 0xFE;
 ---------------------------------------------
 " 3 B F E "              byte[] length is 2
                          data[0] = 0x3B;
                          data[1] = 0xFE;
 ---------------------------------------------
 "0"                      byte[] length is 1
                          data[0] = 0x00;
 ---------------------------------------------
 "00"                     byte[] length is 1
                          data[0] = 0x00;
 ---------------------------------------------
 "1"                      byte[] length is 1
                          data[0] = 0x01;
 ---------------------------------------------
 "01"                     byte[] length is 1
                          data[0] = 0x01;
 ---------------------------------------------
 "001"                    byte[] length is 2
                          data[0] = 0x00;
                          data[1] = 0x01;
 ---------------------------------------------
 "777"                    byte[] length is 2
                          data[0] = 0x07;
                          data[1] = 0x77;
 ---------------------------------------------
 "Cafe Babe  "            byte[] length is 4
                          data[0] = 0xCA;
                          data[1] = 0xFE;
                          data[2] = 0xBA;
                          data[3] = 0xBE;
 ---------------------------------------------
 "   0123456789ABCDEF 0123456789abcdef  "
                  byte[] length is 16
    data[ 0] = 0x01;      data[ 8] = 0x01;
    data[ 1] = 0x23;      data[ 9] = 0x23;
    data[ 2] = 0x45;      data[10] = 0x45;
    data[ 3] = 0x67;      data[11] = 0x67;
    data[ 4] = 0x89;      data[12] = 0x89;
    data[ 5] = 0xAB;      data[13] = 0xAB;
    data[ 6] = 0xCD;      data[14] = 0xCD;
    data[ 7] = 0xEF;      data[15] = 0xEF;
 ---------------------------------------------
 null                     byte[] length is 0
 ---------------------------------------------
 ""                       byte[] length is 0
 ---------------------------------------------
 "   "                    byte[] length is 0
 ---------------------------------------------
 "  !@#$%^()-_+={}[]"     byte[] length is 0
 ---------------------------------------------
 " =!= 7 ** F # 2  "      byte[] length is 2
                          data[0] = 0x07;
                          data[1] = 0xF2;
 ---------------------------------------------
 

Parameters:
srcStr - string to parse (null is ok).
Returns:
parsed value. The number of bytes returned is always in the range of 0 to ((srcLen + 1) / 2). null is never returned. The actual number of bytes returned is based on the number of valid hex digits found.
See Also:
toHexString(byte[])

filter

public static String filter(String source,
                            String validChar)
Deprecated. Use winnow(String, String) instead.


winnow

public static String winnow(String source,
                            char[] sortedValidChar)
Winnows out invalid characters from the source String keeping only the characters specified in sortedValidChar. For this method to work correctly, it is critical that the char's to keep (which are supplied in sortedValidChar) are sorted in ascending Unicode order (as if run through Arrays.sort(char[]) or toSortedCharArray(char[])).

Example:

 char[] sortedValidChar = StringTools.toSortedCharArray("0246813579");
 String s1 = StringTools.winnow("763-555-1212", sortedValidChar);
 //              results in s1: "7635551212"
 String s2 = StringTools.winnow(" (763) 555  1212 ", sortedValidChar);
 //              results in s2: "7635551212"
 //
 // NOTE: For an easier way, see winnowDigit(String)!

Another Example:

 char[] validChar = StringTools.toSortedCharArray("fedcba");
 String s3 = StringTools.winnow("happy dad", validChar);
 //              results in s3: "adad"
 String s4 = StringTools.winnow("cat fell into big wall bell", validChar);
 //              results in s4: "cafebabe"

Parameters:
source - source string to process
sortedValidChar - any char in this sorted char[] is considered a keeper. If null or a zero-length array is passed in, a zero-length String is returned. This array must be sorted.
Returns:
the winnowed string. If all characters in source were valid, that same String instance is returned. If there were any characters in source that were not in sortedValidChar, then a new String is returned with those invalid characters stripped out. If either source or sortedValidChar is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.

winnow

public static String winnow(String source,
                            String validChar)
Winnows the source String keeping only the characters specified in validChar. If you already have the validChar String as a sorted char[], it is more efficient to call winnow(String, char[]) directly.

Parameters:
source - source string to process
validChar - any char in this string is considered a keeper.
Returns:
the filtered string. If all characters in source are valid, that same String instance is returned. If there were any characters in source that were not in validChar, then a new String is returned with those invalid characters stripped out. If either source or validChar is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.

winnowDigit

public static String winnowDigit(String source)
Winnows the source String keeping only the digit characters (0-9). There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming). Example:
 String s1 = StringTools.winnowDigit("763-555-1212");
 //                   results in s1: "7635551212"
 String s2 = StringTools.winnowDigit(" (763) 555  1212 ");
 //                   results in s2: "7635551212"

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are digits, that same String instance is returned. If there were any characters in source that were not digits, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.
See Also:
winnow(String, char[])

winnowHexDigit

public static String winnowHexDigit(String source)
Winnows the source String keeping only the hexadecimal digit characters (0-9, A-F, a-f). Note that both capital and lowercase letters are accepted and retained. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming). Example:
 String s1 = StringTools.winnowHexDigit("  3B20 CAFE  ");
 //                      results in s1: "3B20CAFE"
 String s2 = StringTools.winnowHexDigit("cat has 9 lives");
 //                      results in s2: "caa9e"

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are hex digits, that same String instance is returned. If there were any characters in source that were not hex digits, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.
See Also:
winnow(String, char[])

winnowAlpha

public static String winnowAlpha(String source)
Winnows the source String keeping only the English alphabet characters (A-Z, a-z). Note that both capital and lowercase letters are accepted and retained. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming). Example:
 String s1 = StringTools.winnowAplha("  4T fifty 6T  ");
 //                   results in s1: "TfiftyT"
 String s2 = StringTools.winnowAlpha("A983-22JK-TPL5-3WQH");
 //                   results in s2: "AJKTPLWQH"

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are alpha char, that same String instance is returned. If there were any characters in source that were not alpha char, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.
See Also:
winnow(String, char[])

winnowAlphaNumeric

public static String winnowAlphaNumeric(String source)
Winnows the source String keeping only the alphanumeric characters (A-Z, a-z, 0-9). Note that both capital and lowercase letters are accepted and retained. There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming). Example:
 String s1 = StringTools.winnowAplhaNumeric(" Today, 3; tomorrow, 4! ");
 //                          results in s1: "Today3tomorrow4"
 String s2 = StringTools.winnowAlphaNumeric("A983-22JK-TPL5-3WQH");
 //                          results in s2: "A98322JKTPL53WQH"

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are alphanumeric char, that same String instance is returned. If there were any characters in source that were not alphanumeric char, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null.
See Also:
winnow(String, char[])

winnowDecimal

public static String winnowDecimal(String source)
Winnows the passed String keeping only the characters that make up the string version of a decimal number. Processes the passed string by ignoring all characters not in the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ., -}.

The negative sign '-' is ignored if it is not the first valid character.

Only the first decimal point ('.') is kept, any additional decimal points are ignored.

Extra leading zeros (0) are removed. A leading zero is only kept if it immediately precedes a decimal point or is the only digit. A leading zero is a zero that appears to the left of the decimal point and if it appears before the other digits.

If zero digits are found, then a zero-length String is returned (even if a decimal point and/or a minus sign were found). There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

Examples:

 String s0 = StringTools.winnowDecimal("107.11170524");
 //                     results in s0: "107.11170524"
 String s1 = StringTools.winnowDecimal(" -3,591.103 ");
 //                     results in s1: "-3591.103"
 String s2 = StringTools.winnowDecimal(" abc-3,efg5h9i1j.k1l0m3n ");
 //                     results in s2: "-3591.103"
 String s3 = StringTools.winnowDecimal(" 4 - 3 = 1 "); // no math done!
 //                     results in s3: "431"
 String s4 = StringTools.winnowDecimal("  3,148,912.  ");
 //                     results in s4: "3148912."
 String s5 = StringTools.winnowDecimal(" -35-91.10.3 ");
 //                     results in s5: "-3591.103"
 String s6 = StringTools.winnowDecimal("-abc.def");
 //                     results in s6: ""
 String s7 = StringTools.winnowDecimal("-.");
 //                     results in s7: ""
 String s8 = StringTools.winnowDecimal("-");
 //                     results in s8: ""
 String s9 = StringTools.winnowDecimal(".");
 //                     results in s9: ""
 String s10 = StringTools.winnowDecimal("  abc def ghi ");
 //                     results in s10: ""
String s11 = StringTools.winnowDecimal(".45"); // results in s11: ".45" String s12 = StringTools.winnowDecimal("0.45"); // results in s12: "0.45" String s13 = StringTools.winnowDecimal("0052"); // results in s13: "52" String s14 = StringTools.winnowDecimal("00.5"); // results in s14: "0.5" String s15 = StringTools.winnowDecimal("00000"); // results in s15: "0" String s16 = StringTools.winnowDecimal("000.0500"); // results in s16: "0.0500" String s17 = StringTools.winnowDecimal("1"); // results in s17: "1" String s18 = StringTools.winnowDecimal("1."); // results in s18: "1." String s19 = StringTools.winnowDecimal("0"); // results in s19: "0" String s20 = StringTools.winnowDecimal("0."); // results in s20: "0." String s21 = StringTools.winnowDecimal("000."); // results in s21: "0."

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are decimal char, that same String instance is returned. If there were any characters in source that were not decimal char, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null. If the returned result would be a zero-length String or if a zero-length String is passed in, then a reference to the single, shared ZERO_LEN_STRING instance is returned to help be more memory and more garbage-collection efficient.

winnowInteger

public static String winnowInteger(String source)
Winnows the passed String keeping only the characters that make up the string version of an integer number. Processes the passed string by ignoring all characters not in the set {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, -}.

The negative sign '-' is ignored if it is not the first valid character.

All decimal points are ignored, so be careful when winnowing something like "34.5" as the result for this method is: 345 which is ten times bigger than probably intended! If input might contain decimal points that should not be ignored, instead use something like winnowDecimal(String), DecimalTools.parseBigDecimal(String), or DecimalTools.parseValue(String).

Extra leading zeros (0) are removed. A leading zero is only kept if it is the only digit. A leading zero is a zero that appears to the left of the other digits.

If zero digits are found, then a zero-length String is returned (even if a minus sign was found). There is no need to trim any whitespace before calling this method as none of the whitespace characters are in the valid set of characters listed above (in fact, pre-trimming of whitespace is likely to be less efficient than allowing this method to do the whitespace trimming).

Example:

 String s0 = StringTools.winnowInteger("98555");
 //                     results in s0: "98555"
 String s1 = StringTools.winnowInteger(" -3,591 ");
 //                     results in s1: "-3591"
 //
 // If a decimal point is present, it is ignored
 // and any and all digits after it are retained:
 String s2 = StringTools.winnowInteger(" 91.0 ");
 //                     results in s2: "910" // so be careful!
 String s3 = StringTools.winnowInteger(" 91.8 ");
 //                     results in s3: "918" // so be careful!
 //
 String s4 = StringTools.winnowInteger(" abc-3,efg5h9i1j.kmn ");
 //                     results in s4: "-3591"
 String s5 = StringTools.winnowInteger(" 4 - 3 = 1 "); // no math done!
 //                     results in s5: "431"
 String s6 = StringTools.winnowInteger("  3,148,912.  ");
 //                     results in s6: "3148912"
 String s7 = StringTools.winnowInteger(" -35-91.10.3 ");
 //                     results in s7: "-3591103"
 String s8 = StringTools.winnowInteger("-abc.def");
 //                     results in s8: ""
 String s9 = StringTools.winnowDecimal("-.");
 //                     results in s9: ""
 String s10 = StringTools.winnowDecimal("-");
 //                     results in s10: ""
 String s11 = StringTools.winnowDecimal(".");
 //                     results in s11: ""
 String s12 = StringTools.winnowInteger("  abc def ghi ");
 //                     results in s12: ""
String s13 = StringTools.winnowInteger("0"); // results in s13: "0" String s14 = StringTools.winnowInteger("000"); // results in s14: "0" String s15 = StringTools.winnowInteger("0052"); // results in s15: "52" String s15 = StringTools.winnowInteger("-0052"); // results in s15: "-52"

Parameters:
source - source string to process
Returns:
the filtered string. If all characters in source are integer char, that same String instance is returned. If there were any characters in source that were not integer char, then a new String is returned with those invalid characters stripped out. If source is "empty" (that is null or zero-length), a zero-length String is returned. This method never returns null. If the returned result would be a zero-length String or if a zero-length String is passed in, then a reference to the single, shared ZERO_LEN_STRING instance is returned to help be more memory and more garbage-collection efficient.

toSortedCharArray

public static char[] toSortedCharArray(char[] source)
Returns a new char[] sorted in Unicode order representing all of the characters in the source char[]. If null or a zero-length array is passed in, a zero-length char[] is returned. This method never returns null. Note that any duplicate characters in the source are retained.

The char[] returned is suitable for passing into winnow(String source, char[] sortedValidChar) as the sortedValidChar.

Parameters:
source - original char[] to sort. The contents of the passed array are not modified by this method—a brand new array is allocated internally and returned.
Returns:
a new char[] with all of the characters in source sorted in Unicode order.

toSortedCharArray

public static char[] toSortedCharArray(String source)
Returns a char[] sorted in Unicode order representing all of the characters in the source String. If null or a zero-length String is passed in, a zero-length char[] is returned. This method never returns null. Note that any duplicate characters in the source are retained.

The char[] returned is suitable for passing into winnow(String source, char[] sortedValidChar) as the sortedValidChar.

Parameters:
source - set of characters to sort.
Returns:
all of the characters in source sorted in Unicode order.

stackTraceToStringArray

public static String[] stackTraceToStringArray(Throwable t)
Performs a stack trace on the passed Throwable and returns each line as an element in the array.


split

public static String[] split(String source,
                             char delimiter)
Splits up the specified source into multiple String's based on the specified delimiter. Each of the resulting String's is trimmed.

Examples:

 split("a|b|c|d", '|')   -> { "a", "b", "c", "d" }
 split("|a|b|c|d", '|')  -> { "", "a", "b", "c", "d" }
 split("a|b|c|d|", '|')  -> { "a", "b", "c", "d", "" }

 split("||a||b|||c||d||", '|')  ->
         { "", "", "a", "", "b", "", "", "c", "", "d", "", "" }

 split("apple banana cherry grape watermelon", ' ')  ->
         { "apple", "banana", "cherry", "grape", "watermelon" }
 


split

public static String[] split(String source,
                             String delimiter)
Splits up the specified source into multiple String's based on the specified delimiter. The original source is trimmed before any processing. Each of the resulting String's is trimmed.

Examples:

 split("a|b|c|d", "|")   -> { "a", "b", "c", "d" }
 split("|a|b|c|d", "|")  -> { "", "a", "b", "c", "d" }
 split("a|b|c|d|", "|")  -> { "a", "b", "c", "d", "" }

 split("||a||b|||c||d||", "|")  ->
         { "", "", "a", "", "b", "", "", "c", "", "d", "", "" }

 split("apple banana cherry grape watermelon", " ")  ->
         { "apple", "banana", "cherry", "grape", "watermelon" }

 split("apple, banana, cherry, grape, watermelon", ",")  ->
         { "apple", "banana", "cherry", "grape", "watermelon" }
 


sortUnique

public static String[] sortUnique(String[] source)
Returns a sorted copy of the original list of strings. If source is null, a zero-length array is returned. Returned array length may be less than source length. If source contains duplicates, they are skipped. If source contains nulls or zero-length strings, they are skipped.


quoteWrap

public static String quoteWrap(String source)
Returns the source String wrapped with double-quotes. If source is pointing to null, then the String null is returned (without surrounding quotes). If source is pointing to the String apple then a new String with a prefix and suffix of " is returned: "apple" (the quotes are actually part of the returned String).


quoteWrap

public static String quoteWrap(Object source)
Returns the toString() version of the source Object wrapped with double-quotes. If source is pointing to null, then the String null is returned (without surrounding quotes). If source is pointing to the String apple then a new String with a prefix and suffix of " is returned: "apple" (the quotes are actually part of the returned String).


paramEmptyCheck

public static String paramEmptyCheck(String param,
                                     String paramName)
                              throws IllegalArgumentException
Used as a helper to check passed parameters for prohibited "empty" values in other methods. Being "empty" is determined by isEmpty(String). If param is not "empty", then param is simply and quietly returned from this method.

Parameters:
param - the parameter value to check.
paramName - the optional name of the parameter being checked. If present, paramName is used to enhance the text of the exception.
Returns:
the passed param if param is not "empty".
Throws:
IllegalArgumentException - if param is "empty".

paramEmptyCheck

public static String paramEmptyCheck(String param)
                              throws IllegalArgumentException
Used as a helper to check passed parameters for prohibited "empty" values in other methods. Being "empty" is determined by isEmpty(String). If param is not "empty", then param is simply and quietly returned from this method.

Parameters:
param - the parameter value to check.
Returns:
the passed param if param is not "empty".
Throws:
IllegalArgumentException - if param is "empty".

formatCommaDelimited

public static String formatCommaDelimited(String... itemList)
Takes the passed strings and formats them into a comma and space delimited string. Each comma is followed by a space. There is no final comma. For example:
 String s = StringTools.formatCommandDelimited(apple, banana, cherry);
 
returns this String: "apple, banana, cherry".

Parameters:
itemList -

ProgramixGenericLib v5.0.1

Copyright © 2001-2009 Programix Incorporated. All rights reserved. ProgramixGenericLib is free and is OSI Certified Open Source Software under the BSD license.