StringUtilities (BlackBerry JDE 7.1.0 API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.util
Class StringUtilities

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

public final class StringUtilities
extends Object
extends Object

Utility methods for manipulating Strings.

Field Summary
`static int`	`COLLATE_FRENCH_ACCENTS` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_LEVEL_IDENTICAL` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_IGNORE_CASE` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_IGNORE_CASE_AND_ACCENTS` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_PRIMARY` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_QUATERNARY` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_SECONDARY` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_LEVEL_TERTIARY` A comparison level for the aLevel parameter to the compare function.
`static int`	`COLLATE_SPACE_NON_IGNORABLE` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_UPPERCASE_FIRST` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_VARIABLE_BLANKED` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_VARIABLE_NON_IGNORABLE` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_VARIABLE_SHIFTED` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_VARIABLE_SHIFT_TRIMMED` A bit value for the aFlags and aFlagsMask parameters to the compare function.
`static int`	`COLLATE_VARIABLE_TREATMENT_MASK` A bit value for the aFlagsMask parameter to the compare function.

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`	`compare(String aString1, int aOffset1, int aLength1, String aString2, int aOffset2, int aLength2, int aLevel, int aLocale, int aFlags, int aFlagsMask)` Compare two sub-strings, specifying the collation level, the locale and modifying flags.
`static int`	`compare(String aString1, String aString2, int aLevel, int aLocale)` Compare two strings, specifying the collation level and locale, making spaces non-ignorable and using the default treatment of ignorable (variable) elements.
`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)` Deprecated. This function will give poor or unusable results for most non-English locales because it ignores locale-dependent collation rules. Use compare with COLLATE_LEVEL_SECONDARY.
`static int`	`compareToIgnoreCase(String s1, String s2, int locale)` Deprecated. This function will give poor or unusable results for most non-English locales because it ignores locale-dependent collation rules. Use compare.
`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`	`pad(String string, char padding, int minLength)` Repeatedly adds a character to the beginning of a string until its length is at least a certain length.
`static String`	`pad(String string, char padding, int minLength, boolean padLeft)` Repeatedly adds a character to the beginning of a string until its length is at least a certain length.
`static String`	`quote(Object object)` Puts double quotes around the string representation of an object.
`static String`	`removeChars(String src, String remove)` Removes specified characters from a string.
`static boolean`	`startsWithIgnoreCase(String aString, String aPrefix)` Determines if target string begins with provided prefix.
`static boolean`	`startsWithIgnoreCaseAndAccents(String aString, String aPrefix)` Determines if target string begins with a provided prefix, ignoring 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 aString1, String aString2)` 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`

Field Detail

COLLATE_LEVEL_PRIMARY

public static int COLLATE_LEVEL_PRIMARY

A comparison level for the aLevel parameter to the compare function. Compare on basic character identity only. Ignore case and diacritics.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_IGNORE_CASE_AND_ACCENTS

public static int COLLATE_LEVEL_IGNORE_CASE_AND_ACCENTS

A comparison level for the aLevel parameter to the compare function. Compare on basic character identity only. Ignore case and diacritics.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_SECONDARY

public static int COLLATE_LEVEL_SECONDARY

A comparison level for the aLevel parameter to the compare function. Compare on basic character identity and diacritics. Ignore case.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_IGNORE_CASE

public static int COLLATE_LEVEL_IGNORE_CASE

A comparison level for the aLevel parameter to the compare function. Compare on basic character identity and diacritics. Ignore case.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_TERTIARY

public static int COLLATE_LEVEL_TERTIARY

A comparison level for the aLevel parameter to the compare function. Compare on basic character identity and diacritics, taking case into account.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_QUATERNARY

public static int COLLATE_LEVEL_QUATERNARY

A comparison level for the aLevel parameter to the compare function. The quaternary level uses the primary sort keys of normally ignored characters as quaternary keys. It has an effect only when the collation method uses the 'shifted' or 'shift-trimmed' treatment of variable keys.

Since:: BlackBerry API 7.0.0

COLLATE_LEVEL_IDENTICAL

public static int COLLATE_LEVEL_IDENTICAL

A comparison level for the aLevel parameter to the compare function. Compare on canonically normalised Unicode scalar values. This level is rarely worth using because for nearly all strings it will give the same result as the quaternary level.

Since:: BlackBerry API 7.0.0

COLLATE_VARIABLE_SHIFTED

public static int COLLATE_VARIABLE_SHIFTED

A bit value for the aFlags and aFlagsMask parameters to the compare function. Variable collation key treatment: shifted. See http://www.unicode.org/unicode/reports/tr10.

Since:: BlackBerry API 7.0.0

COLLATE_VARIABLE_BLANKED

public static int COLLATE_VARIABLE_BLANKED

A bit value for the aFlags and aFlagsMask parameters to the compare function. Variable collation key treatment: blanked. See http://www.unicode.org/unicode/reports/tr10.

Since:: BlackBerry API 7.0.0

COLLATE_VARIABLE_NON_IGNORABLE

public static int COLLATE_VARIABLE_NON_IGNORABLE

A bit value for the aFlags and aFlagsMask parameters to the compare function. Variable collation key treatment: non-ignorable. See http://www.unicode.org/unicode/reports/tr10.

Since:: BlackBerry API 7.0.0

COLLATE_VARIABLE_SHIFT_TRIMMED

public static int COLLATE_VARIABLE_SHIFT_TRIMMED

A bit value for the aFlags and aFlagsMask parameters to the compare function. Variable collation key treatment: trimmed. See http://www.unicode.org/unicode/reports/tr10.

Since:: BlackBerry API 7.0.0

COLLATE_VARIABLE_TREATMENT_MASK

public static int COLLATE_VARIABLE_TREATMENT_MASK

A bit value for the aFlagsMask parameter to the compare function. A mask to select the variable collation key bits.

Since:: BlackBerry API 7.0.0

COLLATE_FRENCH_ACCENTS

public static int COLLATE_FRENCH_ACCENTS

A bit value for the aFlags and aFlagsMask parameters to the compare function. Compare secondary keys in reverse order to implement French collation. It is not necessary to override this flag in the French locale because it is set by default.

Since:: BlackBerry API 7.0.0

COLLATE_UPPERCASE_FIRST

public static int COLLATE_UPPERCASE_FIRST

A bit value for the aFlags and aFlagsMask parameters to the compare function. Make upper-case sort before lower-case at level 3. The default is lower-case before upper-case.

Since:: BlackBerry API 7.0.0

COLLATE_SPACE_NON_IGNORABLE

public static int COLLATE_SPACE_NON_IGNORABLE

A bit value for the aFlags and aFlagsMask parameters to the compare function. Make space (U+0020) non-ignorable. The default is ignorable.

Since:: BlackBerry API 7.0.0

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)

Deprecated. This function will give poor or unusable results for most non-English locales because it ignores locale-dependent collation rules. Use compare with COLLATE_LEVEL_SECONDARY.

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 character 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)

Deprecated. This function will give poor or unusable results for most non-English locales because it ignores locale-dependent collation rules. Use compare.

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 character 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

compare

public static int compare(String aString1,
                          int aOffset1,
                          int aLength1,
                          String aString2,
                          int aOffset2,
                          int aLength2,
                          int aLevel,
                          int aLocale,
                          int aFlags,
                          int aFlagsMask)

Compare two sub-strings, specifying the collation level, the locale and modifying flags.

Parameters:: aString1 - first string to be compared; aOffset1 - starting position in the first string; aLength1 - length of text to be compared in the first string; aString1 - second string to be compared; aOffset1 - starting position in the second string; aLength1 - length of text to be compared in the second string; aLevel - the comparison level: one of the COLLATE_LEVEL_* constants; aLocale - the locale: a locale of zero causes the current locale to be used; a locale of -1 causes a standard non-locale-based collation method to be used; aFlags - overriding values for any flags selected by aFlagsMask; aFlagsMask - a mask to select flags to be overridden by aFlags
Returns:: negative if the first string is less than (lexically precedes) the second, zero if the strings are equal, or positive if the first string is greater than (lexically follows) the second. In detail: -2 is returned if the first string is less than the second but is not a prefix of it; -1 is returned if the first string is a prefix of the second string 1 is returned if the second string is a prefix of the first string 2 is returned if the second string is less than the first but is not a prefix of it.
Since:: BlackBerry API 7.0.0

compare

public static int compare(String aString1,
                          String aString2,
                          int aLevel,
                          int aLocale)

Compare two strings, specifying the collation level and locale, making spaces non-ignorable and using the default treatment of ignorable (variable) elements.

Parameters:: aString1 - first string to be compared; aString2 - second string to be compared; aLevel - the comparison level: one of the COLLATE_LEVEL_* constants; aLocale - the locale: a locale of zero causes the current locale to be used; a locale of -1 causes a standard non-locale-based collation method to be used
Returns:: negative if the first string is less than (lexically precedes) the second, zero if the strings are equal, or positive if the first string is greater than (lexically follows) the second. In detail: -2 is returned if the first string is less than the second but is not a prefix of it; -1 is returned if the first string is a prefix of the second string 1 is returned if the second string is a prefix of the first string 2 is returned if the second string is less than the first but is not a prefix of it.
Since:: BlackBerry API 7.0.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 aString,
                                           String aPrefix)

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 aString,
                                                     String aPrefix)

Determines if target string begins with a provided prefix, ignoring 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 aString1,
                                         String aString2)

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

Two null strings are considered equal.

Parameters:: aString1 - First string to compare.; aString2 - 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

pad

public static String pad(String string,
                         char padding,
                         int minLength)

Repeatedly adds a character to the beginning of a string until its length is at least a certain length. This is useful, for example, for zero-padding the string representation of an integer to be a certain length.

If the length of the given string is greater than or equal to the given minLength then this method does nothing and returns the given String object. Otherwise, a new String with a length equal to minLength that begins with the given padding character repeated and ends with the given string is returned.

For example:

pad("123", '0', 5) returns "00123"
pad("ABC", 'z', -1) returns "ABC"
pad("ABC", 'z', 6) returns "zzzABC"
pad(null, '0', 5) returns null

This method simply invokes StringUtilities.pad(String, char, int, boolean) with the given arguments and padLeft==true.

Parameters:: string - the string to pad; may be null; padding - the character to repeatedly add to the beginning of the string in order to bring it to the minimum length; minLength - the minimum length of the string to return; may be negative, which is treated as if it were 0 (zero)
Returns:: the given string padded to the given minimum length with the given padding character; returns null if and only if the given string is null
Since:: BlackBerry API 7.0.0

pad

public static String pad(String string,
                         char padding,
                         int minLength,
                         boolean padLeft)

For example:

pad("123", '0', 5, true) returns "00123"
pad("ABC", 'z', -1, true) returns "ABC"
pad("ABC", 'z', 6, true) returns "zzzABC"
pad(null, '0', 5, true) returns null
pad("123", '0', 5, false) returns "12300"
pad("ABC", 'z', -1, false) returns "ABC"
pad("ABC", 'z', 6, false) returns "ABCzzz"
pad(null, '0', 5, false) returns null

Parameters:: string - the string to pad; may be null; padding - the character to repeatedly add to the beginning of the string in order to bring it to the minimum length; minLength - the minimum length of the string to return; may be negative, which is treated as if it were 0 (zero); padLeft - if true the pad the left side of the string (starting at index 0); if false then pad the right side of the string (starting at string.length())
Returns:: the given string padded to the given minimum length with the given padding character; returns null if and only if the given string is null
Since:: BlackBerry API 7.0.0

quote

public static String quote(Object object)

Puts double quotes around the string representation of an object. This method is useful for formatting a string for display to a technical user in a log or test failure message.

If the given object is null then the 4-character string "null" is returned. Otherwise, the String returned from its toString() method is returned with a double quote character (") added to the beginning and the end. If the object's toString() method returns null then this method behaves as if the 4-character string "null" was returned from the toString() method. If the toString() method throws an exception then the string returned from the exception's toString() method is used, prepended with the fully-qualified class name.

Here are some examples:

Object Specified to `quote()`	Contents of String Returned from `quote()`
`"Hello"`	"Hello"
`"My Friend"`	"My Friend"
`new Integer(5)`	"5"
`null`	null
new Object() { public String toString() { return null; } }	"null"
new Object() { public String toString() { throw new RuntimeException("fail"); } }	"java.lang.RuntimeException: fail"

Parameters:: object - the object whose string representation to quote; may be null
Returns:: a newly-create string whose value is the quoted string representation of the given object, as defined above; never returns null
See Also:: Object.toString(), Throwable.toString()
Since:: BlackBerry API 7.0.0

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal

net.rim.device.api.util Class StringUtilities

COLLATE_LEVEL_PRIMARY

COLLATE_LEVEL_IGNORE_CASE_AND_ACCENTS

COLLATE_LEVEL_SECONDARY

COLLATE_LEVEL_IGNORE_CASE

COLLATE_LEVEL_TERTIARY

COLLATE_LEVEL_QUATERNARY

COLLATE_LEVEL_IDENTICAL

COLLATE_VARIABLE_SHIFTED

COLLATE_VARIABLE_BLANKED

COLLATE_VARIABLE_NON_IGNORABLE

COLLATE_VARIABLE_SHIFT_TRIMMED

COLLATE_VARIABLE_TREATMENT_MASK

COLLATE_FRENCH_ACCENTS

COLLATE_UPPERCASE_FIRST

COLLATE_SPACE_NON_IGNORABLE

convertToOriginal

toLowerCase

compareToIgnoreCase

compareToHandleSpecialChars

compareToIgnoreCase

compare

compare

toLowerCase

toUpperCase

computeHashCode

hashCodeIgnoreCase

hashCode

computeReverseLookupHashCodeString

computeReverseLookupHashCodeString

computeReverseLookupHashCodeBytes

computeReverseLookupHashCodeBytes

startsWithIgnoreCase

startsWithIgnoreCaseAndAccents

stringToWords

stringToKeywords

stringToWords

stringToKeywords

stringToWordsOrKeywords

stringToWords

stringToKeywords

strEqualIgnoreCase

strEqual

cStr2String

compareObjectToStringIgnoreCase

indexOf

indexOf

removeChars

stringHashToLong

append

append

append

append

writeUTF

copy

pad

pad

quote

net.rim.device.api.util
Class StringUtilities