str

str.Find

str.Find(hay, needle [, start [, occurrence]]) -> int

Finds the first (or the occurrence-th) appearance of needle in hay, starting at start. Matches are non-overlapping.

The 0-based byte index of the match, or -1 if there is no (further) match.

// first match, then the 2nd and 3rd occurrence
printf("%d\n", str.Find("ababab", "ab"));
printf("%d\n", str.Find("ababab", "ab", 0, 2));
printf("%d\n", str.Find("ababab", "ab", 0, 3));
printf("%d\n", str.Find("hello", "z"));

0
2
4
-1

str.FindLast

str.FindLast(hay, needle [, start]) -> int

Finds the LAST appearance of needle (searching backwards). start is the upper bound on the largest starting index considered.

The 0-based byte index of the last match, or -1 if none.

// last 'ab', then backwards from index 3
printf("%d\n", str.FindLast("ababab", "ab"));
printf("%d\n", str.FindLast("ababab", "ab", 3));

4
2

str.FindChar

str.FindChar(hay, code [, start]) -> int

Finds the first appearance of a single byte (character code) from start. The fastest search, because it uses memchr directly.

The 0-based index of the byte, or -1 if not found.

// look for 'l' (code 108)
printf("%d\n", str.FindChar("hello", 108));
printf("%d\n", str.FindChar("hello", 108, 3));

2
3

str.FindAnyOf

str.FindAnyOf(hay, set [, start]) -> int

Returns the first position where the character of hay IS in the set.

The index of the first matching character, or -1 if none is in the set.

// position of the first digit
printf("%d\n", str.FindAnyOf("abc123", "0123456789"));

3

str.FindNotOf

str.FindNotOf(hay, set [, start]) -> int

Returns the first position where the character of hay is NOT in the set.

The index of the first character not in the set, or -1 if all are in it.

// first non-space character
printf("%d\n", str.FindNotOf(" x", " "));

3

str.Count

str.Count(hay, needle) -> int

Counts the non-overlapping appearances of needle in hay.

The number of occurrences (integer). Counting is non-overlapping.

printf("%d\n", str.Count("ababab", "ab"));
printf("%d\n", str.Count("aaaa", "aa"));

3
2

str.Contains

str.Contains(hay, needle) -> int

Tells whether needle occurs anywhere in hay.

1 if it contains needle; 0 if not.

printf("%d\n", str.Contains("hello world", "wor"));

1

str.StartsWith

str.StartsWith(hay, prefix) -> int

Tells whether hay begins with prefix.

1 if it starts with prefix; 0 if not (also 0 when prefix is longer than the text).

printf("%d\n", str.StartsWith("hello", "he"));

1

str.EndsWith

str.EndsWith(hay, suffix) -> int

Tells whether hay ends with suffix.

1 if it ends with suffix; 0 if not.

printf("%d\n", str.EndsWith("hello", "lo"));

1

str.Sub

str.Sub(s, start [, len]) -> string

Returns a substring of length len from position start. When len is omitted, it runs to the end of the string.

The new substring. If start is past the end of the string, returns an empty string.

printf("%s\n", str.Sub("hello world", 6));
printf("%s\n", str.Sub("hello world", 0, 5));
printf("%s\n", str.Sub("hello", -2));

world
hello
lo

str.Left

str.Left(s, n) -> string

Returns the first n characters of the string.

A new string of the first n characters.

printf("%s\n", str.Left("hello", 3));

hel

str.Right

str.Right(s, n) -> string

Returns the last n characters of the string.

A new string of the last n characters.

printf("%s\n", str.Right("hello", 3));

llo

str.Upper

str.Upper(s) -> string

Converts the text to upper case (ASCII a–z only).

The upper-cased new string.

printf("%s\n", str.Upper("Hello"));

HELLO

str.Lower

str.Lower(s) -> string

Converts the text to lower case (ASCII A–Z only).

The lower-cased new string.

printf("%s\n", str.Lower("Hello"));

hello

str.Reverse

str.Reverse(s) -> string

Reverses the order of the string's bytes.

The reversed new string.

printf("%s\n", str.Reverse("abc"));

cba

str.Trim

str.Trim(s) -> string

Strips leading AND trailing whitespace characters (space, tab, newline) from the string.

The new string trimmed on both sides.

// the [] only shows the boundary
printf("[%s]\n", str.Trim(" hi "));

[hi]

str.TrimLeft

str.TrimLeft(s) -> string

Strips whitespace only from the START of the string.

The new string trimmed on the left.

printf("[%s]\n", str.TrimLeft(" hi "));

[hi ]

str.TrimRight

str.TrimRight(s) -> string

Strips whitespace only from the END of the string.

The new string trimmed on the right.

printf("[%s]\n", str.TrimRight(" hi "));

[ hi]

str.TrimChars

str.TrimChars(s, set) -> string

Strips the characters of the given set from both ends.

The new string trimmed of the set's characters on both sides.

printf("[%s]\n", str.TrimChars("xxhixx", "x"));

[hi]

str.Replace

str.Replace(s, from, to [, maxCount]) -> string

Replaces every (or at most maxCount) occurrence of from with to.

The new, replaced string.

printf("%s\n", str.Replace("a.b.c", ".", "-"));
printf("%s\n", str.Replace("aaaa", "a", "b", 2));

a-b-c
bbaa

str.Repeat

str.Repeat(s, n) -> string

Concatenates the string n times.

The new string repeated n times. A too-large result raises a runtime error.

printf("%s\n", str.Repeat("ab", 3));

ababab

str.PadLeft

str.PadLeft(s, width [, code]) -> string

Pads the string on the left up to the desired width with the given character.

The new left-padded string (at least width long).

// the code of '0' is 48
printf("%s\n", str.PadLeft("7", 3, 48));

007

str.PadRight

str.PadRight(s, width [, code]) -> string

Pads the string on the right up to the desired width with the given character.

The new right-padded string.

printf("[%s]\n", str.PadRight("7", 3));

[7 ]

str.Insert

str.Insert(s, pos, ins) -> string

Inserts the ins text at position pos.

The new string with the inserted part.

printf("%s\n", str.Insert("helloworld", 5, " "));

hello world

str.Remove

str.Remove(s, pos [, len]) -> string

Removes len characters starting at pos. When len is omitted, it removes to the end.

The new string without the removed part.

printf("%s\n", str.Remove("hello world", 5, 1));

helloworld

str.Equals

str.Equals(a, b) -> int

Tests exact (byte-for-byte) equality.

1 if the two strings are identical; 0 if not.

printf("%d\n", str.Equals("abc", "abc"));

1

str.EqualsIgnoreCase

str.EqualsIgnoreCase(a, b) -> int

Tests case-insensitive equality (ASCII).

1 if they are equal ignoring case; 0 if not.

printf("%d\n", str.EqualsIgnoreCase("AB", "ab"));

1

str.Compare

str.Compare(a, b) -> int

Compares two strings lexicographically (byte by byte).

-1 if a is less than b; 0 if equal; 1 if a is greater.

printf("%d\n", str.Compare("abc", "abd"));
printf("%d\n", str.Compare("abc", "abc"));

-1
0

str.CompareIgnoreCase

str.CompareIgnoreCase(a, b) -> int

Case-insensitive lexicographic comparison (ASCII).

-1 / 0 / 1, ignoring case.

printf("%d\n", str.CompareIgnoreCase("ABC", "abc"));

0

str.Len

str.Len(s) -> int

Returns the length of the string in bytes.

The number of bytes up to the first NUL byte.

printf("%d\n", str.Len("hello"));

5

str.IsEmpty

str.IsEmpty(s) -> int

Tells whether the string is empty.

1 if the string is empty; 0 otherwise.

printf("%d\n", str.IsEmpty(""));
printf("%d\n", str.IsEmpty("x"));

1
0

str.CharAt

str.CharAt(s, index) -> int

Returns the code of the byte at position index.

The byte code between 0 and 255, or -1 if the index is out of range.

// the code of 'B' is 66
printf("%d\n", str.CharAt("ABC", 1));
printf("%d\n", str.CharAt("ABC", 9));

66
-1

str.ToInt

str.ToInt(s) -> int

Reads an integer from the start of the string (base 10). Lenient: it ignores trailing junk after the number.

The parsed integer; 0 if it does not start with a number.

printf("%d\n", str.ToInt("42"));
printf("%d\n", str.ToInt("12abc"));

42
12

str.ToIntOr

str.ToIntOr(s, default) -> int

Converts to an integer, but ONLY if the whole string is a clean integer (no leftover). Otherwise it returns the default.

The number if the whole string is a valid integer; otherwise the default.

printf("%d\n", str.ToIntOr("42", -1));
printf("%d\n", str.ToIntOr("12abc", -1));

42
-1

str.IsInt

str.IsInt(s) -> int

Checks whether the whole string is a single valid integer (with no leftover).

1 if it is a clean integer; 0 if not (an empty string is also 0).

printf("%d\n", str.IsInt("42"));
printf("%d\n", str.IsInt("12abc"));

1
0

str.ToFloat

str.ToFloat(s) -> float

Reads a floating-point number from the start of the string. Lenient, like ToInt.

The parsed floating-point value; 0.0 if it is not a number.

// print the float readably via FromFloat
printf("%s\n", str.FromFloat(str.ToFloat("3.14"), 2));

3.14

str.FromInt

str.FromInt(n) -> string

Builds a string from an integer (base 10).

The textual form of the number.

printf("%s\n", str.FromInt(42));

42

str.FromFloat

str.FromFloat(x [, decimals]) -> string

Builds a string from a floating-point (or integer) number with a fixed number of decimals.

The textual form of the number with decimals decimal places.

printf("%s\n", str.FromFloat(3.14159));
printf("%s\n", str.FromFloat(3.14159, 2));

3.141590
3.14

str.FromChar

str.FromChar(code) -> string

Builds a one-character string from a single byte code.

A string of length one containing that byte.

// the code of 'A' is 65
printf("%s\n", str.FromChar(65));

A

str.SplitCount

str.SplitCount(s, sep) -> int

Counts how many fields the sep separator would split the string into.

The number of fields (always at least 1).

printf("%d\n", str.SplitCount("a,b,c", ","));

3

str.SplitGet

str.SplitGet(s, sep, index) -> string

Returns the index-th (0-based) field of the string split along sep.

The field's text. A negative or too-large index yields an empty string.

printf("%s\n", str.SplitGet("a,b,c", ",", 1));
// index too large -> empty
printf("[%s]\n", str.SplitGet("a,b,c", ",", 9));

b
[]

Practical notes

Performance

• The search functions (Find, Count, Replace, SplitGet) use the fast memchr/memcmp pair internally rather than a naive pairwise scan, so they are fast even on large text.

• To walk over every match in a string, call Find in a loop while advancing the start parameter (a single pass). The occurrence parameter recounts from the start of the string on every call, so it is slower for many matches.

• The character-set functions (FindAnyOf, FindNotOf, TrimChars) build a 256-entry table, so their cost scales with the length of the text, regardless of the size of the set.

Common pitfalls

• Byte vs character: Len, CharAt and indices count bytes. In accented (UTF-8) text a single "letter" can be several bytes, and Upper/Lower/Reverse are correct only for the ASCII range.

• Binary data: if the text may contain a 0 byte, the str plugin only "sees" up to the first zero — use the blob plugin in that case.

• ToInt vs ToIntOr: ToInt silently returns 0 for invalid input; if you must distinguish a real 0 from an error, use IsInt or ToIntOr.

• FromFloat decimals: it gives 6 decimals by default; for display it is almost always worth giving an explicit decimals value.

Error handling

The functions report a wrong argument count or type as a runtime error, and the script stops. Content-level edge cases (a negative or too-large index, no match), however, are handled not as errors but with a graceful return value: searches return -1, and slicing functions return an empty string or a result clamped to the boundary. So in the usual cases you do not need extra guard checks.

The map key-value plugin

Thread-safe associative store — complete function reference