StrLib — Plan9Basic Documentation

StrLib — String Library

Comprehensive string manipulation with 63 functions (75 registered signatures with overloads) across 17 categories. Covers case conversion, character ops, number formatting, substring extraction, search, validation, comparison, padding, multi-line handling, delimited parsing, file I/O, and clipboard.

Characteristic	Description
Indexing	Zero-based for most functions (exceptions noted)
Error Handling	Functions set error code via `strerror()`
Unicode	Full support for characters 0–65535
Safe Operations	Edge cases handled gracefully without crashes
Locale	`str$()` uses system locale; `stri$()` always uses period

Error Codes

Code	Constant	Description
0	ERR_NONE	No error
1	ERR_INDEX_OUT_OF_BOUNDS	Index outside valid range
2	ERR_INVALID_ARGUMENT	Invalid parameter value
3	ERR_STRING_EMPTY	Operation on empty string
4	ERR_FILE_ERROR	File operation failed
5	ERR_CLIPBOARD_ERROR	Clipboard operation failed

Function	Signature	Description
`strerror()`	`strerror@`	Get last error code (0 = success)

Case Conversion

Function	Signature	Description
`lcase$(s$)`	`lcase$@$`	Lowercase
`ucase$(s$)`	`ucase$@$`	Uppercase
`alcase$(s$)`	`alcase$@$`	ANSI lowercase (better for accents)
`aucase$(s$)`	`aucase$@$`	ANSI uppercase (better for accents)
`proper$(s$)`	`proper$@$`	Title case (capitalize each word)
`swapcase$(s$)`	`swapcase$@$`	Swap upper/lower case

╯ plan9basic─◻✕
println lcase$("Hello World")    ' hello world
println ucase$("Hello World")    ' HELLO WORLD
println alcase$("CAFÉ")          ' café
println aucase$("café")          ' CAFÉ
println proper$("hello world")   ' Hello World
println swapcase$("Hello")       ' hELLO

ⓘ Note: lcase$/ucase$ use standard rules. alcase$/aucase$ use ANSI locale rules for better accented character support (é, ü, ñ, etc.).

Trimming

Function	Signature	Description
`trim$(s$)`	`trim$@$`	Trim both sides
`ltrim$(s$)`	`ltrim$@$`	Trim left side
`rtrim$(s$)`	`rtrim$@$`	Trim right side

╯ plan9basic─◻✕
println "["; trim$("  Hello  "); "]"     ' [Hello]
println "["; ltrim$("  Hello  "); "]"    ' [Hello  ]
println "["; rtrim$("  Hello  "); "]"    ' [  Hello]

Character Operations

Function	Signature	Description
`chr$(code)`	`chr$@n`	Create character from Unicode code (0–65535)
`chr$(s$, pos)`	`chr$@$n`	Get character at position (0-based)
`chr$(s$, pos, c$)`	`chr$@$n$`	Set character at position (0-based)

╯ plan9basic─◻✕
println chr$(65)              ' A
println chr$(8364)            ' € (Euro sign)

text$ = "Hello"
println chr$(text$, 0)        ' H
println chr$(text$, 4)        ' o

println chr$(text$, 0, "J")   ' Jello
println chr$(text$, 4, "a")   ' Hella

ⓘ Note: Error codes: ERR_INVALID_ARGUMENT if code outside 0–65535, ERR_STRING_EMPTY if string is empty, ERR_INDEX_OUT_OF_BOUNDS if position invalid.

Number ↔ String Conversion

Function	Signature	Description
`str$(n)`	`str$@n`	Number to string (system locale)
`str$(n, dec)`	`str$@nn`	With fixed decimal places (locale)
`stri$(n)`	`stri$@n`	Number to string (always period)
`stri$(n, dec)`	`stri$@nn`	With fixed decimal places (period)
`hex$(n)`	`hex$@n`	Number to hexadecimal
`hex$(n, digits)`	`hex$@nn`	Hex with min digits (zero-padded)
`oct$(n)`	`oct$@n`	Number to octal
`bin$(n)`	`bin$@n`	Number to binary
`val(s$)`	`val@$`	String to number
`valcode()`	`valcode@`	Conversion error position (0 = ok)

╯ plan9basic─◻✕
println str$(3.14159)       ' 3.14159 or 3,14159 (locale)
println stri$(3.14159)      ' 3.14159 (always period)
println stri$(42, 3)        ' 42.000
println hex$(255)           ' FF
println hex$(255, 4)        ' 00FF
println oct$(64)            ' 100
println bin$(255)           ' 11111111

x = val("123")              ' x = 123
y = val("123abc")
println valcode()           ' 4 (error at position 4)

⚠ Warning: str$() uses the system locale (comma in Brazil/Europe, period in US). Use stri$() when generating JSON, CSV, or any data for interchange between systems.

⚠ Warning: alcase$() and aucase$() are Ansi, not “all”. They follow the locale, where lcase$() and ucase$() know only a-z. The two pairs agree on plain ASCII and part on every accented letter: ucase$("ação") leaves the accents alone and aucase$("ação") raises them.

⚠ Warning: lfill$() and rfill$() take the fill as a character code, not a string: lfill$("42", 5, asc("0")).

Substring Operations

Function	Signature	Description
`mid$(s$, start)`	`mid$@$n`	From position to end (0-based)
`mid$(s$, start, len)`	`mid$@$nn`	From position with length
`left$(s$, n)`	`left$@$n`	First n characters
`left$(s$)`	`left$@$`	First character
`right$(s$, n)`	`right$@$n`	Last n characters
`right$(s$)`	`right$@$`	Last character
`insert$(s$, ins$, pos)`	`insert$@$$n`	Insert at position (0-based)
`delete$(s$, pos, cnt)`	`delete$@$nn`	Delete at position (0-based)

╯ plan9basic─◻✕
println mid$("Hello World", 6)       ' World
println mid$("Hello World", 0, 5)    ' Hello
println left$("Hello World", 5)      ' Hello
println left$("Hello")               ' H
println right$("Hello World", 5)     ' World
println right$("Hello")              ' o

println insert$("AC", "B", 1)        ' ABC
println delete$("Hello World", 5, 6) ' Hello

ⓘ Note: All positions are 0-based. Values are clamped to valid ranges — no crashes on out-of-bounds access.

Padding & Filling

Function	Signature	Description
`ltab$(s$, width)`	`ltab$@$n`	Left-pad with spaces
`rtab$(s$, width)`	`rtab$@$n`	Right-pad with spaces
`lfill$(s$, width, chr)`	`lfill$@$nn`	Left-fill with character (ASCII code)
`rfill$(s$, width, chr)`	`rfill$@$nn`	Right-fill with character
`center$(s$, width)`	`center$@$n`	Center with spaces
`center$(s$, width, chr)`	`center$@$nn`	Center with fill character
`space$(n)`	`space$@n`	String of n spaces
`string$(n, chr)`	`string$@nn`	String of n characters (ASCII code)

╯ plan9basic─◻✕
println "["; ltab$("Hi", 10); "]"      ' [        Hi]
println "["; rtab$("Hi", 10); "]"      ' [Hi        ]
println lfill$("42", 5, 48)            ' 00042 (48 = '0')
println center$("Title", 11, 45)       ' ---Title---
println space$(5)                      ' "     "
println string$(5, 42)                 ' ***** (42 = '*')

String Information

Function	Signature	Description
`len(s$)`	`len@$`	String length (character count)
`asc(s$)`	`asc@$`	ASCII/Unicode code of first character

╯ plan9basic─◻✕
println len("Hello")    ' 5
println len("Olá")      ' 3 (Unicode-aware)
println len("")          ' 0
println asc("A")         ' 65
println asc("€")         ' 8364

String Validation

All validation functions return 1 (true) or 0 (false). Empty strings return 0.

Function	Signature	Description
`isnumeric(s$)`	`isnumeric@$`	Valid number? (accepts -, ., scientific)
`isalpha(s$)`	`isalpha@$`	All letters? (includes Unicode letters)
`isalnum(s$)`	`isalnum@$`	All alphanumeric?
`isdigits(s$)`	`isdigits@$`	All digits 0–9? (no -, ., or spaces)
`isspace(s$)`	`isspace@$`	All whitespace? (space, tab, newline)
`islower(s$)`	`islower@$`	All letters lowercase? (non-letters ignored)
`isupper(s$)`	`isupper@$`	All letters uppercase? (non-letters ignored)

╯ plan9basic─◻✕
println isnumeric("3.14")     ' 1
println isnumeric("abc")       ' 0
println isalpha("Hello")       ' 1
println isalpha("Hello123")    ' 0
println isdigits("12345")      ' 1
println isdigits("12.34")      ' 0
println islower("hello123")    ' 1 (digits ignored)
println isupper("HELLO 123")   ' 1 (spaces/digits ignored)

ⓘ Note: isnumeric() accepts decimal points, negative signs, and scientific notation. isdigits() only accepts bare digits 0–9.

Search Functions

Function	Signature	Description
`instr(s$, find$)`	`instr@$$`	Find position (0-based, -1 if not found)
`instr(s$, find$, start)`	`instr@$$n`	Find from position
`instrrev(s$, find$)`	`instrrev@$$`	Find last occurrence
`instrrev(s$, find$, pos)`	`instrrev@$$n`	Find last before position
`countstr(s$, find$)`	`countstr@$$`	Count non-overlapping occurrences
`containsstr(s$, find$)`	`containsstr@$$`	Contains? (case-sensitive, 1/0)
`containstext(s$, find$)`	`containstext@$$`	Contains? (case-insensitive, 1/0)
`startsstr(s$, pre$)`	`startsstr@$$`	Starts with? (case-sensitive)
`startstext(s$, pre$)`	`startstext@$$`	Starts with? (case-insensitive)
`endsstr(s$, suf$)`	`endsstr@$$`	Ends with? (case-sensitive)
`endstext(s$, suf$)`	`endstext@$$`	Ends with? (case-insensitive)

╯ plan9basic─◻✕
text$ = "banana"
println instr(text$, "an")           ' 1
println instr(text$, "an", 2)        ' 3
println instrrev(text$, "an")         ' 3
println countstr(text$, "a")          ' 3

println containsstr("Hello", "ell")   ' 1
println containstext("Hello", "ELL")  ' 1
println startsstr("Hello", "He")      ' 1
println endsstr("file.txt", ".txt")   ' 1

ⓘ Note: For startsstr/startstext and endsstr/endstext, the prefix/suffix is the first parameter.

String Comparison

Function	Signature	Description
`strcmp(s1$, s2$)`	`strcmp@$$`	Compare case-sensitive: -1, 0, or 1
`strcmpi(s1$, s2$)`	`strcmpi@$$`	Compare case-insensitive: -1, 0, or 1

╯ plan9basic─◻✕
println strcmp("apple", "banana")   ' -1 (a < b)
println strcmp("hello", "hello")    ' 0  (equal)
println strcmp("zebra", "apple")    ' 1  (z > a)
println strcmpi("Hello", "hello")   ' 0  (equal, ignoring case)

String Manipulation

Function	Signature	Description
`mulstring$(s$, n)`	`mulstring$@$n`	Repeat string n times
`replacestr$(s$, f$, r$)`	`replacestr$@$$$`	Replace all (case-sensitive)
`replacetext$(s$, f$, r$)`	`replacetext$@$$$`	Replace all (case-insensitive)
`reverse$(s$)`	`reverse$@$`	Reverse string
`stuffstring$(s$, p, d, i$)`	`stuffstring$@$nn$`	Insert/delete/replace (1-based!)

╯ plan9basic─◻✕
println mulstring$("Ha", 3)    ' HaHaHa
println replacestr$("Hello World", "World", "BASIC")  ' Hello BASIC
println replacetext$("The THE the", "the", "a")      ' a a a
println reverse$("Hello")        ' olleH

' stuffstring$ uses 1-based indexing!
println stuffstring$("Hello", 6, 0, " World")          ' Hello World
println stuffstring$("Hello World", 7, 5, "BASIC")     ' Hello BASIC

⚠ Warning: stuffstring$() uses 1-based indexing, unlike most other StrLib functions.

Multi-line String Functions

Function	Signature	Description
`count(s$)`	`count@$`	Count lines in string
`line$(s$, idx)`	`line$@$n`	Get line at index (0-based)
`line$(s$, idx, new$)`	`line$@$n$`	Set/replace line at index

╯ plan9basic─◻✕
text$ = "Apple" + chr$(10) + "Banana" + chr$(10) + "Cherry"
println count(text$)          ' 3
println line$(text$, 0)        ' Apple
println line$(text$, 1)        ' Banana

text$ = line$(text$, 1, "Orange")
println line$(text$, 1)        ' Orange

Delimited String Functions

Function	Signature	Description
`word$(s$, pos, delim$)`	`word$@$n$`	Extract word at position (1-based!)
`wordcount(s$, delim$)`	`wordcount@$$`	Count words in delimited string

╯ plan9basic─◻✕
csv$ = "John,Doe,35,Engineer"
println wordcount(csv$, ",")     ' 4
println word$(csv$, 1, ",")      ' John
println word$(csv$, 2, ",")      ' Doe
println word$(csv$, 3, ",")      ' 35
println word$(csv$, 4, ",")      ' Engineer

' Path parsing
path$ = "C:\\Users\\Andre\\Documents"
println word$(path$, 3, "\\")

⚠ Warning: word$() uses 1-based indexing — the first word is position 1.

File Operations

Function	Signature	Description
`opentext$(file$, enc$)`	`opentext$@$$`	Read entire text file
`savetext$(file$, enc$, content$)`	`savetext$@$$$`	Write text file

Encoding	Aliases
UTF-8	`utf8`, `utf-8`
UTF-7	`utf7`, `utf-7`
UTF-16 LE	`unicode`, `utf-16`, `utf-16le`
UTF-16 BE	`utf-16be`, `big endian unicode`
ANSI	`ansi`
ASCII	`ascii`

╯ plan9basic─◻✕
content$ = opentext$("data.txt", "utf-8")
if strerror() = 0 then
    println "Loaded: "; len(content$); " chars, "; count(content$); " lines
endif

savetext$("output.txt", "utf-8", content$)
if strerror() = 0 then
    println "File saved"
endif

Clipboard Operations

Function	Signature	Description
`copytext$(s$)`	`copytext$@$`	Copy string to clipboard
`pastetext$()`	`pastetext$@`	Get text from clipboard

╯ plan9basic─◻✕
copytext$("Hello from Plan9Basic!")
if strerror() = 0 then
    println "Copied to clipboard"
endif

clip$ = pastetext$()
if strerror() = 0 then
    println "Clipboard: "; clip$
endif

Complete Examples

CSV Data Parser

╯ csv_parser.bas─◻✕
' Parse delimited data with word$() and wordcount()
println "=== CSV Parser Demo ==="
println ""

csvLine$ = "John,Doe,35,Engineer,New York"
println "CSV Line: "; csvLine$
println "Fields: "; wordcount(csvLine$, ",")
println ""

println "  First Name: "; word$(csvLine$, 1, ",")
println "  Last Name:  "; word$(csvLine$, 2, ",")
println "  Age:        "; word$(csvLine$, 3, ",")
println "  Job:        "; word$(csvLine$, 4, ",")
println "  City:       "; word$(csvLine$, 5, ",")
println ""

' Iterate all fields
for i = 1 to wordcount(csvLine$, ",")
    println "  ["; i; "] "; word$(csvLine$, i, ",")
next

Password Strength Checker

╯ password.bas─◻✕
function checkPassword$(password$) local score, hasUpper, hasLower, hasDigit, hasSpecial, i, c$
    score = 0
    hasUpper = 0
    hasLower = 0
    hasDigit = 0
    hasSpecial = 0
    
    if len(password$) >= 8 then
        score = score + 1
    endif
    if len(password$) >= 12 then
        score = score + 1
    endif
    
    for i = 0 to len(password$) - 1
        c$ = chr$(password$, i)
        if isupper(c$) = 1 then
            hasUpper = 1
        endif
        if islower(c$) = 1 then
            hasLower = 1
        endif
        if isdigits(c$) = 1 then
            hasDigit = 1
        endif
        if containsstr("!@#$%^&*()_+-=", c$) = 1 then
            hasSpecial = 1
        endif
    next
    
    score = score + hasUpper + hasLower + hasDigit + hasSpecial
    
    if score <= 2 then
        return "Weak"
    else if score <= 4 then
        return "Medium"
    else
        return "Strong"
    endif
endfunction

println checkPassword$("password")          ' Weak
println checkPassword$("Pass123")           ' Medium
println checkPassword$("MyP@ssw0rd!")       ' Strong

Table Formatter

╯ table_fmt.bas─◻✕
' Formatted table output using center$() and padding
col1 = 15
col2 = 10
col3 = 12

println string$(col1 + col2 + col3 + 8, 45)
println "| "; center$("Name", col1); " | "; center$("Age", col2); " | "; center$("City", col3); " |"
println "|"; string$(col1 + 2, 45); "|"; string$(col2 + 2, 45); "|"; string$(col3 + 2, 45); "|"
println "| "; rtab$("John Doe", col1); " | "; ltab$(str$(35), col2); " | "; rtab$("New York", col3); " |"
println "| "; rtab$("Jane Smith", col1); " | "; ltab$(str$(28), col2); " | "; rtab$("London", col3); " |"
println string$(col1 + col2 + col3 + 8, 45)

String Sort with Comparison

╯ sort.bas─◻✕
' Bubble sort using strcmp()
names$ = "Zebra" + chr$(10) + "Apple" + chr$(10) + "Mango" + chr$(10) + "Banana"

n = count(names$)
for i = 0 to n - 2
    for j = 0 to n - 2 - i
        if strcmp(line$(names$, j), line$(names$, j + 1)) > 0 then
            temp$ = line$(names$, j)
            names$ = line$(names$, j, line$(names$, j + 1))
            names$ = line$(names$, j + 1, temp$)
        endif
    next
next

println "Sorted:"
for i = 0 to count(names$) - 1
    println "  "; line$(names$, i)
next

Quick Reference

Function	Signature	Description
`strerror()`	`strerror@`	Last error code
`lcase$(s$) / ucase$(s$)`	`*case$@$`	Standard case conversion
`alcase$(s$) / aucase$(s$)`	`a*case$@$`	ANSI locale case conversion
`proper$(s$)`	`proper$@$`	Title case
`swapcase$(s$)`	`swapcase$@$`	Swap case
`trim$(s$) / ltrim$ / rtrim$`	`*trim$@$`	Whitespace trimming
`chr$(n) / chr$(s$,pos) / chr$(s$,pos,c$)`	`chr$@...`	Character create/get/set
`str$(n) / str$(n,dec)`	`str$@n[n]`	Number to string (locale)
`stri$(n) / stri$(n,dec)`	`stri$@n[n]`	Number to string (invariant)
`hex$(n) / oct$(n) / bin$(n)`	`*$@n`	Base conversion
`val(s$) / valcode()`	`val@$`	String to number
`mid$(s$,start[,len])`	`mid$@$n[n]`	Substring extraction
`left$(s$[,n]) / right$(s$[,n])`	`*$@$[n]`	First/last characters
`insert$(s$,ins$,pos)`	`insert$@$$n`	Insert at position
`delete$(s$,pos,cnt)`	`delete$@$nn`	Delete from position
`ltab$/rtab$/lfill$/rfill$/center$`	`*$@$n[n]`	Padding & filling
`space$(n) / string$(n,chr)`	`*$@n[n]`	Character repetition
`len(s$) / asc(s$)`	`len/asc@$`	Length and ASCII code
`is*(s$)`	`is*@$`	7 validation functions
`instr/instrrev/countstr`	`*@$$[n]`	Search functions
`contains/starts/ends*`	`*@$$`	6 match functions
`strcmp/strcmpi`	`str*@$$`	Comparison (-1, 0, 1)
`mulstring$/replace*/reverse$`	`*$@$...`	Manipulation
`stuffstring$(s$,p,d,i$)`	`stuffstring$@$nn$`	Insert/delete/replace (1-based)
`count(s$) / line$(s$,idx[,new$])`	`*@$n[$]`	Multi-line functions
`word$(s$,pos,d$) / wordcount(s$,d$)`	`*@$n$/$$`	Delimited parsing (1-based)
`opentext$/savetext$`	`*text$@$$[$]`	File I/O
`copytext$/pastetext$`	`*text$@...`	Clipboard

63 unique functions, 75 registered signatures with overloads.