docs(strings): document the embedded standard library and STRING values

Describe -no-std, C_STRING literals, library function semantics and
owning string lifetimes in the manuals and contributor guidance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 28 insertions, 23 deletions

diff --git a/pseudocode-lib/README.md b/pseudocode-lib/README.md
index 9182b14..e0819bf 100644
--- a/pseudocode-lib/README.md
+++ b/pseudocode-lib/README.md
@@ -1,36 +1,41 @@
-# Experimental string library
+# Standard pseudocode library
 
-Build with `cmake --build build`. Include the built library in your program and pass it as a compiler input:
+`cpsc` embeds `std.cps`, its imported `string.cps`, and the matching `string.o`. Programs use STRING and its functions without INCLUDE statements or extra command-line inputs:
 
 ```text
-INCLUDE "build/pseudocode-lib/_exp_string.cps"
-DECLARE Greeting : _EXP_STRING((C_STRING)"hello")
-CALL _EXP_STRING_OUTPUT(Greeting & _EXP_STRING_NUM_TO_STR(42))
+DECLARE Greeting : STRING
+Greeting <- "hello"
+OUTPUT Greeting & NUM_TO_STR(42)
 ```
 
-```sh
-build/cpsc prog.cps build/pseudocode-lib/_exp_string.cps
-build/cpsc prog.cps build/pseudocode-lib/_exp_string.cps -r
-```
-
-INCLUDE paths are relative to the program. Adjust them when the program is elsewhere.
-
-`_EXP_STRING` owns an unbounded `std::string` through one handle. Constructors accept no arguments, another `_EXP_STRING`, `C_STRING`, or `(INTEGER count, C_CHAR character)`. Cast literals to C types explicitly; built-in STRING is not a constructor argument. Copy construction and assignment own independent strings. `_HANDLE` is public only for library implementation access; do not modify or free it.
-
-The library provides `&`, `_EXP_STRING_NUM_TO_STR` (INTEGER/REAL), `_EXP_STRING_STR_TO_NUM` (REAL), `_EXP_STRING_LENGTH` (byte length) and `_EXP_STRING_OUTPUT` (text plus newline). Numeric formatting uses `std::to_string`; parsing uses `std::stod` and requires full consumption. C++ standard exceptions print the user call line and are catchable with TRY/CATCH. The built-in STRING remains available with its existing lifetime and NUL limitations. Owning class values inside whole-record or BYVAL-array copies still have bitwise-copy limitations.
+Use `-no-std` to disable automatic loading and linking. For an explicit library build, include the built unit from your program and pass every imported unit as a compiler input:
 
-`_EXP_STRING_LEFT(S : _EXP_STRING, Count : INTEGER)` returns a new `_EXP_STRING` containing up to Count bytes from the beginning. Nonpositive counts return an empty string; counts exceeding the length return the whole string. Embedded NUL bytes are preserved.
+```text
+INCLUDE "build/pseudocode-lib/std.cps"
+OUTPUT LENGTH("hello")
+```
 
-`_EXP_STRING_RIGHT(S : _EXP_STRING, Count : INTEGER)` returns a new `_EXP_STRING` containing up to Count bytes from the end. Nonpositive counts return an empty string; counts exceeding the length return the whole string. Embedded NUL bytes are preserved.
+```sh
+cmake --build build
+build/cpsc -no-std prog.cps build/pseudocode-lib/std.cps build/pseudocode-lib/string.cps -r
+```
 
-`_EXP_STRING_MID(S : _EXP_STRING, Start : INTEGER, Count : INTEGER)` returns a new `_EXP_STRING` containing up to Count bytes from the one-based Start position. Starts below 1 clamp to 1; starts beyond the end and nonpositive counts return an empty string. Counts clamp to the remaining bytes. Embedded NUL bytes are preserved.
+INCLUDE paths are relative to the including source. Adjust the example paths when the program is elsewhere. Native compilation and `-r` automatically link the required library object. `-S` only emits IR; manually linking that IR requires `build/pseudocode-lib/string.o` and a compatible C++ runtime.
 
-`_EXP_STRING_LCASE(S : _EXP_STRING)` returns a new `_EXP_STRING` with letters converted to lower case. Its `(Ch : CHAR)` overload returns CHAR, following guide section 5.5. Nonletters and embedded NUL bytes are preserved; the source is unchanged. Use ASCII for predictable case conversion.
+STRING is an owning class backed by `std::string`. Constructors accept no arguments, another STRING, C_STRING, or `(INTEGER count, C_CHAR character)`. Copies and assignments are independent, including STRING fields inside records and BYVAL arrays. `_HANDLE` is public for implementation access; do not modify or free it.
 
-`_EXP_STRING_UCASE(S : _EXP_STRING)` returns a new `_EXP_STRING` with letters converted to upper case. Its `(Ch : CHAR)` overload returns CHAR, following guide section 5.5. Nonletters and embedded NUL bytes are preserved; the source is unchanged. Use ASCII for predictable case conversion.
+Ordinary double-quoted literals construct STRING through `NEW(C_STRING)` and require a visible STRING class. They retain the legacy NUL truncation: `"a\0b"` constructs `"a"`. The adjacent uppercase suffix `"hello"C` creates C_STRING directly and works with `-no-std`. Explicit casts convert C_STRING to an owning STRING, treating null as empty. `(C_STRING)Text` and `Text.C_STR()` borrow a NUL-terminated pointer valid until Text changes or is destroyed. INPUT reads an unbounded whitespace-delimited word; OUTPUT and file I/O use NUL-terminated text.
 
-`_EXP_STRING_ASC(S : _EXP_STRING)` returns the unsigned code of the first byte as INTEGER, or 0 for an empty string. Its `(Ch : CHAR)` overload returns the unsigned byte code of Ch. For ASCII characters this is the ASCII code.
+The library provides `&`, six case-sensitive content comparisons, and these ordinary functions:
 
-`_EXP_STRING_CHR(Code : INTEGER)` returns a new `_EXP_STRING` containing the low eight bits of Code as one byte. Unlike built-in STRING, `_EXP_STRING` preserves NUL: `_EXP_STRING_CHR(0)` has length 1.
+- `LENGTH(S)` returns the byte length, including embedded NUL bytes constructed through CHR or the count/character constructor.
+- `LEFT(S, Count)` and `RIGHT(S, Count)` return up to Count bytes. Nonpositive counts return empty; oversized counts return the whole string.
+- `MID(S, Start, Count)` uses a one-based Start. Starts below 1 clamp to 1; starts beyond the end and nonpositive counts return empty. Counts clamp to the remaining bytes.
+- `LCASE(CHAR)` and `UCASE(CHAR)` return CHAR, following guide section 5.5. STRING overloads return independent strings. Nonletters and embedded NUL bytes are preserved; use ASCII for predictable case conversion.
+- `ASC(CHAR)` and `ASC(STRING)` return the unsigned character or first-byte code; an empty string returns zero.
+- `CHR(Code)` returns a one-byte STRING containing the low eight bits. `LENGTH(CHR(0))` is 1.
+- `NUM_TO_STR(INTEGER)` and `NUM_TO_STR(REAL)` use C++17 `std::to_string`, with six fractional digits for REAL.
+- `STR_TO_NUM(S)` returns REAL using `std::stod` and requires full consumption. Invalid text, trailing junk, and out-of-range values throw.
+- `IS_NUM(S)` tests full consumption by `strtod` without throwing for invalid text. Leading whitespace is accepted; trailing whitespace, trailing junk, empty input, and embedded NUL bytes are rejected.
 
-`_EXP_STRING_IS_NUM(S : _EXP_STRING)` returns BOOLEAN indicating whether a nonempty string is fully consumed by `strtod`. Leading whitespace is accepted; trailing whitespace, other trailing text, and embedded NUL bytes are rejected. Invalid numeric text returns FALSE without throwing.
+Library C++ exceptions print the user call line and can be caught with TRY/CATCH. Library functions follow the guide where specified; LEFT, STRING case conversion, byte-code and numeric-conversion functions remain compatibility extensions.