Document spans, interop, csv, parallel, and combine

- Language basics: add Span/RoSpan section with construction, operations
  and lifetime rules
- Writing programs: add full Spans in .NET interop subsubsection
  (arrays-as-spans, #:copy for span returns, span values and their
  restrictions); update performance notes to remove "without spans"
- Standard library: split std/units+rational into two subsections with
  fuller descriptions; add std/parallel+combine, std/interop, and
  text/csv+csv-codec subsections
- index: mention CSV in the text module description

🤖 Generated with [ECA](https://eca.dev) (anthropic/claude-sonnet-4-6)

Co-Authored-By: eca-agent <git@eca.dev>
This commit is contained in:
Linus Björnstam 2026-11-09 16:11:17 +01:00
parent d16bf477a1
commit 6ee8ca62b9
4 changed files with 109 additions and 7 deletions

View file

@ -1332,6 +1332,18 @@ An @code{Array} is a plain .NET array: mutable, fixed in length, and exactly wha
Every evaluation of an array literal makes a fresh array, so a function that returns @code{#[0 0]} returns a new one each time.
To work on part of an array without copying it, make a span: @code{(Span %a)} is a writable view (.NET's @code{Span<T>}) and @code{(RoSpan %a)} is a read-only view (@code{ReadOnlySpan<T>}).
@codeblock[#:lang "bjolang"]|{
(def s (array->span a #:from 1 #:to 3))
(span-length s) ;; 2
(span-ref s 0) ;; 2
(span-set! s 0 99) ;; writes into a: a is now #[42 99 3]
(span->array s) ;; #[99 3], a fresh copy
}|
A span is valid only while the call that made it runs, so it can be a local variable, a function argument or a return value, and the compiler refuses it anywhere it could outlive the call (such as inside another collection or across a yield point). The section on .NET interop in Part 2 covers the full rules and how spans work with .NET methods.
@subsubsection{Maps}
@code{Map} is an immutable hash map. The @code{#map(...)} literal takes entries written as @code{(key value)}, @code{[key value]} or @code{(key . value)}.