Strings#

Adama has a solid set of string manipulation methods you can call directly on string values. Searching, splitting, trimming, case conversion -- the stuff you reach for constantly when dealing with text.

Basic Example#

public string x;
formula x_x = (x + x).reverse();

Here reverse() is called as a method on the concatenated string. That's the pattern -- methods on values, not static function calls.

String Methods#

length()#

Returns the number of characters in the string.

string text = "Hello";
int len = text.length();  // 5

Returns: int - The length of the string

split(word)#

Splits the string into a list of parts using the given delimiter. Standard stuff.

procedure foo() {
  string csv = "apple,banana,cherry";
  list<string> fruits = csv.split(",");
  // ["apple", "banana", "cherry"]
}

Returns: list<string> - List of substrings

Maybe variant:

Returns: maybe<list<string>> - List of substrings if delimiter was provided

contains(word)#

Tests whether the string contains the given substring.

string text = "Hello World";
bool hasWorld = text.contains("World");  // true
bool hasGoodbye = text.contains("Goodbye");  // false

Returns: bool - True if the substring is found

Maybe variant:

Returns: maybe<bool> - Result if the search word was provided

indexOf(word)#

Finds the position of the first occurrence of a substring.

string text = "Hello World";
maybe<int> pos = text.indexOf("World");  // 6
maybe<int> notFound = text.indexOf("xyz");  // -1

Returns: maybe<int> - The zero-based index, or empty if not found

With offset:

string text = "Hello Hello";
maybe<int> second = text.indexOf("Hello", 1);  // 6

Returns: maybe<int> - The zero-based index after offset, or empty if not found

Maybe variants:

Returns: maybe<int> - Position if word was provided

Returns: maybe<int> - Position if word was provided

trim()#

Strips whitespace from both ends.

string text = "  Hello World  ";
string trimmed = text.trim();  // "Hello World"

Returns: string - The trimmed string

trimLeft()#

Strips whitespace from the left side only.

string text = "  Hello";
string trimmed = text.trimLeft();  // "Hello"

Returns: string - The left-trimmed string

trimRight()#

Strips whitespace from the right side only.

string text = "Hello  ";
string trimmed = text.trimRight();  // "Hello"

Returns: string - The right-trimmed string

upper()#

Converts all characters to uppercase.

string text = "Hello World";
string upper = text.upper();  // "HELLO WORLD"

Returns: string - The uppercase string

lower()#

Converts all characters to lowercase.

string text = "Hello World";
string lower = text.lower();  // "hello world"

Returns: string - The lowercase string

mid(start, length)#

Grabs a substring starting at the given position for the specified length.

string text = "Hello World";
maybe<string> sub = text.mid(0, 5);  // "Hello"
maybe<string> sub2 = text.mid(6, 5);  // "World"

Returns: maybe<string> - The extracted substring, or empty if out of bounds

left(n)#

Returns the first n characters.

string text = "Hello World";
maybe<string> sub = text.left(5);  // "Hello"

Returns: maybe<string> - The first n characters, or empty if out of bounds

right(length)#

Returns the last n characters.

string text = "Hello World";
maybe<string> sub = text.right(5);  // "World"

Returns: maybe<string> - The rightmost substring, or empty if out of bounds

substr(start, end)#

Returns a substring from start to end position. The start is inclusive, end is exclusive -- the standard convention.

string text = "Hello World";
maybe<string> sub = text.substr(0, 5);  // "Hello"

Returns: maybe<string> - The extracted substring, or empty if out of bounds

startsWith(prefix)#

Tests whether the string begins with the given prefix.

string text = "Hello World";
bool startsHello = text.startsWith("Hello");  // true
bool startsGoodbye = text.startsWith("Goodbye");  // false

Returns: bool - True if the string starts with the prefix

endsWith(suffix)#

Tests whether the string ends with the given suffix.

string text = "Hello World";
bool endsWorld = text.endsWith("World");  // true
bool endsHello = text.endsWith("Hello");  // false

Returns: bool - True if the string ends with the suffix

multiply(n)#

Repeats the string n times. Because sometimes you just need "hahaha".

string text = "ha";
string laugh = text.multiply(3);  // "hahaha"

You can also use the * operator, which does the same thing:

string laugh = "ha" * 3;  // "hahaha"

Returns: string - The repeated string

reverse()#

Reverses the character order.

string text = "Hello";
string reversed = text.reverse();  // "olleH"

Returns: string - The reversed string

removeAll(word)#

Removes all occurrences of the given substring.

string text = "ABCDEFABCDEFABCDEF";
string result = text.removeAll("DEF");  // "ABCABCABC"

Returns: string - The string with all occurrences removed

replaceAll(old, new)#

Replaces all occurrences of a substring with another.

string text = "ABCDEFABCDEFABCDEF";
string result = text.replaceAll("DEF", "XYZ");  // "ABCXYZABCXYZABCXYZ"

Returns: string - The string with replacements made

bulkReplaceAll(delimiter, replacements)#

This one is handy when you need to do a bunch of replacements at once. You provide a delimiter pattern and a map of replacements, and it swaps them all in one pass.

procedure foo() {
  map<string, string> replacements;
  replacements["xyz"] = "abc";
  replacements["abc"] = "xyz";
  string result = "hi [!!xyz!!], it's [!!abc!!]".bulkReplaceAll("!!", replacements);
  // "hi [abc], it's [xyz]"
}

Returns: string - The string with bulk replacements made

passwordHash()#

Creates a secure hash of the string for password storage. Don't store passwords in plaintext -- use this.

string hash = "secret".passwordHash();

Returns: string - A secure hash of the string

passwordCheck(password)#

Verifies a password against a hash created by passwordHash().

string hash = "secret".passwordHash();
bool valid = hash.passwordCheck("secret");    // true
bool invalid = hash.passwordCheck("wrong");   // false

Returns: bool - True if the password matches the hash

codepoints()#

Returns the list of Unicode codepoints in the string. For when you need to work at the codepoint level.

procedure foo() {
  string text = "Hello";
  list<int> cp = text.codepoints();  // list of codepoints
}

Returns: list<int> - The list of Unicode codepoints

codepointAt(index)#

Returns the Unicode codepoint at a specific index.

string text = "Hello";
maybe<int> cp = text.codepointAt(0);  // 72 (ASCII for 'H')

Returns: maybe<int> - The codepoint value, or empty if out of bounds

initialsOf(includeMinor)#

Extracts initials from a string. Useful for names and display purposes.

string initials1 = "Justice of Doom".initialsOf(false);  // "JD"
string initials2 = "Justice of Doom".initialsOf(true);   // "JoD"

Returns: string - The extracted initials

camelject(separator)#

Converts camelCase text into a separated format. I needed this for converting between naming conventions.

string result1 = "CreditCard".camelject(" ");       // "Credit Card"
string result2 = "CreditCard".camelject("_").lower();  // "credit_card"

Returns: string - The separated string

intFromHex()#

Parses a hexadecimal string to an integer.

maybe<int> value = "42FF".intFromHex();  // 17151

Returns: maybe<int> - The parsed integer, or empty if invalid hex

longFromHex()#

Parses a hexadecimal string to a long integer.

maybe<long> value = "42FF".longFromHex();  // 17151L

Returns: maybe<long> - The parsed long, or empty if invalid hex

length() (alias)#

Returns the number of characters in the string (same as length() above).

string text = "Hello";
int len = text.length();  // 5

Returns: int - The length of the string

intOf()#

Parses the string as an integer. Returns empty if the string isn't a valid number.

maybe<int> value = "42".intOf();  // 42
maybe<int> invalid = "abc".intOf();  // empty

Returns: maybe<int> - The parsed integer, or empty if not a valid number

principalOf()#

Converts the string to a principal value.

string agent = "user123";
principal p = agent.principalOf();

Returns: principal - The principal value constructed from the string

List Methods#

concat()#

Concatenates all strings in a list into one string. No separator.

procedure foo() {
  string[] parts = ["X", "Y"];
  string result = parts.concat();  // "XY"
}

Returns: string - The concatenated string

join(separator)#

Joins all strings in a list with a separator between them.

procedure foo() {
  string[] parts = ["X", "Y"];
  string result = parts.join(", ");  // "X, Y"
}

Returns: string - The joined string (or maybe<string> for maybe lists)

Integer Methods#

to_roman()#

Converts an integer to a Roman numeral string. Because why not.

string roman = (2023).to_roman();  // "MMXXIII"

Returns: string - The Roman numeral representation

hexOf()#

Converts an integer to its hexadecimal string representation.

string hex = (100).hexOf();  // "64"

Returns: string - The hexadecimal representation

Static Functions#

String.charOf(ch)#

Converts an integer character code to a single-character string. The inverse of working with codepoints.

string a = String.charOf(65);  // "A"
string newline = String.charOf(10);  // "\n"

Returns: string - A single-character string

Method Summary Table#

List Methods#

Integer Methods#