String

mash.string · Data

Two things share the name “string” in MaSH, and they do different jobs.

• mash.str(value) wraps a piece of text in a text object with methods for trimming, searching, replacing and changing case. This is what you use most.
• mash.string (this page) is a small toolbox of functions that take text in and give a result out: fuzzy matching, random text, bulk replace, web-address encoding.

Use mash.str to tidy and test one piece of text. Use mash.string when you’re comparing two pieces or making new ones.

How it works

Text objects print as text but aren’t plain text. mash.str(" hi ").trim() gives another text object. Add .toString() when you need ordinary text, such as a value you’re about to store in a field or compare strictly. Printing, {{ }} templates and joining with ~ handle them for you.

Methods chain. Each one returns a new text object, so mash.str(x).trim().lower().replace("inv-", "") works from left to right. Nothing changes the original.

Passing a number or a null is fine. mash.str(5) is the text 5. mash.str(null) is empty.

Matching helpers are for people’s typing. levenshtein counts the single-letter edits between two words. similarText scores how alike they are. soundex and metaphone give a code that sounds-alike words share. Use them to forgive typos, not to decide who someone is.

Common tasks

Clean up a value before you use it:

set raw to "  Invoice INV-2041, paid  "
set clean to mash.str(raw).trim()
printline clean.lower().toString()
printline clean.before(",").toString()
printline clean.replace("INV-", "#").toString()

invoice inv-2041, paid
Invoice INV-2041
Invoice #2041, paid

Test and pull out pieces:

set ref to mash.str("Order SO-20417 shipped")
printline ref.startsWith("Order")
printline ref.match("/SO-(\\d+)/")[1]
printline ref.split(" ").count()

true
20417
3

Pad, reshape and change case:

printline mash.str("7").padStart(4, "0").toString()
printline mash.str("hello world").camel().toString()
printline mash.str("Hello World").snake().toString()
printline mash.str("Café").upper().toString()

0007
helloWorld
hello_world
CAFÉ

Swap several words at once without them tripping over each other:

printline mash.string.replace({"cat": "dog", "dog": "cat"}, "cat chases dog")

dog chases cat

Tolerate a typo:

set known to ["Marketing", "Engineering", "Operations"]
set typed to "Marketting"
each known as dept
    if mash.string.levenshtein(dept, typed) is less than or equal to 2
        printline "Did you mean {{dept}}?"
    end
end

Did you mean Marketing?

Encode a value for a web address:

printline mash.string.urlencode("a b&c")

a+b%26c

Watch out for

• mash.str(...).title() is not “title case”. Pass true (title(true)) to capitalise every word.
• Methods are named like the text-object’s own. contains doesn’t exist. Use containsAny(["a", "b"]). padLeft doesn’t exist. It’s padStart. When a call says “Method … does not exist”, check mash.debug.getMethods.
• random is for ids and tokens, not secrets. mash.string.random(8) gives 8 hex characters. Pass your own alphabet (random(6, "0123456789")) for codes. For anything security-sensitive use mash.crypt.
• similarText(a, b, true) gives a percentage, and without true it gives a count of matching characters.

See also

Values and types and Expressions for the ~ join and {{ }} templates.

Methods

iconv

string.iconv(from_encoding: string, to_encoding: string, string: string)

Convert a string between character encodings

levenshtein

string.levenshtein(str1: string, str2: string) → int

Calculate the Levenshtein distance between two strings

metaphone

string.metaphone(string: string) → string

Calculate the metaphone key of a string

random

string.random(length?: int = 16, chars?: string = "") → string

Generate a random string

replace

string.replace(dictionary: Collection, subject: Stringable)

Replace substrings using a dictionary of search/replace pairs

similarText

string.similarText(first: string, second: string, percent?: bool = false) → int

Calculate the similarity between two strings

soundex

string.soundex(string: string) → string

Calculate the soundex key of a string

urldecode

string.urldecode(string: string, raw?: bool = false) → string

Decode a URL-encoded string

urlencode

string.urlencode(string: string, raw?: bool = false) → string

URL-encode a string

wordCount

string.wordCount(string: string) → int

Count the number of words in a string