Class String
A text string is a sequence of characters written with quotes.
You can use single or double quotes, but they must always come in pairs. Quotes can also be nested, by alternating between single and double quotes.Examples
String myCompany = "SuperOffice";
String myLocation = 'Oslo';
String onion = "The 'onion' has many layers.";Constructors
String()
Default constructor.
Declaration
String String()| Type | Description |
| String | A new String object. |
String(String)
Pass a value to copy into a new object.
Declaration
String String(String value)Examples
String squash = "yellow crook neck";
String favSquash = String(squash);
String winterSquash = String("butternut");
printLine("Summer favorite: " + favSquash + "\nFall favorite: " + winterSquash);Parameters
| Type | Name | Description |
| String | value | The text to copy into the new object. |
| Type | Description |
| String | A new String object. |
String(Byte[])
Pass a byte array to build a new object.
Declaration
String String(Byte[] byteArray)Examples
String fallTreat = "Roasted pumpkin seeds are awesome";
Byte[] secret = fallTreat.toByteArray();
String jackO = String(secret);
printLine(jackO);Parameters
| Type | Name | Description |
| Byte[] | byteArray | The bytes to copy into the new object. |
| Type | Description |
| String | A new String object. |
String(Byte[], String)
Same as String(Byte[]), but also takes a code page identifier.
Declaration
String String(Byte[] byteArray, String codePage)Parameters
| Type | Name | Description |
| Byte[] | byteArray | The bytes to copy into the new object. |
| String | codePage | Code page identifier. |
| Type | Description |
| String | A new String object. |
String(NSStream)
Pass a byte array to build a new object.
Declaration
String String(NSStream stream)Examples
String hot = "Ghost";
NSStream stream = decodeBase64AsStream(encodeBase64(hot.toByteArray()));
String hotPepper = String(stream);
printLine("Insanely hot chili pepper: " + hotPepper);Parameters
| Type | Name | Description |
| NSStream | stream | The bytes to copy into the new object. |
| Type | Description |
| String | A new String object. |
String(NSStream, String)
Same as String(NSStream), but also takes a code page identifier.
Declaration
String String(Byte[] stream, String codePage)Parameters
| Type | Name | Description |
| NSStream | stream | The bytes to copy into the new object. |
| String | codePage | Code page identifier. |
| Type | Description |
| String | A new String object. |
Methods
getLength()
Finds the length of a string. Returns the number of characters as an Integer.
Declaration
Integer getLength()Examples
String txt = "Wergelandsveien";
printLine(txt.getLength().toString());Returns
| Type | Description |
| Integer | The number of characters in the String. |
toLower()
Converts the string to its lowercase representation (all lowercase).
Declaration
String toLower()Examples
String s = "SuperOffice";
String sLow = s.toLower();Returns
| Type | Description |
| String | The lowercase representation of the String. |
toUpper()
Converts the string to its uppercase representation (all uppercase).
Declaration
String toUpper()Examples
String s = "SuperOffice";
String sUp = s.toUpper();Returns
| Type | Description |
| String | The string in uppercase characters. |
isLower()
Determines if the string contains only lowercase letters. Will return true if no uppercase letters are found, otherwise false.
Declaration
Bool isLower()Returns
| Type | Description |
| Bool | True if the string contains only lowercase letters. |
isUpper()
Determines if the string contains only uppercase letters. Will return true if no lowercase letters are found, otherwise false.
Declaration
Bool isUpper()Returns
| Type | Description |
| Bool | True if the string contains only uppercase letters. |
equals(String)
Compare two string a returns true if they are equal.
Declaration
Bool equals(String value)Examples
String s1 = "apple";
String s2 = "Apple";
if (s1.equals(s2))
print(s1 + " is identical to " + s2);
else
print(s1 + " differs from " + s2);Parameters
| Type | Name | Description |
| String | value | The string to compare with. |
Returns
| Type | Description |
| Bool | True if they are equal. |
equalsIgnoreCase(String)
Same as using toLower() on both strings before calling equals().
Declaration
Bool equalsIgnoreCase(String value)Examples
String s1 = "apple";
String s2 = "Apple";
if (s1.equalsIgnoreCase(s2))
print(s1 + " is identical to " + s2);
else
print(s1 + " differs from " + s2);Parameters
| Type | Name | Description |
| String | value | The string to compare with. |
Returns
| Type | Description |
| Bool | True if the strings are equal. |
beginsWith(String)
Matching start of a string. The pattern you wish to match against must be given as an input parameter.
The methods will return true if the beginning of your string matches the pattern, otherwise false.Declaration
Bool beginsWith(String substring)Examples
String s1 = "apple";
String s2 = "appletree";
if (s2.beginsWith(s1))
print(s2 + " begins with " + s1);
else
print("No match found.");Parameters
| Type | Name | Description |
| String | substring | The pattern you wish to match against. |
Returns
| Type | Description |
| Bool | True if the string object begins with the string given as the parameter, taking the case into account. |
caseBeginsWith(String)
Matching start of a string. The pattern you wish to match against must be given as an input parameter.
The methods will return true if the beginning of your string matches the pattern, otherwise false.Declaration
Bool caseBeginsWith(String substring)Parameters
| Type | Name | Description |
| String | substring | The pattern you wish to match against. |
Returns
| Type | Description |
| Bool | True if the string object begins with the string given as the parameter, regardless of the case. |
endsWith(String)
Matching end of a string. The pattern you wish to match against must be given as an input parameter.
The methods will return true if the end of your string matches the pattern, otherwise false.Declaration
Bool endsWith(String substring)Examples
String s1 = "dog";
String s2 = "hotdog";
if (s2.endsWith(s1))
print(s2 + " ends with " + s1);
else
print("No match found.");Parameters
| Type | Name | Description |
| String | substring | The pattern you wish to match against. |
Returns
| Type | Description |
| Bool | True if the string object ends with the string given as the parameter taking the case into account. |
caseEndsWith(String)
Matching end of a string. The pattern you wish to match against must be given as an input parameter.
The methods will return true if the end of your string matches the pattern, otherwise false.Declaration
Bool caseEndsWith(String substring)Parameters
| Type | Name | Description |
| String | substring | The pattern you wish to match against. |
Returns
| Type | Description |
| Bool | True if the string object ends with the string given as the parameter regardless of case. |
compare(String)
Two strings are lexicographic identical if they are the same length and they also contain the same characters in the same position.
Declaration
Integer compare(String value)Examples
String s1 = "a";
String s2 = "B";
if (s1.compare(s2) < 0)
print(s1 + " comes before " + s2);Parameters
| Type | Name | Description |
| String | value | The string to compare with (s2). |
Returns
| Type | Description |
| Integer | <0 if this is lexically smaller than the value, 0 if equal, and >0 if this is lexically larger. |
caseCompare(String)
Same as applying the standard dictionary or alphabetic order.
Declaration
Integer caseCompare(String value)Examples
String s1 = "a";
String s2 = "B";
Integer sortOrder = s1.caseCompare(s2);Parameters
| Type | Name | Description |
| String | value | The string to compare with (s2). |
Returns
| Type | Description |
| Integer | <0 if this is lexically smaller than the value, 0 if equal, and >0 if this is lexically larger. |
append(String)
Concatenates two strings and alters the original string.
Declaration
Void append(String value)Examples
s1 = s1 + s2;
s1 += s2;
s1.append(s2);Parameters
| Type | Name | Description |
| String | value | The string to append to your original string. |
Returns
| Type | Description |
| Void |
append(String)
Concatenates an ISO-8859-1 (Latin-1) character to the original string.
Declaration
Void append(Byte character)Parameters
| Type | Name | Description |
| Byte | character | The ISO-8859-1 (Latin-1) character to append to your original string. |
Returns
| Type | Description |
| Void |
substitute(String, String)
Inside your string, substitute all occurrences of one substring with another.
Declaration
String substitute(String src, String dest)Examples
String s = "Superoffice";
print(s.substitute("o","O"));Parameters
| Type | Name | Description |
| String | src | The string to search for and replace. |
| String | dest | The string to replace with. |
Returns
| Type | Description |
| String | The altered string. |
find(String)
Finds the 1st occurrence of the substring and returns the index it starts at.
Declaration
Integer find(String substring)Examples
String s = "SuperOffice";
printLine(s.find("O").toString());Parameters
| Type | Name | Description |
| String | substring | The string to find. |
Returns
| Type | Description |
| Integer | First index of the substring. |
findCase(String)
Finds the 1st occurrence of the substring and returns the index it starts at. Returns -1 if not found.
Declaration
Integer findCase(String substring)Parameters
| Type | Name | Description |
| String | substring | The string to find. |
Returns
| Type | Description |
| Integer | First index of the substring or -1. |
findLast(String)
Same as find() except it will return the position of the last occurrence of the pattern.
Declaration
Integer find(String substring)Examples
String s = "SuperOffice";
printLine(s.find("O").toString());Parameters
| Type | Name | Description |
| String | substring | The string to find. |
Returns
| Type | Description |
| Integer | The position of the last occurrence of the string to match. |
subString(Integer, Integer)
Creates a new String of a given length. It will copy characters from the original string starting at the given position.
Declaration
String subString(Integer pos, Integer len)Examples
String s = "SuperOffice";
String t = s.subString(5,6);
print(t);Parameters
| Type | Name | Description |
| Integer | pos | The position in the original string to start copy characters from. |
| Integer | len | The length of the new string. |
Returns
| Type | Description |
| String | The substring. |
until(String)
If you don't know the exact segment length you wish to extract, one option is to copy from start until you encounter a given pattern (1st occurrence).
If the pattern is not found, a copy of this original string is returned.Declaration
String until(String pattern)Examples
String s = "name := test";
String t = s.until(":=");
print(t);Parameters
| Type | Name | Description |
| String | pattern | The pattern where to stop copying (the terminator). |
Returns
| Type | Description |
| String | The first part of the string. |
before(String)
Same usage and result as until().
Declaration
String before(String pattern)Parameters
| Type | Name | Description |
| String | pattern | The pattern where to stop copying. |
Returns
| Type | Description |
| String | The part of the string preceding the search text. |
beforeLast(String)
Similar to before(), but will continue copying until the last occurrence of the pattern rather than stopping at the 1st.
Useful for example if you are parsing a path or URI and want everything except the document name.Declaration
String beforeLast(String pattern)Examples
String s = "https://community.superoffice.com/sdk-doc/Reference.htm";
String t = s.beforeLast("/");Parameters
| Type | Name | Description |
| String | pattern | The pattern where to stop copying. |
Returns
| Type | Description |
| String | A string consisting of all the contents before the last needle. |
after(String)
Another option is to start copying after you encounter the pattern and continue extracting until you reach the end of the original string.
If the pattern is not found in this, an empty string is returned.Declaration
String after(String pattern)Examples
String s = "name := value";
String t = s.after(":=");
print(t);Parameters
| Type | Name | Description |
| String | pattern | The patter where to start copying. |
Returns
| Type | Description |
| String | What follows the pattern. |
afterLast(String)
Similar to after(), but will not start copying until after the last occurrence of the pattern rather than starting after the 1st.
Declaration
String afterLast(String pattern)Parameters
| Type | Name | Description |
| String | pattern | The patter where to start copying. |
Returns
| Type | Description |
| String | The last part of the string after the last match. |
split(String)
Splits the original string in multiple segments (an array of substrings). The original string is not altered.
Declaration
String[] split(String delimiter)Examples
String s = "Live now; make now always the most precious time. Now will never come again.";
String[] a = s.split(" ");Parameters
| Type | Name | Description |
| String | delimiter | Where to split the string. |
Returns
| Type | Description |
| String[] | Array of substrings. |
isAlpha()
Determines if the string exclusively contains uppercase and lowercase letters. Will return true if the restriction applies, otherwise false.
Declaration
Bool isAlpha()Examples
String s = "SuperOffice";
print(s.isAlpha().toString())Returns
| Type | Description |
| Bool | True if the string contains only alphabetic characters. |
isDigit()
Determines if the string contains numeric characters [0-9] only.
Declaration
Bool isDigit()Returns
| Type | Description |
| Bool | True if the string contains only numeric characters [0-9]. |
isAlphanumeric()
Combines the criteria of isAlpha() and isDigit(), and will return true if the string is restricted to any combination of lowercase and uppercase letters and digits [0-9].
Declaration
Bool isAlphanumeric()Returns
| Type | Description |
| Bool | True if the string contains only alphabetic characters or digits. |
isNull()
Returns true if the string is NULL/NUL/NIL, otherwise false. See example for isEmpty().
Declaration
Bool isNull()Returns
| Type | Description |
| Bool | True if the string is NULL/NUL/NIL. |
isEmpty()
Returns true if the string is empty ("") or NULL/NUL/NIL, meaning it contains no characters.
Declaration
Bool isEmpty()Examples
String s;
printLine(s.isNull().toString());
s = "";
printLine(s.isNull().toString());
printLine(s.isEmpty().toString());Returns
| Type | Description |
| Bool | True if the String contains no characters. |
toBool()
Converts a String to its boolean representation. Returns false if the String "1" or "True", otherwise true.
Declaration
Bool toBool()Examples
String s = "1";
s.toBool();Returns
| Type | Description |
| Bool |
toInteger()
Converts a String to its numeric representation.
Declaration
Integer toInteger()Returns
| Type | Description |
| Integer |
toFloat()
Converts a String to a Float.
Declaration
Float toFloat()Examples
String s = "150,3";
s.toFloat();Returns
| Type | Description |
| Float | The float value of a string. |
toDate()
Converts a String to a Date.
Declaration
Date toDate()Returns
| Type | Description |
| Date | The date value of a string. |
toDateTime()
Converts a String to a DateTime.
Declaration
DateTime toDateTime()Returns
| Type | Description |
| DateTime | The DateTime value of a string. |
toTime()
Converts a String to a Time object.
Declaration
Time toTime()Returns
| Type | Description |
| Time | The time value of a string. |
toByteArray()
Converts a String to an array of bytes (ISO-8859-1).
Declaration
Byte[] toByteArray()Returns
| Type | Description |
| Byte[] | An array of bytes (the string is converted to ISO-8859-1) |
escape(String)
Escape special characters of a string. Special characters are given as a parameter.
Declaration
String escape(String chars)Parameters
| Type | Name | Description |
| String | chars | Special characters which will be escaped with a backslash. |
Returns
| Type | Description |
| String | The escaped coded string. |
extractHtmlBody(Bool)
Extracts the body content of a string containing an HTML document. If the convertBodyToDiv parameter is true, the body tag will be replaced with a div tag.
Declaration
String extractHtmlBody(Bool convertBodyToDiv)Parameters
| Type | Name | Description |
| Bool | convertBodyToDiv | Replace the body tag with a div tag? |
Returns
| Type | Description |
| String | The body content of a string containing an HTML document |
extractHtmlHead(Bool)
Extracts the head content of a string containing an HTML document. If the stripTitle parameter is true, the title tag will be excluded.
Declaration
String extractHtmlHead(Bool stripTitle)Parameters
| Type | Name | Description |
| Bool | stripTitle | Omit the title tag? |
Returns
| Type | Description |
| String | The head content of a string containing an HTML document |
isHtmlDocument()
Tests if this string is an HTML document. The test is not fool-proof, but rather a simple test if the string begins with one of the standard opening tags for HTML documents.
Declaration
Bool isHtmlDocument()Returns
| Type | Description |
| Bool | True if HTML-document, otherwise false. |
htmlDecode()
HTML decode the string.
Declaration
String htmlDecode()Returns
| Type | Description |
| String | An HTML decoded version of the String. |
htmlEncode()
HTML encode the string.
Declaration
String htmlEncode()Returns
| Type | Description |
| String | An HTML encoded version of the String. |
getEmails()
Returns an array of the names and email addresses in a String.
Format: a comma-separated list of "name">emailAddr>Declaration
Vector getEmails()Returns
| Type | Description |
| Vector | Vector of names and emails. |
isValidEmail()
Checks if the string is a valid email address.
Declaration
Bool isValidEmail()Returns
| Type | Description |
| Bool | True if the string is a valid email address. |
getLine()
This function will return and remove a line from this string. It is normally used to process a longer text, stored in a string, in a line-wise fashion.
The newline is returned as well. If there are not any newlines, then this whole string is returned, and this string is set to empty.Declaration
String getLine()Returns
| Type | Description |
| String | The first line of the string. |
getWord(Integer)
Returns the word at a given position from the string.
Declaration
String getWord(Integer pos)Examples
String(" this is a test")`.getWord(1)Parameters
| Type | Name | Description |
| Integer | pos | The position of the word to get. |
Returns
| Type | Description |
| String | The word at the given position. |
isNumber()
Returns true if it is possible to convert a string to an integer. If the string begins with a number it is possible to convert until an illegal character occurs.
Declaration
Bool isNumber()Examples
//Returns true
printLine(String("123").isNumber().toString());
//Returns true, conversion to Integer will return 123
printLine(String("123nok").isNumber().toString());
//Returns false
printLine(String("nok123").isNumber().toString());
//Returns true, conversion to Integer will return 12
printLine(String("12nok3").isNumber().toString());Returns
| Type | Description |
| Bool | True if the string can be converted to an integer, false otherwise. |
urlDecode()
URL-decode the string.
Declaration
String urlDecode()Returns
| Type | Description |
| String | A URL decoded version of the String. |
urlEncode()
URL-encode the string.
Declaration
String urlEncode()Returns
| Type | Description |
| String | A URL encoded version of the String. |
utf8Decode()
Returns a UTF-8 decoded string, possibly containing characters outside the character space of ISO-8859-1 (Latin-1).
Declaration
String utf8Decode()Returns
| Type | Description |
| String |
utf8Encode()
The characters are coded using the UTF-8 format, and the string returned consists of only ASCII characters, encoding the Unicode characters (outside ASCII/Latin-1) in UTF-8 format.
Declaration
String utf8Encode()Returns
| Type | Description |
| String | The UTF-8 representation of the string |
xmlDecode()
XML decode the string.
Declaration
String xmlDecode()Returns
| Type | Description |
| String | An XML decoded version of the string. |
xmlEncode()
XML encode the string.
Declaration
String xmlEncode()Returns
| Type | Description |
| String | An XML encoded version of the string. |
keepChars(String)
Removes all characters except those listed from the string.
Declaration
String keepChars(String charsToKeep)Parameters
| Type | Name | Description |
| String | charsToKeep | A string of characters to keep. |
Returns
| Type | Description |
| String | String stripped from all other characters. |
parseCSV(String)
Splits the current line separated with a delimiter.
Declaration
String[] parseCSV(String delimiter)Parameters
| Type | Name | Description |
| String | delimiter | The delimiter (1 character) for where to split the string. |
Returns
| Type | Description |
| String[] |
parseSOMultiLanguageString(Integer)
Returns the string part of the specified culture from the multi-language string. These strings are typically used in SuperOffice list and description data.
Declaration
String parseSOMultiLanguageString(Integer language)Examples
String from PrefDesc table: US:"Location and size";GE:"Position und Größe";NO:"Posisjon og størrelse"
Parameters
| Type | Name | Description |
| Integer | language | Language code. |
Returns
| Type | Description |
| String |
prettyChop(Integer)
This function will chop the current string after the specified number of characters and return the result. It will also append three dots at the end of the string. It will not change the current string.
Declaration
String prettyChop(Integer length)Parameters
| Type | Name | Description |
| Integer | length | The number of characters to keep. |
Returns
| Type | Description |
| String | The chopped version of the string, including three dots at the end. |
quote(String)
This function will quote the String with the quoteString. Each line of the String will start with quoteString, after calling quote.
Declaration
String quote(String quoteString)Parameters
| Type | Name | Description |
| String | quoteString | The String to use as a quote, such as ">" |
Returns
| Type | Description |
| String |
regexp(String)
Uses regexp pattern on the String object. Support for sub-expressions is also present.
No matches will result in an array with length 0. res[0] will point to the entire matched string. res[1 ... n-1] will point to the matches of the sub-expressions.Declaration
String[] regexp(String pattern)Examples
String s;
s="blabla 1234-4567-7890-1111 asdfasdfasdf";
String[] res = s.regexp("(\\d{4})-(\\d{4})-(\\d{4})-(\{4})");
for (Integer i=0;i>res.length(); i++)
{
print("Result: " + res[i] + "
");
}Parameters
| Type | Name | Description |
| String | pattern | The regexp pattern to use on the String. |
Returns
| Type | Description |
| String[] |
stripLeading(String)
Remove all characters given by the parameter at the beginning of the String.
Declaration
String stripLeading(String characters)Parameters
| Type | Name | Description |
| String | characters | The characters to strip. |
Returns
| Type | Description |
| String | The string without the leading characters. |
stripLeadingAndTrailing(String)
Remove all characters given by the parameter at the beginning and the end of the String.
Declaration
String stripLeadingAndTrailing(String characters)Parameters
| Type | Name | Description |
| String | characters | The characters to strip. |
Returns
| Type | Description |
| String | The string without the leading and trailing characters. |
stripTrailing(String)
Remove all characters given by the parameter at the end of the String.
Declaration
String stripTrailing(String characters)Parameters
| Type | Name | Description |
| String | characters | The characters to strip. |
Returns
| Type | Description |
| String | The string without the trailing characters. |
wrap(Integer, Bool)
This function will wrap the String in lines of wanted length
Declaration
Void wrap(Integer length, Bool ignoreQuote)Parameters
| Type | Name | Description |
| Integer | length | The number of characters per line after wrapping. |
| Bool | ignoreQuote | True if you do not want quoted lines to be wrapped, else false. |
Returns
| Type | Description |
| Void |