The String Module (str:)

Table of Content:

Introduction

The str: module provides string manipulation functions.

Function usages are given in the same format as in the reference doc for the builtin module.

Functions

str:compare

str:compare $a $b

Compares two strings and output an integer that will be 0 if a == b, -1 if a < b, and +1 if a > b.

~> str:compare a a
▶ 0
~> str:compare a b
▶ -1
~> str:compare b a
▶ 1

str:contains

str:contains $str $substr

Outputs whether $str contains $substr as a substring.

~> str:contains abcd x
▶ $false
~> str:contains abcd bc
▶ $true

str:contains-any

str:contains-any $str $chars

Outputs whether $str contains any Unicode code points in $chars.

~> str:contains-any abcd x
▶ $false
~> str:contains-any abcd xby
▶ $true

str:count

str:count $str $substr

Outputs the number of non-overlapping instances of $substr in $s. If $substr is an empty string, output 1 + the number of Unicode code points in $s.

~> str:count abcdefabcdef bc
▶ 2
~> str:count abcdef ''
▶ 7

str:equal-fold

str:equal-fold $str1 $str2

Outputs if $str1 and $str2, interpreted as UTF-8 strings, are equal under Unicode case-folding.

~> str:equal-fold ABC abc
▶ $true
~> str:equal-fold abc ab
▶ $false

str:has-prefix

str:has-prefix $str $prefix

Outputs if $str begins with $prefix.

~> str:has-prefix abc ab
▶ $true
~> str:has-prefix abc bc
▶ $false

str:has-suffix

str:has-suffix $str $suffix

Outputs if $str ends with $suffix.

~> str:has-suffix abc ab
▶ $false
~> str:has-suffix abc bc
▶ $true

str:index

str:index $str $substr

Outputs the index of the first instance of $substr in $str, or -1 if $substr is not present in $str.

~> str:index abcd cd
▶ 2
~> str:index abcd xyz
▶ -1

str:index-any

str:index-any $str $chars

Outputs the index of the first instance of any Unicode code point from $chars in $str, or -1 if no Unicode code point from $chars is present in $str.

~> str:index-any "chicken" "aeiouy"
▶ 2
~> str:index-any l33t aeiouy
▶ -1

str:last-index

str:last-index $str $substr

Outputs the index of the last instance of $substr in $str, or -1 if $substr is not present in $str.

~> str:last-index "elven speak elvish" elv
▶ 12
~> str:last-index "elven speak elvish" romulan
▶ -1

str:title

str:title $str

Outputs $str with all Unicode letters that begin words mapped to their Unicode title case.

~> str:title "her royal highness"
▶ Her Royal Highness

str:to-lower

str:to-lower $str

Outputs $str with all Unicode letters mapped to their lower-case equivalent.

~> str:to-lower 'ABC!123'
▶ abc!123

str:to-title

str:to-title $str

Outputs $str with all Unicode letters mapped to their Unicode title case.

~> str:to-title "her royal highness"
▶ HER ROYAL HIGHNESS
~> str:to-title "хлеб"
▶ ХЛЕБ

str:to-upper

str:to-upper

Outputs $str with all Unicode letters mapped to their upper-case equivalent.

~> str:to-upper 'abc!123'
▶ ABC!123

str:trim

str:trim $str $cutset

Outputs $str with all leading and trailing Unicode code points contained in $cutset removed.

~> str:trim "¡¡¡Hello, Elven!!!" "!¡"
▶ 'Hello, Elven'

str:trim-left

str:trim-left $str $cutset

Outputs $str with all leading Unicode code points contained in $cutset removed. To remove a prefix string use str:trim-prefix.

~> str:trim-left "¡¡¡Hello, Elven!!!" "!¡"
▶ 'Hello, Elven!!!'

str:trim-prefix

str:trim-prefix $str $prefix

Outputs $str minus the leading $prefix string. If $str doesn’t begin with $prefix, $str is output unchanged.

~> str:trim-prefix "¡¡¡Hello, Elven!!!" "¡¡¡Hello, "
▶ Elven!!!
~> str:trim-prefix "¡¡¡Hello, Elven!!!" "¡¡¡Hola, "
▶ '¡¡¡Hello, Elven!!!'

str:trim-right

str:trim-right $str $cutset

Outputs $str with all leading Unicode code points contained in $cutset removed. To remove a suffix string use str:trim-suffix.

~> str:trim-right "¡¡¡Hello, Elven!!!" "!¡"
▶ '¡¡¡Hello, Elven'

str:trim-space

str:trim-space $str

Outputs $str with all leading and trailing white space removed as defined by Unicode.

~> str:trim-space " \t\n Hello, Elven \n\t\r\n"
▶ 'Hello, Elven'

str:trim-suffix

str:trim-suffix $str $suffix

Outputs $str minus the trailing $suffix string. If $str doesn’t end with $suffix, $str is output unchanged.

~> str:trim-suffix "¡¡¡Hello, Elven!!!" ", Elven!!!"
▶ ¡¡¡Hello
~> str:trim-suffix "¡¡¡Hello, Elven!!!" ", Klingons!!!"
▶ '¡¡¡Hello, Elven!!!'