net.rim.device.api.util
Class StringUtilities

java.lang.Object
  net.rim.device.api.util.StringUtilities

public final class StringUtilities
extends Object

Utility methods for manipulating Strings.

Method Summary
static StringBuffer	append(StringBuffer strBuf, byte[] buffer, int offset, int length) Append a subsection of a byte array to a StringBuffer.
static StringBuffer	append(StringBuffer strBuf, String str, int offset, int length) Appends a subsection of a String to a StringBuffer.
static StringBuffer	append(StringBuffer strBuf, StringBuffer other) Append a StringBuffer to another StringBuffer.
static StringBuffer	append(StringBuffer strBuf, StringBuffer other, int offset, int length) Append a subsection of a StringBuffer to another StringBuffer.
static String	cStr2String(byte[] b, int start, int len) Converts C/C++ string into a Java String.
static int	compareObjectToStringIgnoreCase(Object o1, Object o2) Compares the string form of two objects, ignoring case.
static int	compareToHandleSpecialChars(String s1, String s2) Compare two strings, ignoring case and handling special characters differently than strict ASCII order.
static int	compareToIgnoreCase(String s1, String s2) Compare two strings, ignoring case.
static int	compareToIgnoreCase(String s1, String s2, int locale) Compare two strings, ignoring case, taking into account the specified locale.
static int	computeHashCode(StringBuffer stringBuffer) Retrieves hashcode of provided string buffer.
static int	computeReverseLookupHashCodeBytes(byte[] bytes, int start, int length) Retrieves restricted hashcode for section of a byte array.
static int	computeReverseLookupHashCodeBytes(byte[] bytes, int start, int length, boolean allChars) Retrieves restricted hashcode for section of a byte array.
static int	computeReverseLookupHashCodeString(String string) Retrieves restricted hashcode for string (for use in reverse lookups).
static int	computeReverseLookupHashCodeString(String string, boolean allChars) Retrieves restricted hashcode for string (for use in reverse lookups).
static void	convertToOriginal(StringBuffer stringBuffer, int start, int length) Converts the string buffer content (characters) to the first characters in a decomposition.
static String[]	copy(String[] array) Retrieves a duplicate copy of a String array.
static int	hashCode(String str, int fromIndex, int toIndex, boolean ignoreCase) Retrieves hashcode of provided string between the offsets provided.
static int	hashCodeIgnoreCase(String str) Retrieves case-insensitive hashcode of provided string.
static int	indexOf(String string, char ch, int fromIndex, int toIndex) Retrieves first occurrence of character in section of provided string.
static int	indexOf(String string, int ch, int fromIndex, int toIndex) Retrieves first occurrence of character in section of provided string.
static String	removeChars(String src, String remove) Removes specified characters from a string.
static boolean	startsWithIgnoreCase(String string, String prefix) Determines if target string begins with provided prefix.
static boolean	startsWithIgnoreCaseAndAccents(String string, String prefix) Determines if target string begins with a provided prefix, igoring the case and accents of the characters in the string.
static boolean	strEqual(String s1, String s2) Compares two (possibly null) strings for equality.
static boolean	strEqualIgnoreCase(String s1, String s2) Compares two (possibly null) strings for equality, ignoring their case.
static long	stringHashToLong(String key) Returns the first 8 bytes of a SHA1 digest as a long.
static String[]	stringToKeywords(String string) Extracts keyword tokens from provided string.
static int	stringToKeywords(String stringContainingKeywords, int[] startOffsets, int resultOffset) Parses string into keywords.
static int	stringToKeywords(String string, String[] wordArray, int index) Extracts keyword tokens from provided string, placing them into provided array.
static String[]	stringToWords(String string) Extracts word tokens from provided string.
static int	stringToWords(String stringContainingWords, int[] indexResults, int resultOffset) Parses string into words.
static int	stringToWords(String string, String[] wordArray, int index) Extracts word tokens from provided string, placing them into provided array.
static int	stringToWordsOrKeywords(String stringContainingKeywords, int[] startOffsets, int[] endOffsets, int resultOffset, boolean keywords) Native method that parses string to words or keywords
static String	toLowerCase(String str, int locale) Convert string to lower case , using the specified locale.
static void	toLowerCase(StringBuffer stringBuffer, int start, int length, int locale) Converts the string buffer content (characters) to lower case, using the specified locale.
static String	toUpperCase(String str, int locale) Convert string to upper case , using the specified locale.
static int	writeUTF(String str, DataOutput out) Writes a string to the specified DataOutput using UTF-8 encoding in a machine-independent manner.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

convertToOriginal

public static void convertToOriginal(StringBuffer stringBuffer,
                                     int start,
                                     int length)

Converts the string buffer content (characters) to the first characters in a decomposition. First character in a decomposition is the base character after stripping accents, but does not fold case. If the character is an accent it is returned unchanged. For more information on folding/decompistion see Draft Unicode Technical Report #30: Character Foldings.

Examples: character U+00E9 will be replaced with U+0065; character U+1EDA will be replaced with U+004F.

Parameters:

stringBuffer - string buffer containing characters to use as source.

start - The starting offset. If this value is less than 0 IllegalArgumentException is thrown.

length - Number of characters to include in the conversion. If this value is less than 0, or (start + length) > length of the received string buffer IllegalArgumentException is thrown.

Throws:

NullPointerException - if any argument is null.

See Also:

CharacterUtilities.getOriginal(char)

Since:

BlackBerry API 4.2.0

toLowerCase

public static void toLowerCase(StringBuffer stringBuffer,
                               int start,
                               int length,
                               int locale)

Converts the string buffer content (characters) to lower case, using the specified locale.

Parameters:

stringBuffer - string buffer containing characters to convert

start - The starting offset.

length - Number of characters to include in the conversion.

locale - locale code to use for the conversion

Throws:

NullPointerException - if stringBuffer is null.

IllegalArgumentException - if length or start is less than 0, or (start + length) > length of the received string buffer.

Since:

BlackBerry API 4.6.0

compareToIgnoreCase

public static int compareToIgnoreCase(String s1,
                                      String s2)

Compare two strings, ignoring case.

This function converts each character of s1 to upper case and each character of s2 to upper case, in the context of the specified locale, and compares the converted characters one by one. It is assumed that conversion of 1 charcater to the upper case will result in 1 upper case(if exists) character.

Parameters:

s1 - First string to compare.

s2 - Second string to compare.

Returns:

Value less than zero if first string sorts before the second; zero if the two strings are the same; value greater than zero if the first string sorts after the second.

Throws:

NullPointerException - if any argument is null.

compareToHandleSpecialChars

public static int compareToHandleSpecialChars(String s1,
                                              String s2)

Compare two strings, ignoring case and handling special characters differently than strict ASCII order.

This function converts each character of s1 to upper case and each character of s2 to upper case, in the context of the specified locale, and compares the converted characters one by one. It is assumed that conversion of 1 charcater to the upper case will result in 1 upper case(if exists) character. The following special characters are sorted before any others, in the order they appear below:

SPACE ! " # $ % & ( * , . / : ; @ [ ] ^ _ { | } ~ + < = > ' -

Parameters:

s1 - First string to compare.

s2 - Second string to compare.

Returns:

Value less than zero if first string sorts before the second; zero if the two strings are the same; value greater than zero if the first string sorts after the second.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 5.0.0

compareToIgnoreCase

public static int compareToIgnoreCase(String s1,
                                      String s2,
                                      int locale)

Compare two strings, ignoring case, taking into account the specified locale.

This function converts each character of s1 to upper case and each character of s2 to upper case, in the context of the specified locale, and compares the converted characters one by one. It is assumed that conversion of 1 charcater to the upper case will result in 1 upper case(if exists) character.

Parameters:

s1 - First string to compare.

s2 - Second string to compare.

locale - The locale code to use for the conversion.

Returns:

Value less than zero if first string sorts before the second; zero if the two strings are the same; value greater than zero if the first string sorts after the second.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.2.0

toLowerCase

public static String toLowerCase(String str,
                                 int locale)

Convert string to lower case , using the specified locale.

Parameters:

str - String to convert

locale - locale code to use for the conversion

Returns:

converted to lower case string

Throws:

NullPointerException - if the argument is null.

Since:

BlackBerry API 4.2.0

toUpperCase

public static String toUpperCase(String str,
                                 int locale)

Convert string to upper case , using the specified locale.

Parameters:

str - String to convert

locale - locale code to use for the conversion

Returns:

converted to upper case string

Throws:

NullPointerException - if the argument is null.

Since:

BlackBerry API 4.2.0

computeHashCode

public static int computeHashCode(StringBuffer stringBuffer)

Retrieves hashcode of provided string buffer.

An identical hashcode would be produced for a String instance containing the same data.

Parameters:

stringBuffer - String buffer for which to retrieve a hashcode.

Returns:

Hashcode of string buffer.

Throws:

NullPointerException - if the argument is null.

hashCodeIgnoreCase

public static int hashCodeIgnoreCase(String str)

Retrieves case-insensitive hashcode of provided string.

An hashcode identical to str.toLowerCase().hashCode() without the extra object creation.

Parameters:

str - String for which to retrieve a case-insensitive hashcode.

Returns:

Case-insensitive hashcode of the string.

Throws:

NullPointerException - if the argument is null.

Since:

BlackBerry API 4.0.0

hashCode

public static int hashCode(String str,
                           int fromIndex,
                           int toIndex,
                           boolean ignoreCase)

Retrieves hashcode of provided string between the offsets provided.

An hashcode identical to str.substring(fromIndex, toIndex).hashCode() without the extra object creation.

Parameters:

str - String for which to retrieve a hashcode.

fromIndex - First element in string to look at. If this value is less than 0, or if the value is greater than the toIndex parameter an IllegalArgumentException is thrown.

toIndex - Last element in string to look at. If this value is greater than the length of the string, this method assumes it has the same value as the length of the string.

ignoreCase - Whether or not to compute a case-insensitive hashcode.

Returns:

Hashcode of the sub-string.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.1.0

computeReverseLookupHashCodeString

public static int computeReverseLookupHashCodeString(String string)

Retrieves restricted hashcode for string (for use in reverse lookups).

The hash only considers alphas, numbers, *, #, and the @ sign, with all characters being lower case.

Parameters:

string - String for which to retrieve the hashcode.

Returns:

Hashcode of string.

Throws:

NullPointerException - if the argument is null.

computeReverseLookupHashCodeString

public static int computeReverseLookupHashCodeString(String string,
                                                     boolean allChars)

Retrieves restricted hashcode for string (for use in reverse lookups).

The hash only considers alphas, numbers, *, #, and the @ sign, with all characters being lower case.

Parameters:

string - String for which to retrieve the hashcode.

allChars - true if all characters should be hashed, false if just the subset above.

Returns:

Hashcode of string.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.2.0

computeReverseLookupHashCodeBytes

public static int computeReverseLookupHashCodeBytes(byte[] bytes,
                                                    int start,
                                                    int length)

Retrieves restricted hashcode for section of a byte array.

The hash only considers alphas, numbers, *, #, and the @ sign, with all characters being lower case.

Parameters:

bytes - Byte array containing section for which to retrieve the hashcode.

start - First element to include in the compuatation.

length - Number of bytes to include in the computation.

Returns:

Hashcode of section of byte array.

Throws:

NullPointerException - if any argument is null.

computeReverseLookupHashCodeBytes

public static int computeReverseLookupHashCodeBytes(byte[] bytes,
                                                    int start,
                                                    int length,
                                                    boolean allChars)

Retrieves restricted hashcode for section of a byte array.

The hash only considers alphas, numbers, *, #, and the @ sign, with all characters being lower case.

Parameters:

bytes - Byte array containing section for which to retrieve the hashcode.

start - First element to include in the compuatation.

length - Number of bytes to include in the computation.

allChars - true if all characters should be hashed, false if just the subset above.

Returns:

Hashcode of section of byte array.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.2.0

startsWithIgnoreCase

public static boolean startsWithIgnoreCase(String string,
                                           String prefix)

Determines if target string begins with provided prefix.

Parameters:

string - Target string to check.

prefix - Prefix to look for.

Returns:

True if target string starts with provided prefix; otherwise, false.

Throws:

NullPointerException - if any argument is null.

startsWithIgnoreCaseAndAccents

public static boolean startsWithIgnoreCaseAndAccents(String string,
                                                     String prefix)

Determines if target string begins with a provided prefix, igoring the case and accents of the characters in the string.

Parameters:

string - The Target string to check.

prefix - The prefix to look for.

Returns:

true if the target string starts with the provided prefix; otherwise false.

stringToWords

public static String[] stringToWords(String string)

Extracts word tokens from provided string.

A word is a contiguous block of upper case and lower case characters, with the adjacent characters at either end, if they exist, not being upper or lower case.

Parameters:

string - String to tokenize.

Returns:

Array of words found in provided string.

stringToKeywords

public static String[] stringToKeywords(String string)

Extracts keyword tokens from provided string.

A keyword is the same as a word except it may contain additional characters that are necessary for keywords.

Parameters:

string - String to tokenize.

Returns:

Array of keywords found in provided string.

See Also:

StringUtilities.stringToWords(java.lang.String)

Since:

BlackBerry API 4.0.0

stringToWords

public static int stringToWords(String stringContainingWords,
                                int[] indexResults,
                                int resultOffset)
                         throws ArrayIndexOutOfBoundsException

Parses string into words.

This method computes the positions of words in a target string. A word is defined as a contiguous block of upper and lower case characters, with the adjacent characters at either end (if they exist) not upper or lower case.

If the resulting array is not large enough to hold the computed indexes, an ArrayIndexOutOfBoundsException is thrown.

Parameters:

stringContainingWords - Target string to parse.

indexResults - Array of word positions in the target string.

resultOffset - First element of the results array to contain the first word position for the target string.

Returns:

Total number of words found in target string.

Throws:

ArrayIndexOutOfBoundsException - If the results array is not large enough to contain the positions of all the words found in the target string.

stringToKeywords

public static int stringToKeywords(String stringContainingKeywords,
                                   int[] startOffsets,
                                   int resultOffset)
                            throws ArrayIndexOutOfBoundsException

Parses string into keywords.

This method computes the positons of keywords in a target string. A keyword is the same as a word except it may contain additional characters that are necessary for keywords.

If the resulting array is not large enough to hold the computed indexes, an ArrayIndexOutOfBoundsException is thrown.

Parameters:

stringContainingKeywords - Target string to parse.

indexResults - Array of keyword positions in the target string.

resultOffset - First element of the results array to contain the first keyword position for the target string.

Returns:

Total number of keywords found in target string.

Throws:

ArrayIndexOutOfBoundsException - If the results array is not large enough to contain the positions of all the keywords found in the target string.

See Also:

StringUtilities.stringToWords(String, int[], int)

Since:

BlackBerry API 4.0.0

stringToWordsOrKeywords

public static int stringToWordsOrKeywords(String stringContainingKeywords,
                                          int[] startOffsets,
                                          int[] endOffsets,
                                          int resultOffset,
                                          boolean keywords)
                                   throws ArrayIndexOutOfBoundsException

Native method that parses string to words or keywords

Parameters:

stringContainingKeywords - Target string to parse.

startOffsets[] - Array of offsets for words' start positions.

endOffsets[] - Array of offsets for words' end positions.

resultOffset - First element of the offsets arrays.

keywords - Boolean that says whether string should be parsed for words or keywords.

Returns:

Total number of entries found in target string.

Throws:

ArrayIndexOutOfBoundsException - If the offsets arrays are not large enough to contain the positions of all the keywords found in the target string.

Since:

BlackBerry API 4.0.0

stringToWords

public static int stringToWords(String string,
                                String[] wordArray,
                                int index)

Extracts word tokens from provided string, placing them into provided array.

A word is a contiguous block of upper case and lower case characters, with the adjacent characters at either end, if they exist, not being alphanumeric.

Parameters:

string - String to tokenize.

wordArray - Array to contain the word tokens found in provided string.

index - Position in the word array at which to start adding words found in provided string.

Returns:

Number of words extracted from provided string.

stringToKeywords

public static int stringToKeywords(String string,
                                   String[] wordArray,
                                   int index)

Extracts keyword tokens from provided string, placing them into provided array.

A keyword is the same as a word except it may contain additional characters that are necessary for keywords.

Parameters:

string - String to tokenize.

wordArray - Array to contain the keyword tokens found in the provided string.

index - Position in wordArray at which to start adding keywords found in the provided string.

Returns:

Number of keywords extracted from the provided string.

Since:

BlackBerry API 4.0.0

strEqualIgnoreCase

public static boolean strEqualIgnoreCase(String s1,
                                         String s2)

Compares two (possibly null) strings for equality, ignoring their case.

No attempt is currently made to pay attention to ASCII ordering. Two null strings are considered equal.

Parameters:

s1 - First string to compare.

s2 - Second string to compare.

Returns:

True if the two strings are equal; otherwise, false.

strEqual

public static boolean strEqual(String s1,
                               String s2)

Compares two (possibly null) strings for equality.

Two null strings are considered equal.

Parameters:

s1 - First string to compare.

s2 - Second string to compare.

Returns:

True if the two strings are equal; otherwise, false.

cStr2String

public static final String cStr2String(byte[] b,
                                       int start,
                                       int len)

Converts C/C++ string into a Java String.

This method strips off the trailing nulls. Use this instead of String.trim() if you don't want to end up creating two string objects.

Parameters:

b - Byte array containing C/C++ string data.

start - First byte in the C/C++ string.

len - Length of the C/C++ string (this may include nulls that this method will strip.

Returns:

Java String form of provided C/C++ string.

Throws:

NullPointerException - if the argument is null.

compareObjectToStringIgnoreCase

public static int compareObjectToStringIgnoreCase(Object o1,
                                                  Object o2)

Compares the string form of two objects, ignoring case.

This method invokes Object.toString() on both provided objects, and then compares the two return values for equality. No attempt is currently made to pay attention to ASCII ordering. A null object sorts before a non-null object.

Parameters:

o1 - First object to compare.

o2 - Second object to compare.

Returns:

Value less than zero if first object's string form sorts before second; zero if both string forms are equal; value greater than zero if first object's string form sorts after second.

indexOf

public static int indexOf(String string,
                          char ch,
                          int fromIndex,
                          int toIndex)

Retrieves first occurrence of character in section of provided string.

Parameters:

string - String containing section search.

ch - Character to look for.

fromIndex - First element in string to look at. If this value is less than 0, this method assumes it has the value 0. If this value is greater than the toIndex parameter, this method assumes it has the same value as the toIndex parameter.

toIndex - Last element in string to look at. If this value is greater than the length of the string, this method assumes it has the same value as the length of the string.

Returns:

Index of the first occurrence of the character within the section of the string searched. If the fromIndex parameter is greater than, or equal to the toIndex parameter, then this method returns -1. This method also returns -1 if it cannot find an occurrence of the character in the section of the string searched.

indexOf

public static int indexOf(String string,
                          int ch,
                          int fromIndex,
                          int toIndex)

Retrieves first occurrence of character in section of provided string.

Parameters:

string - String containing section search.

ch - Character to look for.

fromIndex - First element in string to look at. If this value is less than 0, this method assumes it has the value 0. If this value is greater than the toIndex parameter, this method assumes it has the same value as the toIndex parameter.

toIndex - Last element in string to look at. If this value is greater than the length of the string, this method assumes it has the same value as the length of the string.

Returns:

Index of the first occurrence of the character within the section of the string searched. If the fromIndex parameter is greater than, or equal to the toIndex parameter, then this method returns -1. This method also returns -1 if it cannot find an occurrence of the character in the section of the string searched.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.0.0

removeChars

public static String removeChars(String src,
                                 String remove)

Removes specified characters from a string.

Parameters:

src - Source string; may not be null.

remove - String containing characters to remove from source string; may not be null.

Returns:

Resulting string with characters removed.

Throws:

NullPointerException - if any argument is null.

stringHashToLong

public static long stringHashToLong(String key)

Returns the first 8 bytes of a SHA1 digest as a long. The same result can be obtained interactively using the BlackBerry JDE by highlighting a string, right-clicking, and choosing "Convert '<string>' to long" from the context menu.

Parameters:

key - The string to convert to a long.

Returns:

The long representation of key.

Throws:

NullPointerException - if the argument is null.

Since:

BlackBerry API 4.0.2

append

public static StringBuffer append(StringBuffer strBuf,
                                  String str,
                                  int offset,
                                  int length)

Appends a subsection of a String to a StringBuffer.

Note this has the same affect as:

for(int i = 0; i < length; i++) strBuf.append( str.charAt(offset+i) );

Parameters:

strBuf - The string buffer to append the string to.

str - The string to append onto the string buffer.

offset - The offset (starting position) into the string of the subsection to append.

length - The number of characters to append.

Returns:

strBuf.

Throws:

StringIndexOutOfBoundsException - if one or both of offset or length is less than zero or if offset+length is greater than str.length().

NullPointerException - if any argument is null.

Since:

BlackBerry API 3.7.0

append

public static StringBuffer append(StringBuffer strBuf,
                                  byte[] buffer,
                                  int offset,
                                  int length)

Append a subsection of a byte array to a StringBuffer.

Note this has the same affect as:

for(int i = 0; i < length; i++) strBuf.append( buffer[offset+i] );

Parameters:

strBuf - The string buffer to append the byte array data to.

buffer - The byte array to append onto the string buffer.

offset - The offset into buffer of the subsection to append.

length - The number of bytes to append.

Returns:

strBuf.

Throws:

ArrayIndexOutOfBoundsException - if one or both of offset or length is less than zero or if offset+length is greater than buffer.length.

NullPointerException - if any argument is null.

Since:

BlackBerry API 3.7.0

append

public static StringBuffer append(StringBuffer strBuf,
                                  StringBuffer other)

Append a StringBuffer to another StringBuffer.

Parameters:

strBuf - The string buffer to append to.

other - The string buffer that will be appended to strBuf.

Returns:

strBuf.

Throws:

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.0.0

append

public static StringBuffer append(StringBuffer strBuf,
                                  StringBuffer other,
                                  int offset,
                                  int length)

Append a subsection of a StringBuffer to another StringBuffer.

Parameters:

strBuf - The string buffer to append to.

other - The string buffer whose subsection will be appended to strBuf.

offset - The offset into other of the subsection to append.

length - The number of characters to append.

Returns:

strBuf.

Throws:

NullPointerException - if any argument is null.

ArrayIndexOutOfBoundsException - if one or both of offset or length is less than zero or if offset+length is greater than other.length().

Since:

BlackBerry API 4.0.0

writeUTF

public static int writeUTF(String str,
                           DataOutput out)
                    throws IOException

Writes a string to the specified DataOutput using UTF-8 encoding in a machine-independent manner.

First, two bytes are written to out as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for the character. If no exception is thrown, the counter written is incremented by the total number of bytes written to the output stream. This will be at least two plus the length of str, and at most two plus thrice the length of str.

Parameters:

str - a string to be written.

out - destination to write to

Returns:

The number of bytes written out.

Throws:

IOException - if an I/O error occurs.

NullPointerException - if any argument is null.

Since:

BlackBerry API 4.1.0

copy

public static String[] copy(String[] array)

Retrieves a duplicate copy of a String array.

Parameters:

array - Array to copy.

Returns:

Copy of array.

Since:

BlackBerry API 6.0.0