String Functions¶

Functions for transforming, inspecting, and formatting strings.

Summary¶

Function	Signature	Description
`abbreviate`	`string, number, string? -> string`	Truncate string with ellipsis suffix
`camel_case`	`string -> string`	Convert to camelCase
`capitalize`	`string -> string`	Capitalize the first character
`center`	`string, number, string? -> string`	Center-pad string to given width
`concat`	`string... -> string`	Concatenate strings
`deburr`	`string -> string`	Remove diacritical marks by mapping Latin-1 accented characters to ASCII equivalents
`escape`	`string -> string`	Escape HTML special characters (& < > " ') into entities
`escape_regex`	`string -> string`	Escape regular-expression metacharacters with a backslash
`explode`	`string -> array`	Convert a string to an array of Unicode codepoints
`find_first`	`string, string -> number \\| null`	Find first occurrence of substring
`find_last`	`string, string -> number \\| null`	Find last occurrence of substring
`format`	`string, any -> string`	Substitute placeholders in a template using positional ({0}) or named ({key}) references
`humanize`	`string -> string`	Convert an identifier to a human-readable phrase (first word capitalized, rest lowercased)
`implode`	`array -> string`	Convert an array of Unicode codepoints to a string
`indices`	`string, string -> array`	Find all indices of substring occurrences
`inside`	`string, string -> boolean`	Check if search string is contained in string
`is_blank`	`string -> boolean`	Check if string is empty or whitespace-only
`kebab_case`	`string -> string`	Convert to kebab-case
`lower`	`string -> string`	Convert string to lowercase
`lower_case`	`string -> string`	Lowercase every character (no word splitting; same as lower)
`ltrimstr`	`string, string -> string`	Remove prefix from string if present
`normalize_whitespace`	`string -> string`	Collapse multiple whitespace to single space
`obscure`	`string, number?, string? -> string`	Mask all but the last N characters, with an optional mask character (defaults to masking the whole string with '*')
`pad_left`	`string, number, string -> string`	Pad string on the left to reach target length
`pad_right`	`string, number, string -> string`	Pad string on the right to reach target length
`pascal_case`	`string -> string`	Convert to PascalCase (UpperCamelCase) with no separators
`redact_pattern`	`string, string, string? -> string`	Redact regex pattern matches with replacement
`repeat`	`string, number -> string`	Repeat a string n times
`replace`	`string, string, string -> string`	Replace occurrences of a substring. Use backtick-JSON syntax: replace(text, `"\n"`, `" "`)
`reverse_string`	`string -> string`	Reverse a string
`rtrimstr`	`string, string -> string`	Remove suffix from string if present
`shell_escape`	`string -> string`	Escape a string for safe use in shell commands (POSIX sh compatible, jq parity)
`shouty_kebab_case`	`string -> string`	Convert to SHOUTY-KEBAB-CASE (uppercase words joined by hyphens)
`shouty_snake_case`	`string -> string`	Convert to SHOUTY_SNAKE_CASE (uppercase words joined by underscores)
`slice`	`string, number, number -> string`	Extract substring by start and end index
`snake_case`	`string -> string`	Convert to snake_case
`split`	`string, string -> array`	Split string by delimiter. Use backtick-JSON syntax for literals: split(text, `"\n"`) to split on newlines
`sprintf`	`string, any... -> string`	Printf-style string formatting
`start_case`	`string -> string`	Convert to Start Case: capitalize each word, lowercase the rest, space-separated
`substr`	`string, number, number -> string`	Extract substring by start index and length
`title`	`string -> string`	Convert to title case
`title_case`	`string -> string`	Convert to Title Case with space-separated capitalized words
`train_case`	`string -> string`	Convert to Train-Case: capitalized words joined by hyphens
`trim`	`string -> string`	Remove leading and trailing whitespace
`trim_left`	`string -> string`	Remove leading whitespace
`trim_right`	`string -> string`	Remove trailing whitespace
`truncate`	`string, number -> string`	Truncate to a maximum length, appending a suffix (default "...") that counts toward the length
`unescape`	`string -> string`	Unescape HTML entities (& < > " ') back to characters
`upper`	`string -> string`	Convert string to uppercase
`upper_case`	`string -> string`	Uppercase every character (no word splitting; same as upper)
`words`	`string -> array`	Split a string into words on whitespace, underscores, hyphens, and camelCase boundaries
`wrap`	`string, number -> string`	Wrap text to specified width

Functions¶

abbreviate¶

Truncate string with ellipsis suffix

Signature: string, number, string? -> string

Examples:

# Default ellipsis
abbreviate('hello world', `8`) -> \"hello...\"
# No truncation needed
abbreviate('hello', `10`) -> \"hello\"
# Custom suffix
abbreviate('hello world', `8`, '>>') -> \"hello >>\"

camel_case¶

Convert to camelCase

Signature: string -> string

Examples:

# From snake_case
camel_case('hello_world') -> \"helloWorld\"
# From kebab-case
camel_case('hello-world') -> \"helloWorld\"
# From title case
camel_case('Hello World') -> \"helloWorld\"

capitalize¶

Capitalize the first character

Signature: string -> string

Examples:

# Basic capitalize
capitalize('hello') -> \"Hello\"
# Already uppercase
capitalize('HELLO') -> \"HELLO\"
# Empty string
capitalize('') -> \"\"

center¶

Center-pad string to given width

Signature: string, number, string? -> string

Examples:

# Center with spaces
center('hi', `6`) -> \"  hi  \"
# Center with dashes
center('hi', `6`, '-') -> \"--hi--\"
# Already wider
center('hello', `3`) -> \"hello\"

concat¶

Concatenate strings

Signature: string... -> string

Examples:

# Multiple strings
concat('hello', ' ', 'world') -> \"hello world\"
# Two strings
concat('a', 'b') -> \"ab\"
# Single string
concat('only') -> \"only\"

deburr¶

Remove diacritical marks by mapping Latin-1 accented characters to ASCII equivalents

Signature: string -> string

Examples:

# Strips accents
deburr('déjà vu') -> \"deja vu\"
# Plain ASCII unchanged
deburr('hello') -> \"hello\"

escape¶

Escape HTML special characters (& < > " ') into entities

Signature: string -> string

Examples:

# Escapes < and &
escape('a < b & c') -> \"a &lt; b &amp; c\"

escape_regex¶

Escape regular-expression metacharacters with a backslash

Signature: string -> string

Examples:

# Escapes parentheses
escape_regex('(group)') -> \"\\(group\\)\"

explode¶

Convert a string to an array of Unicode codepoints

Signature: string -> array

Examples:

# ASCII characters
explode('abc') -> [97, 98, 99]
# Unicode characters
explode('A☺') -> [65, 9786]
# Empty string
explode('') -> []

find_first¶

Find first occurrence of substring

Signature: string, string -> number | null

JEP: JEP-014

Examples:

# Find character
find_first('hello', 'l') -> 2
# Find substring
find_first('hello world', 'world') -> 6
# Not found
find_first('hello', 'x') -> null

find_last¶

Find last occurrence of substring

Signature: string, string -> number | null

JEP: JEP-014

Examples:

# Find last character
find_last('hello', 'l') -> 3
# Find last substring
find_last('foo bar foo', 'foo') -> 8
# Not found
find_last('hello', 'x') -> null

format¶

Substitute placeholders in a template using positional ({0}) or named ({key}) references

Signature: string, any -> string

Examples:

# Positional substitution
format('Hello {0}', 'World') -> \"Hello World\"
# Named substitution
format('Hello {name}', {name: 'World'}) -> \"Hello World\"

humanize¶

Convert an identifier to a human-readable phrase (first word capitalized, rest lowercased)

Signature: string -> string

Examples:

# From snake_case
humanize('first_name') -> \"First name\"
# From camelCase
humanize('helloWorld') -> \"Hello world\"

implode¶

Convert an array of Unicode codepoints to a string

Signature: array -> string

Examples:

# ASCII codepoints
implode([97, 98, 99]) -> \"abc\"
# Unicode codepoints
implode([65, 9786]) -> \"A☺\"
# Empty array
implode([]) -> \"\"

indices¶

Find all indices of substring occurrences

Signature: string, string -> array

Examples:

# Multiple occurrences
indices('hello', 'l') -> [2, 3]
# Overlapping matches
indices('ababa', 'aba') -> [0, 2]
# No matches
indices('hello', 'x') -> []

inside¶

Check if search string is contained in string

Signature: string, string -> boolean

Examples:

# Found
inside('world', 'hello world') -> true
# Not found
inside('foo', 'hello world') -> false
# Empty string always matches
inside('', 'hello') -> true

is_blank¶

Check if string is empty or whitespace-only

Signature: string -> boolean

Examples:

# Whitespace only
is_blank('   ') -> true
# Empty string
is_blank('') -> true
# Has content
is_blank('hello') -> false

kebab_case¶

Convert to kebab-case

Signature: string -> string

Examples:

# From camelCase
kebab_case('helloWorld') -> \"hello-world\"
# From snake_case
kebab_case('hello_world') -> \"hello-world\"
# From title case
kebab_case('Hello World') -> \"hello-world\"

lower¶

Convert string to lowercase

Signature: string -> string

JEP: JEP-014

Examples:

# All uppercase
lower('HELLO') -> \"hello\"
# Mixed case
lower('Hello World') -> \"hello world\"
# Already lowercase
lower('hello') -> \"hello\"

lower_case¶

Lowercase every character (no word splitting; same as lower)

Signature: string -> string

Examples:

# Per-character lowercase
lower_case('fooBar') -> \"foobar\"

ltrimstr¶

Remove prefix from string if present

Signature: string, string -> string

Examples:

# Remove prefix
ltrimstr('foobar', 'foo') -> \"bar\"
# Prefix not found
ltrimstr('foobar', 'bar') -> \"foobar\"
# Empty prefix
ltrimstr('hello', '') -> \"hello\"

normalize_whitespace¶

Collapse multiple whitespace to single space

Signature: string -> string

Examples:

# Multiple spaces
normalize_whitespace('a  b  c') -> \"a b c\"
# Newlines to space
normalize_whitespace('a\\n\\nb') -> \"a b\"
# Already normalized
normalize_whitespace('hello') -> \"hello\"

obscure¶

Mask all but the last N characters, with an optional mask character (defaults to masking the whole string with '*')

Signature: string, number?, string? -> string

Examples:

# Credit card
obscure('4111111111111111', `4`) -> \"************1111\"
# Mask all
obscure('secret', `0`) -> \"******\"
# Custom mask char
obscure('password', `4`, '#') -> \"####word\"

pad_left¶

Pad string on the left to reach target length

Signature: string, number, string -> string

JEP: JEP-014

Examples:

# Zero-pad number
pad_left('5', `3`, '0') -> \"005\"
# Right-align text
pad_left('hi', `5`, ' ') -> \"   hi\"
# Already long enough
pad_left('hello', `3`, '0') -> \"hello\"

pad_right¶

Pad string on the right to reach target length

Signature: string, number, string -> string

JEP: JEP-014

Examples:

# Pad with zeros
pad_right('5', `3`, '0') -> \"500\"
# Left-align text
pad_right('hi', `5`, ' ') -> \"hi   \"
# Already long enough
pad_right('hello', `3`, '0') -> \"hello\"

pascal_case¶

Convert to PascalCase (UpperCamelCase) with no separators

Signature: string -> string

Examples:

# From snake_case
pascal_case('hello_world') -> \"HelloWorld\"
# From kebab-case
pascal_case('hello-world') -> \"HelloWorld\"

redact_pattern¶

Redact regex pattern matches with replacement

Signature: string, string, string? -> string

Examples:

# Redact email
redact_pattern('email: test@example.com', '\\S+@\\S+', '[EMAIL]') -> \"email: [EMAIL]\"
# Redact phone
redact_pattern('call 555-1234', '\\d{3}-\\d{4}', '[PHONE]') -> \"call [PHONE]\"
# No matches
redact_pattern('no match', 'xyz', '[X]') -> \"no match\"

repeat¶

Repeat a string n times

Signature: string, number -> string

Examples:

# Repeat 3 times
repeat('ab', `3`) -> \"ababab\"
# Create separator
repeat('-', `5`) -> \"-----\"
# Zero times
repeat('x', `0`) -> \"\"

replace¶

Replace occurrences of a substring. Use backtick-JSON syntax: replace(text, "\n", " ")

Signature: string, string, string -> string

JEP: JEP-014

Examples:

# Replace all occurrences
replace(`"hello"`, `"l"`, `"L"`) -> \"heLLo\"
# Replace newlines
replace(`"line1\\nline2"`, `"\\n"`, `" "`) -> \"line1 line2\"
# Replace all
replace(`"aaa"`, `"a"`, `"b"`) -> \"bbb\"

reverse_string¶

Reverse a string

Signature: string -> string

Examples:

# Reverse word
reverse_string('hello') -> \"olleh\"
# Two chars
reverse_string('ab') -> \"ba\"
# Empty string
reverse_string('') -> \"\"

rtrimstr¶

Remove suffix from string if present

Signature: string, string -> string

Examples:

# Remove suffix
rtrimstr('foobar', 'bar') -> \"foo\"
# Remove file extension
rtrimstr('hello.txt', '.txt') -> \"hello\"
# Suffix not present
rtrimstr('hello', 'xyz') -> \"hello\"
# Only removes once
rtrimstr('barbar', 'bar') -> \"bar\"

shell_escape¶

Escape a string for safe use in shell commands (POSIX sh compatible, jq parity)

Signature: string -> string

Examples:

# Simple string unchanged
shell_escape('hello') -> \"hello\"
# Spaces get quoted
shell_escape('hello world') -> \"'hello world'\"
# Variables are escaped
shell_escape('$PATH') -> \"'$PATH'\"
# Single quotes escaped
shell_escape('it'\\''s') -> \"'it'\\\\''s'\"

shouty_kebab_case¶

Convert to SHOUTY-KEBAB-CASE (uppercase words joined by hyphens)

Signature: string -> string

Examples:

# From camelCase
shouty_kebab_case('helloWorld') -> \"HELLO-WORLD\"
# From snake_case
shouty_kebab_case('hello_world') -> \"HELLO-WORLD\"

shouty_snake_case¶

Convert to SHOUTY_SNAKE_CASE (uppercase words joined by underscores)

Signature: string -> string

Examples:

# From camelCase
shouty_snake_case('helloWorld') -> \"HELLO_WORLD\"
# From kebab-case
shouty_snake_case('hello-world') -> \"HELLO_WORLD\"

slice¶

Extract substring by start and end index

Signature: string, number, number -> string

Examples:

# Middle slice
slice('hello', `1`, `4`) -> \"ell\"
# From start
slice('hello', `0`, `2`) -> \"he\"
# To end
slice('hello', `3`, `5`) -> \"lo\"
# Two characters
slice('abcdef', `2`, `4`) -> \"cd\"

snake_case¶

Convert to snake_case

Signature: string -> string

Examples:

# From camelCase
snake_case('helloWorld') -> \"hello_world\"
# From PascalCase
snake_case('HelloWorld') -> \"hello_world\"
# From kebab-case
snake_case('hello-world') -> \"hello_world\"
# From UPPER_CASE
snake_case('HELLO_WORLD') -> \"hello_world\"

split¶

Split string by delimiter. Use backtick-JSON syntax for literals: split(text, "\n") to split on newlines

Signature: string, string -> array

JEP: JEP-014

Examples:

# Basic split
split(`"a,b,c"`, `","`) -> [\"a\", \"b\", \"c\"]
# Split by space
split(`"hello world"`, `" "`) -> [\"hello\", \"world\"]
# Split on newline
split(`"line1\\nline2"`, `"\\n"`) -> [\"line1\", \"line2\"]
# No delimiter found
split(`"no-delim"`, `","`) -> [\"no-delim\"]

sprintf¶

Printf-style string formatting

Signature: string, any... -> string

Examples:

# Float formatting
sprintf('Pi is %.2f', `3.14159`) -> \"Pi is 3.14\"
# String interpolation
sprintf('Hello %s', 'world') -> \"Hello world\"
# Integer formatting
sprintf('%d items', `42`) -> \"42 items\"
# Multiple args
sprintf('%s: %d', 'count', `5`) -> \"count: 5\"

start_case¶

Convert to Start Case: capitalize each word, lowercase the rest, space-separated

Signature: string -> string

Examples:

# From snake_case
start_case('hello_world') -> \"Hello World\"
# From camelCase
start_case('helloWorld') -> \"Hello World\"

substr¶

Extract substring by start index and length

Signature: string, number, number -> string

Examples:

# From index 1, length 3
substr('hello', `1`, `3`) -> \"ell\"
# From start
substr('hello', `0`, `2`) -> \"he\"
# Middle portion
substr('abcdef', `2`, `2`) -> \"cd\"
# Single character
substr('hello', `4`, `1`) -> \"o\"

title¶

Convert to title case

Signature: string -> string

Examples:

# Basic title case
title('hello world') -> \"Hello World\"
# From uppercase
title('HELLO WORLD') -> \"Hello World\"
# Single word
title('hello') -> \"Hello\"
# Single letters
title('a b c') -> \"A B C\"

title_case¶

Convert to Title Case with space-separated capitalized words

Signature: string -> string

Examples:

# From snake_case
title_case('hello_world') -> \"Hello World\"
# From camelCase
title_case('fooBar') -> \"Foo Bar\"

train_case¶

Convert to Train-Case: capitalized words joined by hyphens

Signature: string -> string

Examples:

# From snake_case
train_case('hello_world') -> \"Hello-World\"
# From camelCase
train_case('fooBar') -> \"Foo-Bar\"

trim¶

Remove leading and trailing whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove both sides
trim('  hello  ') -> \"hello\"
# No whitespace
trim('hello') -> \"hello\"
# Only whitespace
trim('   ') -> \"\"
# Tabs and newlines
trim('\t\nhello\t\n') -> \"hello\"

trim_left¶

Remove leading whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove leading spaces
trim_left('  hello') -> \"hello\"
# Trailing preserved
trim_left('hello  ') -> \"hello  \"
# Remove tabs
trim_left('\t\thello') -> \"hello\"
# No change needed
trim_left('hello') -> \"hello\"

trim_right¶

Remove trailing whitespace

Signature: string -> string

JEP: JEP-014

Examples:

# Remove trailing spaces
trim_right('hello  ') -> \"hello\"
# Leading preserved
trim_right('  hello') -> \"  hello\"
# Remove tabs
trim_right('hello\t\t') -> \"hello\"
# No change needed
trim_right('hello') -> \"hello\"

truncate¶

Truncate to a maximum length, appending a suffix (default "...") that counts toward the length

Signature: string, number -> string

Examples:

# Truncate to 5 chars incl ellipsis
truncate('hello world', `5`) -> \"he...\"
# Shorter than max, unchanged
truncate('hi', `10`) -> \"hi\"

unescape¶

Unescape HTML entities (& < > " ') back to characters

Signature: string -> string

Examples:

# Unescapes &lt; and &amp;
unescape('a &lt; b &amp; c') -> \"a < b & c\"

upper¶

Convert string to uppercase

Signature: string -> string

JEP: JEP-014

Examples:

# Basic uppercase
upper('hello') -> \"HELLO\"
# Mixed case
upper('Hello World') -> \"HELLO WORLD\"
# Already uppercase
upper('HELLO') -> \"HELLO\"
# With numbers
upper('abc123') -> \"ABC123\"

upper_case¶

Uppercase every character (no word splitting; same as upper)

Signature: string -> string

Examples:

# Per-character uppercase
upper_case('fooBar') -> \"FOOBAR\"

words¶

Split a string into words on whitespace, underscores, hyphens, and camelCase boundaries

Signature: string -> array

Examples:

# Splits on camelCase boundary
words('helloWorld') -> ["hello", "World"]
# Splits on space and hyphen
words('foo bar-baz') -> ["foo", "bar", "baz"]

wrap¶

Wrap text to specified width

Signature: string, number -> string

Examples:

# Wrap at word boundary
wrap('hello world', `5`) -> \"hello\\nworld\"
# Multiple wraps
wrap('a b c d e', `3`) -> \"a b\\nc d\\ne\"
# No wrap needed
wrap('short', `10`) -> \"short\"
# Longer text
wrap('one two three', `7`) -> \"one two\\nthree\"