StringTools (ProgramixGenericLib)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

ProgramixGenericLib v5.0.1

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.programix.util
Class StringTools

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

public class StringTools
extends Object
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:

a == b (two references to the same object)
( a == null ) && ( b == null ) (both are null)
( a != null ) && ( b != null ) && ( a.equals(b) == 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:

( a == null ) && ( b != null )
( a != null ) && ( b == null )
( a != null ) && ( b != null ) && ( a.equals(b) == false )

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:

a == b (two references to the same object)
( a == null ) && ( b == null ) (both are null)
( a != null ) && ( b != null ) && ( a.equalsIgnoreCase(b) == 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:

( a == null ) && ( b != null )
( a != null ) && ( b == null )
( a != null ) && ( b != null ) && ( a.equalsIgnoreCase(b) == false )

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

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 -

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

ProgramixGenericLib v5.0.1

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.programix.util Class StringTools

ZERO_LEN_STRING

ZERO_LEN_ARRAY

NULL_FIRST_CASE_SENSITIVE_ASC

NULL_FIRST_CASE_SENSITIVE_DESC

NULL_FIRST_CASE_INSENSITIVE_ASC

NULL_FIRST_CASE_INSENSITIVE_DESC

NULL_LAST_CASE_SENSITIVE_ASC

NULL_LAST_CASE_SENSITIVE_DESC

NULL_LAST_CASE_INSENSITIVE_ASC

NULL_LAST_CASE_INSENSITIVE_DESC

isEmpty

isNotEmpty

isEmpty

isNotEmpty

isEmptyTrimmed

isNotEmptyTrimmed

isEmptyTrimmed

isNotEmptyTrimmed

isEmptyWithoutTrim

isNotEmptyWithoutTrim

isEmptyWithoutTrim

isNotEmptyWithoutTrim

isEmpty

isNotEmpty

trim

trim

trimToNull

trimToNull

nullToBlank

nullToBlank

blankToNull

padClip

toArray

isSame

isDifferent

isSameIgnoreCase

isDifferentIgnoreCase

compare

hash

toHexString

parseHexString

filter

winnow

winnow

winnowDigit

winnowHexDigit

winnowAlpha

winnowAlphaNumeric

winnowDecimal

winnowInteger

toSortedCharArray

toSortedCharArray

stackTraceToStringArray

split

split

sortUnique

quoteWrap

quoteWrap

paramEmptyCheck

paramEmptyCheck

formatCommaDelimited

com.programix.util
Class StringTools