Holger's Java API

## com.antelmann.util
Class Strings

    java.lang.Object
      com.antelmann.util.Strings

    public final class Strings

extends Object

A utility class with several useful functions to manipulate String objects.

Author:
  Holger Antelmann

Nested Class Summary
`static class` `Strings.Symbol` generally useful symbols to ease their use in non-UTF8 source code Convenient example tables are found e.g. here: http://www.csbruce.com/software/utf-8.html

Field Summary
`static String` `fs` Deprecated. see File#separator
`static String` `HTML_COPYRIGHT` represents the symbol for use in HTML or XML
`static String` `HTML_LEFT_DOUBLE_QUOTE` represents the symbol for use in HTML or XML
`static String` `HTML_REGISTERED_TM` represents the symbol for use in HTML or XML
`static String` `HTML_SPACE` represents the HTML non-breaking space character
`static String` `HTML_TRADEMARK` represents the symbol for use in HTML or XML
`static String` `lb` convenient access to the platform dependent line separator
`static String` `MS_DOS` typical MS-DOS charset
`static String` `RIGHT_DOUBLE_QUOTE` represents the symbol for use in HTML or XML
`static PatternExtractor<Object,String>` `STRING_EXTRACTOR`
`static String` `UTF8` UTF8 encoding
`static String` `WESTERN_CHARSET` ISO 8859-1
`static String` `XML_HEADER` xml header line with utf8

Method Summary
`static String` `asPercent(double d)`
`static String` `asSingleLine(String txt, String lineReplacer)`
`static char[]` `baseCharSet()` returns all upper- and lowercase letters as well as all digits
`static String` `capitalizeFirst(String s)` returns a string like the given one, only that the first one is upper case
`static String` `capitalizeFirstOnly(String s)` returns a string where the given string is all lower case, except the first one, which is upper case
`static String` `capitalizeWords(String s)` returns a string where each word will be lowercase except for the first letter of the word, which will be capitalized
`static Comparator<String>` `compareAsNumbers()` a special Comparator that tries to interpret a String as a sequence of numbers; only if that fails, a standard Comparator is used
`static Comparator<Object>` `compareAsString()`
`static Comparator<String>` `compareStringAsDouble()` a special Comparator that tries to interpret both strings as numbers for comparing; only if that fails, a standard Comparator is used
`static boolean` `containsIgnoreCase(Collection<String> col, String pattern)`
`static boolean` `containsIgnoreCase(String text, String pattern)` returns `indexOfIgnoreCase(text, pattern) >= 0`
`static int` `count(String text, String pattern)` counts how many times the given pattern occurs in the given text.
`static int` `countIgnoreCase(String text, String pattern)` counts how many times the given pattern occurs in the given text.
`static String` `cutTail(String str, int n)`
`static String` `decode64(String s)` decodes the given String using Base64 assuming default encoding
`static String` `decodeURL(String s)` uses URLEncoder using UTF8
`static String` `decodeURL(String s, String encoding)`
`static String` `decodeXML(String text)` decodes an HTML or XML text sequence into human readable form using the `translateArray`
`static String` `defaultEncoding()` returns this plattform's default encoding charset
`static String` `encode64(String s)` encodes the given String using Base64 with default encoding
`static String` `encodeURL(String s)` uses URLEncoder using UTF8
`static String` `encodeURL(String s, String encoding)`
`static String` `encodeXML(String text)` encodes a text string to use as text in an HTML or XML document using the `translateArray`
`static int` `equalUntil(String s1, String s2)`
`static char[]` `extendedCharSet()` returns all `baseCharSet()` chars and also includes some extended chars that are found on most keyboards - to be used for generating more secure passwords
`static String` `extract(String str, String from, String to, boolean inclusive)`
`static Integer` `extractInt(String str)`
`static String` `firstLine(String txt)`
`static String` `generateID()`
`static String[]` `getFields(String line, String fieldSeparator, boolean withQuotes)` obtains an array of all 'fields' - including empty fields.
`static int` `getLineCount(String str)` tailing empty lines will not be counted
`static String[]` `getTokens(String str, String delim)` uses a `StringTokenizer` to obtain the tokens
`static String[]` `getTokens(String str, String delim, boolean withQuotes)` allows to 'tokenize' a string while allowing quoted sections where delimiters are regarded as part of the token
`static String` `hash(String s)` returns a human readable digest of the given string based on MD5 and UTF-8 encoding
`static String` `hexString(byte... bytes)`
`static byte[]` `hexToBytes(String s)`
`static int` `indexOfIgnoreCase(String textToSearch, String pattern)` calls the method with the same name adding index 0
`static int` `indexOfIgnoreCase(String textToSearch, String pattern, int fromIndex)`
`static boolean` `isAllNumbers(String str)` returns true only if the string contains only digits (besides whitespace)
`static boolean` `isEmpty(Object obj)` uses the toString method if obj is non-null; returns false if null
`static boolean` `isEmpty(String s)` convenience method: returns true only if the String is either null or has no other content but whitespace
`static String` `left(String str, int n)`
`static String` `mapAsString(Map<?,?> map)` uses 'tab' as field separator and platform dependent line separator
`static String` `mapAsString(Map<?,?> map, String fieldSeparator, String lineSeparator)`
`static char[]` `randomChars(int length)` calls `randomChars(int, char[], boolean)` with `baseCharSet()`; duplicates are allowed
`static char[]` `randomChars(int length, char[] baseSet, boolean allowDuplicates)` calls `randomChars(int, char[], boolean, Random)` with a default Random object
`static char[]` `randomChars(int length, char[] baseSet, boolean allowDuplicates, Random random)` generates and returns a randomly generated character array that is derived from the given input parameters
`static String` `randomString(int length)` simply calls `randomChars(int)` and converts it to a String for convenience
`static String` `randomStringExtended(int length)` similar to `randomString(int)`, but uses `extendedCharSet()`
`static String` `recode(String str, String fromCharset, String toCharset)`
`static String` `replaceAll(String original, String oldSubString, String newSubString)` Deprecated. as of Java version 1.5
`static String` `replaceAllIgnoreCase(String original, String oldSubString, String newSubString)` replaces every occurrence of oldSubString (ignoring case) with newSubString within the original String and returns the resulting string (no regular expressions are used)
`static String` `right(String str, int n)`
`static boolean` `same(String s1, String s2)` returns true only if the the both strings are equal or null, false otherwise.
`static String` `secureHash(String password, byte[] salt)` returns a human readable (hex-string) hash of the given string based on PBKDF2 while using salt to prevent standardized rainbow-table attacks.
`static String` `trim(String s, int length)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### lb

    public static final String lb

  convenient access to the platform dependent line separator

### fs

    @Deprecated
    public static final String fs

  Deprecated. see File#separator
  convenient access to the platform dependent file separator

### XML_HEADER

    public static final String XML_HEADER

  xml header line with utf8

  See Also:
    Constant Field Values

### HTML_SPACE

    public static final String HTML_SPACE

  represents the HTML non-breaking space character

  See Also:
    Constant Field Values

### HTML_LEFT_DOUBLE_QUOTE

    public static final String HTML_LEFT_DOUBLE_QUOTE

  represents the symbol for use in HTML or XML

  See Also:
    Constant Field Values

### RIGHT_DOUBLE_QUOTE

    public static final String RIGHT_DOUBLE_QUOTE

  represents the symbol for use in HTML or XML

  See Also:
    Constant Field Values

### HTML_TRADEMARK

    public static final String HTML_TRADEMARK

  represents the symbol for use in HTML or XML

  See Also:
    Constant Field Values

### HTML_REGISTERED_TM

    public static final String HTML_REGISTERED_TM

  represents the symbol for use in HTML or XML

  See Also:
    Constant Field Values

### HTML_COPYRIGHT

    public static final String HTML_COPYRIGHT

  represents the symbol for use in HTML or XML

  See Also:
    Constant Field Values

### WESTERN_CHARSET

    public static final String WESTERN_CHARSET

  ISO 8859-1

  See Also:
    Constant Field Values

### MS_DOS

    public static final String MS_DOS

  typical MS-DOS charset

  See Also:
    Constant Field Values

### UTF8

    public static final String UTF8

  UTF8 encoding

  See Also:
    Constant Field Values

### STRING_EXTRACTOR

    public static final PatternExtractor<Object,String> STRING_EXTRACTOR

See Also:
  `String.valueOf(Object)`

Method Detail

### defaultEncoding

    public static String defaultEncoding()

  returns this plattform's default encoding charset

### generateID

    public static String generateID()

  See Also:
    `UUID.randomUUID()`

### hash

    public static String hash(String s)

  returns a human readable digest of the given string based on MD5 and UTF-8 encoding

### secureHash

    public static String secureHash(String password,
                                    byte[] salt)

  returns a human readable (hex-string) hash of the given string based on PBKDF2 while using salt to prevent standardized rainbow-table attacks. Note that this algorithm is also deliberately slow to prevent brute force attacks, which makes it useful for e.g. storing passwords.

  See Also:
    `Data.generateSalt(int)`, `SecureUserImpl`

### randomString

    public static String randomString(int length)

  simply calls `randomChars(int)` and converts it to a String for convenience

### randomStringExtended

    public static String randomStringExtended(int length)

  similar to `randomString(int)`, but uses `extendedCharSet()`

### randomChars

    public static char[] randomChars(int length)

  calls `randomChars(int, char[], boolean)` with `baseCharSet()`; duplicates are allowed

### baseCharSet

    public static char[] baseCharSet()

  returns all upper- and lowercase letters as well as all digits

### extendedCharSet

    public static char[] extendedCharSet()

  returns all `baseCharSet()` chars and also includes some extended chars that are found on most keyboards - to be used for generating more secure passwords

### randomChars

    public static char[] randomChars(int length,
                                     char[] baseSet,
                                     boolean allowDuplicates)

  calls `randomChars(int, char[], boolean, Random)` with a default Random object

### randomChars

    public static char[] randomChars(int length,
                                     char[] baseSet,
                                     boolean allowDuplicates,
                                     Random random)

  generates and returns a randomly generated character array that is derived from the given input parameters

  Parameters:
    `length` - specifies the length of the returned array
    `baseSet` - defines the set of characters from with the randomly chosen return value is derived from
    `allowDuplicates` - if false, each character from the baseSet can only be present once in the return value
  Returns:
    an array of randomly generated characters based on the input parameters

### capitalizeWords

    public static String capitalizeWords(String s)

  returns a string where each word will be lowercase except for the first letter of the word, which will be capitalized

### capitalizeFirst

    public static String capitalizeFirst(String s)

  returns a string like the given one, only that the first one is upper case

  See Also:
    `Introspector.decapitalize(String)`

### capitalizeFirstOnly

    public static String capitalizeFirstOnly(String s)

  returns a string where the given string is all lower case, except the first one, which is upper case

  See Also:
    `capitalizeFirst(String)`

### replaceAll

    @Deprecated
    public static String replaceAll(String original,
                                               String oldSubString,
                                               String newSubString)

  Deprecated. as of Java version 1.5

  replaces every occurrence of oldSubString with newSubString within the original String and returns the resulting string (no regular expressions are used). This method is obsolete since Java version 1.5

  See Also:
    `String.replace(CharSequence, CharSequence)`

### replaceAllIgnoreCase

    public static String replaceAllIgnoreCase(String original,
                                              String oldSubString,
                                              String newSubString)

  replaces every occurrence of oldSubString (ignoring case) with newSubString within the original String and returns the resulting string (no regular expressions are used)

### indexOfIgnoreCase

    public static int indexOfIgnoreCase(String textToSearch,
                                        String pattern)

  calls the method with the same name adding index 0

### indexOfIgnoreCase

    public static int indexOfIgnoreCase(String textToSearch,
                                        String pattern,
                                        int fromIndex)

### count

    public static int count(String text,
                            String pattern)

  counts how many times the given pattern occurs in the given text. Example: `count("ababababab", "abab")` returns 2.

### countIgnoreCase

    public static int countIgnoreCase(String text,
                                      String pattern)

  counts how many times the given pattern occurs in the given text. Example: `count("aBabABabab", "aBAb")` returns 2.

### containsIgnoreCase

    public static boolean containsIgnoreCase(String text,
                                             String pattern)

  returns `indexOfIgnoreCase(text, pattern) >= 0`

### containsIgnoreCase

    public static boolean containsIgnoreCase(Collection<String> col,
                                             String pattern)

### encodeXML

    public static String encodeXML(String text)

  encodes a text string to use as text in an HTML or XML document using the `translateArray`

### decodeXML

    public static String decodeXML(String text)

  decodes an HTML or XML text sequence into human readable form using the `translateArray`

### encodeURL

    public static String encodeURL(String s)

  uses URLEncoder using UTF8

### encodeURL

    public static String encodeURL(String s,
                                   String encoding)

### decodeURL

    public static String decodeURL(String s)

  uses URLEncoder using UTF8

### decodeURL

    public static String decodeURL(String s,
                                   String encoding)

### mapAsString

    public static String mapAsString(Map<?,?> map)

  uses 'tab' as field separator and platform dependent line separator

### mapAsString

    public static String mapAsString(Map<?,?> map,
                                     String fieldSeparator,
                                     String lineSeparator)

### asPercent

    public static String asPercent(double d)

### hexString

    public static String hexString(byte... bytes)

  See Also:
    `hexToBytes(String)`, `DatatypeConverter.printHexBinary(byte[])`

### hexToBytes

    public static byte[] hexToBytes(String s)
                             throws NumberFormatException

  Throws:
    `NumberFormatException` - if the String cannot be parsed properly
  See Also:
    `hexToBytes(String)`

### recode

    public static String recode(String str,
                                String fromCharset,
                                String toCharset)
                         throws UnsupportedEncodingException

  Throws:
    `UnsupportedEncodingException`

### encode64

    public static String encode64(String s)

  encodes the given String using Base64 with default encoding

### decode64

    public static String decode64(String s)

  decodes the given String using Base64 assuming default encoding

### same

    public static boolean same(String s1,
                               String s2)

  returns true only if the the both strings are equal or null, false otherwise. This method may be deprecated in the future, as it is really replaced by the more general com.antelmann.util.Misc.same(Object, Object).

  See Also:
    `Misc.same(Object, Object)`

### equalUntil

    public static int equalUntil(String s1,
                                 String s2)

### isEmpty

    public static boolean isEmpty(Object obj)

  uses the toString method if obj is non-null; returns false if null

### isEmpty

    public static boolean isEmpty(String s)

  convenience method: returns true only if the String is either null or has no other content but whitespace

### left

    public static String left(String str,
                              int n)

### right

    public static String right(String str,
                               int n)

### cutTail

    public static String cutTail(String str,
                                 int n)

### firstLine

    public static String firstLine(String txt)

### asSingleLine

    public static String asSingleLine(String txt,
                                      String lineReplacer)

### trim

    public static String trim(String s,
                              int length)

### compareAsString

    public static Comparator<Object> compareAsString()

### compareStringAsDouble

    public static Comparator<String> compareStringAsDouble()

  a special Comparator that tries to interpret both strings as numbers for comparing; only if that fails, a standard Comparator is used

### compareAsNumbers

    public static Comparator<String> compareAsNumbers()

  a special Comparator that tries to interpret a String as a sequence of numbers; only if that fails, a standard Comparator is used

### extractInt

    public static Integer extractInt(String str)

### getFields

    public static String[] getFields(String line,
                                     String fieldSeparator,
                                     boolean withQuotes)

  obtains an array of all 'fields' - including empty fields. Useful to e.g. import a csv file.

  Parameters:
    `line` - the string to be separated into fields
    `fieldSeparator` - the field separator to be used
  Returns:
    an array containing all fields produced by the StringTokenizer
  See Also:
    `StringTokenizer`, `getTokens(String, String)`

### getLineCount

    public static int getLineCount(String str)

  tailing empty lines will not be counted

### getTokens

    public static String[] getTokens(String str,
                                     String delim)

  uses a `StringTokenizer` to obtain the tokens

  Parameters:
    `str` - the string to be tokenized
    `delim` - the delimiter to be used
  Returns:
    an array containing all tokens produced by the StringTokenizer
  See Also:
    `StringTokenizer`, `getFields(String, String, boolean)`

### getTokens

    public static String[] getTokens(String str,
                                     String delim,
                                     boolean withQuotes)

  allows to 'tokenize' a string while allowing quoted sections where delimiters are regarded as part of the token

### extract

    public static String extract(String str,
                                 String from,
                                 String to,
                                 boolean inclusive)

### isAllNumbers

    public static boolean isAllNumbers(String str)

  returns true only if the string contains only digits (besides whitespace)

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads