String

A string is a sequence of characters. Strings appear as literal values, as results of element methods like .text(), .value(), and .attr(), and as inputs to string methods.

Literal syntax

String literals are written with double or single quotes:

"hello"
'hello'
"Untitled"
'It\'s fine'

Both quote styles are equivalent. Use single quotes when the string contains double quotes, or escape the delimiter with a backslash.

String interpolation

Strings support interpolation with #{}. Expressions inside #{} are evaluated and coerced to String:

let name = "world";
"hello #{name}"                    // "hello world"
"total: #{items.count()}"          // "total: 3"
"#{price * quantity} GBP"          // "150 GBP"

#{} is used instead of ${} to avoid ambiguity with CSS selectors. If the expression is null, the result is the empty string. To include a literal #{, escape the #: "\#{not interpolated}".

Concatenation

The + operator concatenates strings:

"hello" + " " + "world"

${h1}.first().text() + " — " + ${[itemprop="author"]}.first().text()

For complex string assembly, string interpolation is often more readable than concatenation.

Methods

contains(substring)

Returns true if the string contains the given substring.

${h1}.first().text().contains("Chapter")

Returns: boolean

startsWith(prefix)

Returns true if the string starts with the given prefix.

${a}.first().attr("href").startsWith("/products")

Returns: boolean

endsWith(suffix)

Returns true if the string ends with the given suffix.

${a}.first().attr("href").endsWith(".html")

Returns: boolean

matches(pattern)

Returns true if the string matches the given regular expression pattern.

${[itemprop="email"]}.first().value().matches("^[^@]+@[^@]+$")

Returns: boolean

count()

Returns the length of the string in characters.

${h1}.first().text().count()

Returns: number

isEmpty()

Returns true if the string has zero characters.

"".isEmpty()
// true
${h1}.first().text().isEmpty()

Returns: boolean

trim()

Returns a new string with leading and trailing whitespace removed.

"  hello  ".trim()
// "hello"

Returns: string

lower()

Returns a new string with all characters converted to lowercase.

"Hello World".lower()
// "hello world"

Returns: string

upper()

Returns a new string with all characters converted to uppercase.

"Hello World".upper()
// "HELLO WORLD"

Returns: string

replace(pattern, replacement)

Returns a new string with all occurrences of pattern replaced by replacement.

"hello world".replace("world", "there")
// "hello there"

Returns: string

split(delimiter)

Splits the string by the given delimiter and returns a list of substrings.

"a,b,c".split(",")
// ["a", "b", "c"]

Returns: list

slice(start[, end])

Returns the substring from start (inclusive) to end (exclusive), operating on characters. If end is omitted, slices to the end of the string. Negative indices count from the end.

"hello".slice(1, 3)    // "el"
"hello".slice(1)       // "ello"
"hello".slice(-3)      // "llo"
"hello".slice(-3, -1)  // "ll"

When start >= end after resolving negative indices, returns an empty string. Indices are clamped to the valid range, so out-of-bounds values do not produce errors.

Returns: string

Type coercion methods

These methods parse a string into another type. .Number() returns null if the string cannot be parsed; .Integer() and .Float() throw a type error instead.

.Number()

Smart-parses the string as a number. Returns an integer for whole numbers like "42" and a float for decimal numbers like "3.14". Returns null if the string is not a valid number.

${[itemprop="price"]}.first().value().Number()
// "42" → 42 (integer)
// "3.14" → 3.14 (float)

Returns: number or null

.Float()

Parses the string as a decimal number. Always returns a float, even for whole numbers. Throws a type error if the string is not a valid number — unlike .Number(), it does not return null.

${[itemprop="rating"]}.first().value().Float()
// "42" → 42.0 (float)
// "3.14" → 3.14 (float)

Returns: float

.Integer()

Parses the string as a whole number (no decimal part). Throws a type error if the string is not a valid integer — unlike .Number(), it does not return null.

${[itemprop="quantity"]}.first().value().Integer()

Returns: integer

.String()

Returns the string itself. This is the identity coercion — useful in generic contexts where coercion is applied uniformly across values.

${h1}.first().text().String()

Returns: string

.Bool()

Converts the string to a Boolean using truthiness rules. Empty strings are false, non-empty strings are true.

"hello".Bool()    // true
"".Bool()         // false

Returns: boolean

Cryptographic methods

These methods are available on the server side only. They are not available in the browser-based JavaScript evaluator.

.sha256()

Returns the SHA-256 hash of the string as a lowercase hex string.

"hello".sha256()
// "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

Returns: string

.hmac_sha256(key)

Returns the HMAC-SHA256 of the string using the given key, as a lowercase hex string.

"message".hmac_sha256("secret-key")

Returns: string

.bcrypt()

Hashes the string using bcrypt. Each call produces a different result due to random salt.

"password".bcrypt()                    // default cost 12
"password".bcrypt({ cost: 10 })        // custom cost (4-31)

.argon2()

Hashes the string using argon2id. Each call produces a different result due to random salt.

"password".argon2()                                         // sensible defaults
"password".argon2({ memory: 19456, time: 2, length: 64 })   // custom params

Options: memory (KiB), time (iterations), length (output bytes).

Random string generation

String.random(length)

Generates a cryptographically random string of the given length using alphanumeric characters (A-Za-z0-9).

String.random(8)              // e.g. "kR7mXp2q"
String.random(32)             // a 32-character random string

String.random(length, options)

Generates a random string with configurable character alphabets and per-alphabet minimum guarantees.

Named alphabets: upper (A-Z), lower (a-z), digits (0-9), symbols, alphanumeric (A-Za-z0-9), url_safe (A-Za-z0-9 plus -_).

Each can be set to true (include), false (exclude), or an integer (include with minimum count guarantee).

String.random(32, { upper: true, digits: true })           // uppercase + digits only
String.random(32, { upper: 3, lower: 3, digits: 2 })       // with minimum counts
String.random(20, { url_safe: true })                       // URL-safe characters

Custom characters: Use chars for a custom character pool, optionally with chars_min for a minimum count.

String.random(20, { chars: "AEIOU" })                       // vowels only
String.random(32, { alphanumeric: true, chars: "-_", chars_min: 2 })  // combined

The algorithm satisfies per-alphabet minimums first, fills the remainder from the combined pool, then shuffles the result.

See also