String4D (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.lang.String4D

All Implemented Interfaces:

java.lang.CharSequence, java.lang.Comparable<String4D>
```
public final class String4D
extends java.lang.Object
implements java.lang.Comparable<String4D>, java.lang.CharSequence
```
String is an immutable array of characters.

IMPORTANT: the totalcross.lang package is the java.lang that will be used in the device. You CANNOT use nor import totalcross.lang package in desktop. When tc.Deploy is called, all references to java.lang are replaced by totalcross.lang automatically. Given this, you must use only the classes and methods that exists BOTH in java.lang and totalcross.lang. For example, you can't use java.lang.ClassLoader because there are no totalcross.lang.ClassLoader. Another example, you can't use java.lang.String.indexOfIgnoreCase because there are no totalcross.lang.String.indexOfIgnoreCase method. Trying to use a class or method from the java.lang package that has no correspondence with totalcross.lang will make the tc.Deploy program to abort, informing where the problem occured. A good idea is to always refer to this javadoc to know what is and what isn't available.

Constructor Summary

Constructors
Constructor and Description
`String4D()` Creates an empty string.
`String4D(byte[] value)` Creates a string from the given byte array.
`String4D(byte[] value, int offset, int count)` Creates a string from the given byte array.
`String4D(byte[] value, int offset, int count, java.lang.String encoding)`
`String4D(char[] c)` Creates a string from the given character array.
`String4D(char[] value, int offset, int count)` Allocates a new String that contains characters from a subarray of the character array argument.
`String4D(java.lang.CharSequence cs)`
`String4D(String4D s)` Creates a copy of the given string.
`String4D(StringBuffer4D buffer)` Creates a new String using the character sequence represented by the StringBuffer.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`char`	`charAt(int i)` Returns the character at the given position.
`int`	`compareTo(String4D s)` Compares this string with another lexicographically.
`int`	`compareToIgnoreCase(String4D str)` Compares this String and another String (case insensitive).
`String4D`	`concat(String4D s)` Concatenates the given string to this string and returns the result.
`boolean`	`contains(java.lang.CharSequence part)`
`boolean`	`contains(String4D part)`
`boolean`	`contentEquals(StringBuffer4D buffer)` Compares the given StringBuffer to this String.
`boolean`	`endsWith(String4D suffix)` Tests if this string ends with the specified suffix.
`boolean`	`equals(java.lang.Object obj)` Returns true if the given string is equal to this string and false otherwise.
`boolean`	`equalsIgnoreCase(String4D s)` Returns true if the given string is equal to this string using caseless comparison and false otherwise.
`byte[]`	`getBytes()` Return this String as bytes.
`byte[]`	`getBytes(java.nio.charset.Charset charset)`
`byte[]`	`getBytes(java.lang.String charsetName)`
`void`	`getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)` Copies characters from this String into the specified character array.
`int`	`hashCode()` Returns the hashcode for this string
`int`	`indexOf(int c)` Returns the index of the specified char in this string starting from 0, or -1 if not found
`int`	`indexOf(int c, int startIndex)` Returns the index of the specified char in this string, or -1 if not found
`int`	`indexOf(String4D c)` Returns the index of the specified string in this string, or -1 if not found or the index is invalid
`int`	`indexOf(String4D c, int startIndex)` Returns the index of the specified string in this string starting from the given index, or -1 if not found.
`boolean`	`isEmpty()` Returns true if, and only if, `length()` is `0`.
`int`	`lastIndexOf(int c)` Returns the last index of the specified char in this string starting from length-1, or -1 if not found
`int`	`lastIndexOf(int c, int startIndex)` Returns the last index of the specified char in this string, or -1 if not found
`int`	`lastIndexOf(String4D s)` Returns the last index of the specified string in this string starting from length-1, or -1 if not found.
`int`	`lastIndexOf(String4D s, int startIndex)` Returns the last index of the specified string in this string starting from the given starting index, or -1 if not found.
`int`	`length()` Returns the length of the string in characters.
`boolean`	`matches(java.lang.String regex)` Test if this String matches a regular expression.
`boolean`	`regionMatches(boolean ignoreCase, int toffset, String4D other, int ooffset, int len)` Predicate which determines if this String matches another String starting at a specified offset for each String and continuing for a specified length, optionally ignoring case.
`boolean`	`regionMatches(int toffset, String4D other, int ooffset, int len)` Predicate which determines if this String matches another String starting at a specified offset for each String and continuing for a specified length.
`String4D`	`replace(char oldChar, char newChar)` Returns a new String with the given oldChar replaced by the newChar
`java.lang.String`	`replace(java.lang.CharSequence targetcs, java.lang.CharSequence replacementcs)` Returns a string that is this string with all instances of the sequence represented by `target` replaced by the sequence in `replacement`.
`java.lang.String`	`replaceAll(java.lang.String regex, java.lang.String replacement)` Replaces all matching substrings of the regular expression with a given replacement.
`java.lang.String`	`replaceFirst(java.lang.String regex, java.lang.String replacement)` Replaces the first substring match of the regular expression with a given replacement.
`java.lang.String[]`	`split(java.lang.String regex)` Split this string around the matches of a regular expression.
`boolean`	`startsWith(String4D prefix)` Tests if this string starts with the specified prefix.
`boolean`	`startsWith(String4D prefix, int from)` Tests if this string starts with the specified prefix.
`java.lang.CharSequence`	`subSequence(int beginIndex, int endIndex)`
`String4D`	`substring(int start)` Returns a substring starting from start to the end of the string.
`String4D`	`substring(int start, int end)` Returns a substring of the string.
`char[]`	`toCharArray()` Returns this string as a character array.
`String4D`	`toLowerCase()` Returns a new instance of this string converted to lower case
`String4D`	`toString4D()` Returns this string.
`String4D`	`toUpperCase()` Returns a new instance of this string converted to upper case
`String4D`	`trim()` Removes characters less than or equal to ' ' (space) from the beginning and end of this String
`static java.lang.String`	`valueOf(boolean b)` Converts the given boolean to a String (in lowercase).
`static String4D`	`valueOf(char c)` Converts the given char to a String.
`static String4D`	`valueOf(char[] data)` Returns a String representation of a character array.
`static String4D`	`valueOf(char[] data, int offset, int count)` Returns a String representing the character sequence of the char array, starting at the specified offset, and copying chars up to the specified count.
`static String4D`	`valueOf(double d)` Converts the given double to a String.
`static String4D`	`valueOf(int i)` Converts the given int to a String.
`static java.lang.String`	`valueOf(long l)` Converts the given long value to a String.
`static java.lang.String`	`valueOf(java.lang.Object obj)` Returns the string representation of the given object.

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

Methods inherited from interface java.lang.CharSequence
chars, codePoints, toString

- Constructor Detail
  - String4D
```
public String4D()
```
    Creates an empty string.
  - String4D
```
public String4D(java.lang.CharSequence cs)
```
  - String4D
```
public String4D(String4D s)
```
    Creates a copy of the given string.
  - String4D
```
public String4D(char[] c)
```
    Creates a string from the given character array.
  - String4D
```
public String4D(char[] value,
                int offset,
                int count)
```
    Allocates a new String that contains characters from a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string.
    
    Parameters:
    
    value - array that is the source of characters.
    
    offset - the initial offset.
    
    count - the length.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - If the offset and count arguments index characters outside the bounds of the value array.
  - String4D
```
public String4D(byte[] value,
                int offset,
                int count)
```
    Creates a string from the given byte array. The bytes are converted to char using the CharacterConverter associated in the charConverter member of totalcross.sys.Convert.
    
    See Also:
    
    Convert.setDefaultConverter(String), CharacterConverter, UTF8CharacterConverter
  - String4D
```
public String4D(byte[] value,
                int offset,
                int count,
                java.lang.String encoding)
         throws java.io.UnsupportedEncodingException
```
    Throws:
    
    java.io.UnsupportedEncodingException
  - String4D
```
public String4D(byte[] value)
```
    Creates a string from the given byte array. The bytes are converted to char using the CharacterConverter associated in the charConverter member of totalcross.sys.Convert.
    
    See Also:
    
    Convert.setDefaultConverter(String), CharacterConverter, UTF8CharacterConverter
  - String4D
```
public String4D(StringBuffer4D buffer)
```
    Creates a new String using the character sequence represented by the StringBuffer. Subsequent changes to buf do not affect the String.
    
    Parameters:
    
    buffer - StringBuffer to copy
    
    Throws:
    
    java.lang.NullPointerException - if buffer is null
- Method Detail
  - length
```
public int length()
```
    Returns the length of the string in characters.
    
    Specified by:
    
    length in interface java.lang.CharSequence
  - charAt
```
public char charAt(int i)
```
    Returns the character at the given position.
    
    Specified by:
    
    charAt in interface java.lang.CharSequence
  - concat
```
public String4D concat(String4D s)
```
    Concatenates the given string to this string and returns the result.
  - toCharArray
```
public char[] toCharArray()
```
    Returns this string as a character array. The array returned is allocated by this method and is a copy of the string's internal character array.
  - toString4D
```
public String4D toString4D()
```
    Returns this string.
  - valueOf
```
public static java.lang.String valueOf(java.lang.Object obj)
```
    Returns the string representation of the given object.
  - substring
```
public String4D substring(int start,
                          int end)
```
    Returns a substring of the string. The start value is included but the end value is not. That is, if you call:
```
 string.substring(4, 6);
 
```
    a string created from characters 4 and 5 will be returned.
    Parameters:
    
    start - the first character of the substring
    
    end - the character after the last character of the substring
  - substring
```
public String4D substring(int start)
```
    Returns a substring starting from start to the end of the string.
    
    Parameters:
    
    start - the first character of the substring
  - startsWith
```
public boolean startsWith(String4D prefix,
                          int from)
```
    Tests if this string starts with the specified prefix.
    
    Parameters:
    
    prefix - the prefix.
    
    from - where to begin looking in the string.
    
    Returns:
    
    true if the character sequence represented by the argument is a prefix of the substring of this object starting at index toffset; false otherwise.
  - startsWith
```
public boolean startsWith(String4D prefix)
```
    Tests if this string starts with the specified prefix.
    
    Parameters:
    
    prefix - the prefix.
    
    Returns:
    
    true if the character sequence represented by the argument is a prefix of the character sequence represented by this string; false otherwise.
  - endsWith
```
public boolean endsWith(String4D suffix)
```
    Tests if this string ends with the specified suffix.
    
    Parameters:
    
    suffix - the suffix.
    
    Returns:
    
    true if the character sequence represented by the argument is a suffix of the character sequence represented by this object; false otherwise.
  - equalsIgnoreCase
```
public boolean equalsIgnoreCase(String4D s)
```
    Returns true if the given string is equal to this string using caseless comparison and false otherwise.
  - replace
```
public String4D replace(char oldChar,
                        char newChar)
```
    Returns a new String with the given oldChar replaced by the newChar
  - lastIndexOf
```
public int lastIndexOf(int c,
                       int startIndex)
```
    Returns the last index of the specified char in this string, or -1 if not found
  - lastIndexOf
```
public int lastIndexOf(int c)
```
    Returns the last index of the specified char in this string starting from length-1, or -1 if not found
  - lastIndexOf
```
public int lastIndexOf(String4D s)
```
    Returns the last index of the specified string in this string starting from length-1, or -1 if not found.
    CAUTION: this method does not exist in BlackBerry, so if you use it, your program will fail in Blackberry.
  - lastIndexOf
```
public int lastIndexOf(String4D s,
                       int startIndex)
```
    Returns the last index of the specified string in this string starting from the given starting index, or -1 if not found.
    CAUTION: this method does not exist in BlackBerry, so if you use it, your program will fail in Blackberry.
  - trim
```
public String4D trim()
```
    Removes characters less than or equal to ' ' (space) from the beginning and end of this String
  - getChars
```
public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)
```
    Copies characters from this String into the specified character array. The characters of the specified substring (determined by srcBegin and srcEnd) are copied into the character array, starting at the array's dstBegin location.
    
    Parameters:
    
    srcBegin - index of the first character in the string
    
    srcEnd - end of the characters that are copied
    
    dst - the destination array
    
    dstBegin - the start offset in the destination array
    
    Since:
    
    SuperWaba 2.0
  - getBytes
```
public byte[] getBytes()
```
    Return this String as bytes. The chars are converted to byte using the CharacterConverter associated in the charConverter member of totalcross.sys.Convert.
    
    Since:
    
    SuperWaba 2.0 beta 4
    
    See Also:
    
    Convert.setDefaultConverter(String), CharacterConverter, UTF8CharacterConverter
  - getBytes
```
public byte[] getBytes(java.nio.charset.Charset charset)
```
  - getBytes
```
public byte[] getBytes(java.lang.String charsetName)
                throws java.io.UnsupportedEncodingException
```
    Throws:
    
    java.io.UnsupportedEncodingException
  - toUpperCase
```
public String4D toUpperCase()
```
    Returns a new instance of this string converted to upper case
  - toLowerCase
```
public String4D toLowerCase()
```
    Returns a new instance of this string converted to lower case
  - indexOf
```
public int indexOf(String4D c)
```
    Returns the index of the specified string in this string, or -1 if not found or the index is invalid
  - valueOf
```
public static java.lang.String valueOf(long l)
```
    Converts the given long value to a String.
  - valueOf
```
public static java.lang.String valueOf(boolean b)
```
    Converts the given boolean to a String (in lowercase).
  - valueOf
```
public static String4D valueOf(double d)
```
    Converts the given double to a String.
  - valueOf
```
public static String4D valueOf(char c)
```
    Converts the given char to a String.
  - valueOf
```
public static String4D valueOf(int i)
```
    Converts the given int to a String.
  - indexOf
```
public int indexOf(int c)
```
    Returns the index of the specified char in this string starting from 0, or -1 if not found
  - indexOf
```
public int indexOf(int c,
                   int startIndex)
```
    Returns the index of the specified char in this string, or -1 if not found
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Returns true if the given string is equal to this string and false otherwise. If the object passed is not a string, false is returned.
    
    Overrides:
    
    equals in class java.lang.Object
  - compareTo
```
public int compareTo(String4D s)
```
    Compares this string with another lexicographically.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<String4D>
    
    Returns:
    
    0 if the strings match, a value < 0 if this string is lexicographically less than the string argument; and > 0 if visa-versa.
  - indexOf
```
public int indexOf(String4D c,
                   int startIndex)
```
    Returns the index of the specified string in this string starting from the given index, or -1 if not found.
  - hashCode
```
public int hashCode()
```
    Returns the hashcode for this string
    
    Overrides:
    
    hashCode in class java.lang.Object
  - contains
```
public boolean contains(String4D part)
```
  - contains
```
public boolean contains(java.lang.CharSequence part)
```
  - contentEquals
```
public boolean contentEquals(StringBuffer4D buffer)
```
    Compares the given StringBuffer to this String. This is true if the StringBuffer has the same content as this String at this moment.
    
    Parameters:
    
    buffer - the StringBuffer to compare to
    
    Returns:
    
    true if StringBuffer has the same character sequence
    
    Throws:
    
    java.lang.NullPointerException - if the given StringBuffer is null
    
    Since:
    
    1.4
  - compareToIgnoreCase
```
public int compareToIgnoreCase(String4D str)
```
    Compares this String and another String (case insensitive). This comparison is similar to equalsIgnoreCase, in that it ignores locale and multi-characater capitalization, and compares characters after performing Character.toLowerCase(Character.toUpperCase(c)) on each character of the string.
    
    Parameters:
    
    str - the string to compare against
    
    Returns:
    
    the comparison
    
    Since:
    
    1.2
    
    See Also:
    
    Collator.compare(String, String)
  - regionMatches
```
public boolean regionMatches(int toffset,
                             String4D other,
                             int ooffset,
                             int len)
```
    Predicate which determines if this String matches another String starting at a specified offset for each String and continuing for a specified length. Indices out of bounds are harmless, and give a false result.
    
    Parameters:
    
    toffset - index to start comparison at for this String
    
    other - String to compare region to this String
    
    ooffset - index to start comparison at for other
    
    len - number of characters to compare
    
    Returns:
    
    true if regions match (case sensitive)
    
    Throws:
    
    java.lang.NullPointerException - if other is null
  - regionMatches
```
public boolean regionMatches(boolean ignoreCase,
                             int toffset,
                             String4D other,
                             int ooffset,
                             int len)
```
    Predicate which determines if this String matches another String starting at a specified offset for each String and continuing for a specified length, optionally ignoring case. Indices out of bounds are harmless, and give a false result. Case comparisons are based on Character.toLowerCase() and Character.toUpperCase(), not on multi-character capitalization expansions.
    
    Parameters:
    
    ignoreCase - true if case should be ignored in comparision
    
    toffset - index to start comparison at for this String
    
    other - String to compare region to this String
    
    ooffset - index to start comparison at for other
    
    len - number of characters to compare
    
    Returns:
    
    true if regions match, false otherwise
    
    Throws:
    
    java.lang.NullPointerException - if other is null
  - matches
```
public boolean matches(java.lang.String regex)
```
    Test if this String matches a regular expression. This is shorthand for Pattern.matches(regex, this).
    
    Parameters:
    
    regex - the pattern to match
    
    Returns:
    
    true if the pattern matches
    
    Throws:
    
    java.lang.NullPointerException - if regex is null
    
    PatternSyntaxException - if regex is invalid
  - replaceFirst
```
public java.lang.String replaceFirst(java.lang.String regex,
                                     java.lang.String replacement)
```
    Replaces the first substring match of the regular expression with a given replacement. This is shorthand for Pattern .compile(regex).matcher(this).replaceFirst(replacement).
    
    Parameters:
    
    regex - the pattern to match
    
    replacement - the replacement string
    
    Returns:
    
    the modified string
    
    Throws:
    
    java.lang.NullPointerException - if regex or replacement is null
    
    PatternSyntaxException - if regex is invalid
    
    See Also:
    
    replaceAll(String, String), Pattern.compile(String)
  - replaceAll
```
public java.lang.String replaceAll(java.lang.String regex,
                                   java.lang.String replacement)
```
    Replaces all matching substrings of the regular expression with a given replacement. This is shorthand for Pattern .compile(regex).matcher(this).replaceAll(replacement).
    
    Parameters:
    
    regex - the pattern to match
    
    replacement - the replacement string
    
    Returns:
    
    the modified string
    
    Throws:
    
    java.lang.NullPointerException - if regex or replacement is null
    
    PatternSyntaxException - if regex is invalid
    
    See Also:
    
    Pattern.compile(String)
  - split
```
public java.lang.String[] split(java.lang.String regex)
```
    Split this string around the matches of a regular expression. Each element of the returned array is the largest block of characters not terminated by the regular expression, in the order the matches are found. The array length is unlimited, and trailing empty entries are discarded, as though calling split(regex, 0).
    
    Parameters:
    
    regex - the pattern to match
    
    Returns:
    
    the array of split strings
    
    Throws:
    
    java.lang.NullPointerException - if regex or replacement is null
    
    PatternSyntaxException - if regex is invalid
    
    See Also:
    
    Pattern.compile(String)
  - valueOf
```
public static String4D valueOf(char[] data)
```
    Returns a String representation of a character array. Subsequent changes to the array do not affect the String.
    
    Parameters:
    
    data - the character array
    
    Returns:
    
    a String containing the same character sequence as data
    
    Throws:
    
    java.lang.NullPointerException - if data is null
    
    See Also:
    
    valueOf(char[], int, int)
  - valueOf
```
public static String4D valueOf(char[] data,
                               int offset,
                               int count)
```
    Returns a String representing the character sequence of the char array, starting at the specified offset, and copying chars up to the specified count. Subsequent changes to the array do not affect the String.
    
    Parameters:
    
    data - character array
    
    offset - position (base 0) to start copying out of data
    
    count - the number of characters from data to copy
    
    Returns:
    
    String containing the chars from data[offset..offset+count]
    
    Throws:
    
    java.lang.NullPointerException - if data is null
    
    java.lang.IndexOutOfBoundsException - if (offset < 0 || count < 0 || offset + count > data.length) (while unspecified, this is a StringIndexOutOfBoundsException)
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if, and only if, length() is 0.
    
    Returns:
    
    true if the length of the string is zero.
    
    Since:
    
    1.6
  - replace
```
public java.lang.String replace(java.lang.CharSequence targetcs,
                                java.lang.CharSequence replacementcs)
```
    Returns a string that is this string with all instances of the sequence represented by target replaced by the sequence in replacement.
    
    Parameters:
    
    target - the sequence to be replaced
    
    replacement - the sequence used as the replacement
    
    Returns:
    
    the string constructed as above
  - subSequence
```
public java.lang.CharSequence subSequence(int beginIndex,
                                          int endIndex)
```
    Specified by:
    
    subSequence in interface java.lang.CharSequence

Class String4D

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.CharSequence

Constructor Detail

String4D

String4D

String4D

String4D

String4D

String4D

String4D

String4D

String4D

Method Detail

length

charAt

concat

toCharArray

toString4D

valueOf

substring

substring

startsWith

startsWith

endsWith

equalsIgnoreCase

replace

lastIndexOf

lastIndexOf

lastIndexOf

lastIndexOf

trim

getChars

getBytes

getBytes

getBytes

toUpperCase

toLowerCase

indexOf

valueOf

valueOf

valueOf

valueOf

valueOf

indexOf

indexOf

equals

compareTo

indexOf

hashCode

contains

contains

contentEquals

compareToIgnoreCase

regionMatches

regionMatches

matches

replaceFirst

replaceAll

split

valueOf

valueOf

isEmpty

replace

subSequence