types.String.tolower

Method on every string

pure string.tolower([start: number, end: number], ...): any

Returns a copy of str with the ASCII letters in [start, end) lowercased.

The binding carries no declaration string, so the VM cannot report parameter names. The names above are from this page; the types and attributes still come from the VM. The VM also cannot tell an optional parameter from a variadic tail here, so read the brackets and any trailing ... from the prose below, not from the signature.

Parameters

`start`	number	index of the first byte to convert; defaults to 0 optional
`end`	number	index one past the last byte to convert; defaults to `str.len()` optional
`...`	any	not a real parameter; see Notes repeats

Return value

A copy of str the same length as the original, with every byte in [start, end) that is A-Z replaced by its lowercase letter. Bytes outside the range, and bytes inside it that are not A-Z (including any byte of a multi-byte character), are copied unchanged. With no arguments the whole string is lowercased.

Errors

Throws wrong indexes when end < start after negative indices (counted from the end, as for types.String.slice) are resolved. Throws slice out of range when end > str.len() or the resolved start < 0.

Unlike types.String.slice, an out-of-range or inverted [start, end) throws here instead of clamping - despite both functions reading their range with the same helper.

Notes

Takes 0, 1 or 2 arguments, not the variadic tail the VM's dump implies (it shows tolower([arg1: number, arg2: number], ...) because this binding carries no declaration string).

Case conversion only ever touches the ASCII bytes A-Z; there is no locale and no Unicode case folding, so a non-ASCII byte is never altered.

Example

examples/types/string/tolower.nut

println("\"ABC\".tolower() =", "ABC".tolower())
println("\"ABCDEF\".tolower(1, 3) =", "ABCDEF".tolower(1, 3))   // only the given range is converted

try { "ABCDEF".tolower(2, 100) } catch (e) println("\"ABCDEF\".tolower(2, 100) throws:", e)
try { "ABCDEF".tolower(3, 1) } catch (e) println("\"ABCDEF\".tolower(3, 1) throws:", e)

Output:

"ABC".tolower() = abc
"ABCDEF".tolower(1, 3) = AbcDEF
"ABCDEF".tolower(2, 100) throws: slice out of range
"ABCDEF".tolower(3, 1) throws: wrong indexes