String library reference

Strings are valid UTF-8 independent values. Default parameters borrow without copying; results own their storage. Positions, lengths and padding widths below count Unicode scalar values, starting at zero. A combining sequence or emoji may contain several scalars. Equality and search are exact and case-sensitive. No implicit normalization, locale tailoring, or numeric conversion occurs.

Functions

All integer arguments/results use INTEGER (signed 64-bit). Fallible calls are checked automatically, including calls whose successful results are discarded; inline TRY is optional.

MID/INSTRFROM reject negative starts and starts beyond LEN. LEFT/RIGHT/MID reject negative counts; excessive nonnegative counts clamp to available text. SPACE/REPEAT reject negative counts. Padding widths and slicing positions are not display-column measurements.

VAL requires the entire trimmed input to be optional ASCII + or - followed by ASCII decimal digits. Empty input, embedded whitespace, fractional/exponent/radix notation, and trailing characters fail. The full signed 64-bit range is accepted. VAL parses INTEGER; STR also formats DOUBLE. Use checked CDBL(text) / VALDOUBLE(text) for floating-point parsing; see the math reference .

LINES recognizes CRLF as one boundary, plus LF, CR, vertical tab, form feed, U+001C–U+001E, NEL, line separator and paragraph separator. Empty input yields an empty list; a trailing line boundary does not add a final empty element. SPLIT with a nonempty separator preserves final empty fields. Its separator is optional and defaults to “”: omitted/empty separators split into Unicode code points, with empty input producing an empty list. Combining marks remain separate entries.

FORMAT requires exactly as many values as {} placeholders, and balanced/escaped braces. Values are strings: use STR explicitly for numeric values. Width/precision/type format specifications are deferred.

Traditional string-result spellings with a trailing dollar are optional call aliases, such as LEFT$(text, count), UCASE$(text) and STR$(value). They are recognized for the string-result functions listed above except UNICODEVERSION; they do not introduce typed variable suffixes or arbitrary dollar-named functions. INSTR/ASC/VAL/SPLIT/LINES return other types and have no dollar alias. This is modern BASIL behavior, not complete QuickBASIC compatibility: positions are zero-based, not-found is -1, CHR/ASC use Unicode scalars, and VAL is checked and strict.

Recoverable errors

NumericError and StringError are distinct built-in typed records with an INTEGER Code field. Construction is an ordinary value operation. User functions declare escaping types in FAILS, and RETURN ERROR explicitly forwards a caught error.

TRY
    PRINT UPPER("Straße")
    PRINT TRY LEFT("café 🌍", 4)
    PRINT JOIN(TRY SPLIT("one,two,three", ","), " | ")
    PRINT TRY VAL("42")
CATCH err AS StringError
    PRINT "String error code: " + STR(err.Code)
CATCH err AS NumericError
    PRINT "Number error code: " + STR(err.Code)
END TRY

Errors inside a catch target an outer matching catch or propagate from the function, never another clause of the same handler. Partial expressions and owned locals are cleaned on recoverable exit. Allocation failure remains fatal, separate from these errors, with no normal application-cleanup guarantee. Integer arithmetic overflow and invalid ByteAt access are also fatal.