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:
parent
d16bf477a1
commit
6ee8ca62b9
4 changed files with 109 additions and 7 deletions
|
|
@ -12,16 +12,26 @@ For more details, see @link["modules/std/prelude.html"]{@code{(std prelude)}}.
|
|||
Numbers beyond the operators. Integer division has Racket's names: @code{quotient} and @code{remainder} are what @code{/} and @code{%} do, and @code{modulo} takes the sign of the divisor, so @code{(modulo -1 10)} is 9. There are @code{gcd}, @code{lcm}, an integer @code{expt} and an exact @code{integer-sqrt} at every integer type, the @code{exact-} roundings from a double to an int, and the rest of @code{System.Math} over doubles. The prelude has @code{abs}, @code{min}, @code{max} and @code{clamp} from here without an import.
|
||||
For more details, see @link["modules/std/maths.html"]{@code{(std maths)}}.
|
||||
|
||||
@subsection{std/units and std/rational}
|
||||
@subsection{std/rational}
|
||||
|
||||
Units of measure, and exact fractions. @code{(std units)} declares SI for the units in types and quantity literals that "Language basics" describes: the eight base dimensions, the SI and binary prefixes, and about 270 units from @code{in} and @code{mi} to @code{eV}, @code{Sv} and @code{rpm}. The constants @code{c}, @code{gn} and @code{planck} are units too, so @code{(number-in v c)} is a speed as a fraction of light's. It is also a library for units at run time, when a unit comes as text, as in a calculator: @code{(convert-query "6000 m + 50 ft in mi")} gives @code{(Ok "3.737697 mi")}, and a @code{Measurement} is a number with a dimension that is checked when the program runs. Absolute temperatures are the types @code{Celsius} and @code{Fahrenheit} rather than units, and the decibels are functions. @code{(std rational)} has the operations of the built-in @code{rational} by name, the roundings to a @code{bigint}, and conversions to and from text, rounded once to a @code{double} or a @code{decimal}.
|
||||
For more details, see @link["modules/std/units.html"]{@code{(std units)}} and @link["modules/std/rational.html"]{@code{(std rational)}}.
|
||||
Exact fractions over @code{bigint}. @code{Rational} is the built-in @code{rational} type, kept in lowest terms with a positive denominator so equal fractions are equal values. @code{(rational n d)} constructs a fraction, @code{rational-num} and @code{rational-den} take it apart, and @code{rational+}, @code{rational*}, @code{rational-recip} and @code{rational-expt} work alongside the standard arithmetic operators. @code{string->rational} reads both @code{"1|60"} and decimal text such as @code{"0.3048"}, and @code{rational->double} and @code{rational->decimal} convert back.
|
||||
For more details, see @link["modules/std/rational.html"]{@code{(std rational)}}.
|
||||
|
||||
@subsection{std/units}
|
||||
|
||||
Units of measure, both at compile time and at run time. Importing the module declares the SI base dimensions and @code{information} (@code{b}), the SI and binary prefixes, and about 270 units with @code{def/dimension}, @code{def/prefix} and @code{def/unit}—the definitions that quantity literals like @code{<120 km/h>}, unit-annotated types like @code{(double m/s)}, and @code{number-in} use at compile time and erase at run time. For units that arrive as text at run time, @code{string->measurement}, @code{measurement-in} and @code{convert-query} (e.g. @code{(convert-query "6000 m + 50 ft in mi")}) parse, check dimensions and convert against a runtime unit table.
|
||||
For more details, see @link["modules/std/units.html"]{@code{(std units)}}.
|
||||
|
||||
@subsection{std/array and std/simd}
|
||||
|
||||
Two modules for numbers in bulk, with the CPU's vector instructions. @code{(std array)} has whole-array operations: @code{array-sum}, @code{array-dot}, @code{array-min}, @code{array-max}, @code{array-add!}, @code{array-scale!}, @code{array-count}, @code{array-index-of} and @code{array-fill!}. Each is one loop in the runtime, which works on as many elements per instruction as a vector register holds when the element is a primitive number, and one at a time for a type such as @code{bigint}. At @code{double}, a sum adds lane by lane, so its last bits can differ from a left fold. @code{(std simd)} has the vectors themselves, for the loops that the kernels do not cover. @code{(Simd128 %a)} and @code{(Simd256 %a)} are .NET's @code{Vector128<T>} and @code{Vector256<T>}, with a name per element type: @code{Float64x4} is four doubles, @code{UInt8x32} is 32 bytes. The operations are the methods of one trait, @code{Simd}, at both widths: @code{simd-add}, @code{simd-mul}, the comparisons @code{simd-lt} and the others, which give masks, @code{simd-select}, @code{simd-count-true}, @code{simd-sum} and more. A vector is made with @code{simd256-load}, @code{simd128-splat} or @code{simd256-zero}, and @code{simd256-whole} says where the elements after the last whole vector start. A 128-bit vector is fast on every x86-64 and ARM64 CPU. A 256-bit vector needs AVX2, and @code{simd256-accelerated?} says whether the CPU has it. The section on performance in "Writing programs" says when vectors pay.
|
||||
For more details, see @link["modules/std/array.html"]{@code{(std array)}} and @link["modules/std/simd.html"]{@code{(std simd)}}.
|
||||
|
||||
@subsection{std/parallel and std/combine}
|
||||
|
||||
Data-parallel work across CPU cores on dedicated compute threads. @code{(std parallel)} splits any @code{Chunkable} collection (@code{Range}, @code{Vec}, @code{Array}, @code{IArray}, @code{Map}, @code{HashSet}, @code{OrderedMap} and @code{OrderedSet}) into parts without copying elements. @code{in-parts} runs a function on each part and returns a vector of the part results; @code{in-parallel} joins the part results in order using @code{Combinable} from @code{(std combine)}; and @code{par-map}, @code{par-filter} and @code{par-for-each} operate over a whole collection. For an array, @code{part->span} gives each worker a writable @code{(Span %a)} over its own non-overlapping slice so an array can be updated in place across cores without locks. @code{(std combine)} provides the associative @code{Combinable} trait (@code{combine} and @code{combine-all}) for types with one natural ordered combination: @code{Vec}, @code{List}, @code{IArray}, @code{string}, sets and tuples.
|
||||
For more details, see @link["modules/std/parallel.html"]{@code{(std parallel)}} and @link["modules/std/combine.html"]{@code{(std combine)}}.
|
||||
|
||||
@subsection{std/fmt}
|
||||
|
||||
Formatting in two layers: interpolation and layout. @code{println*} prints strings, ints, doubles, chars and bools written in one vec. The layout layer is made of blocks: a @code{Block} is one piece of output, and every combinator takes its content as a block and gives back a block. A string, an int and a character are blocks, and so is a vec of blocks, such as @code{["x = " 7 nl]}. With them you pad, cut and align text, wrap and justify paragraphs, format numbers, and lay out tables with borders, a header, and columns that fit the width. The section on formatting text in "Writing programs" is a guide, with what goes in the brackets and what to write when it does not compile.
|
||||
|
|
@ -117,6 +127,11 @@ For more details, see @link["modules/std/mutable/vec.html"]{@code{(std mutable v
|
|||
An inbox is how .NET code gives work to Bjolang. A thread that is not a fiber, such as a timer, a @code{FileSystemWatcher} or a Kestrel thread, posts an item and returns. A fiber takes the item with its own handlers, parameters and cancellation scope. An inbox always has a capacity, and a @code{WhenFull} policy says what a post does when the inbox is full. @code{inbox-call} is a request and a reply: the .NET caller gets a @code{Task}, and a fiber answers it.
|
||||
For more details, see @link["modules/std/inbox.html"]{@code{(std inbox)}}.
|
||||
|
||||
@subsection{std/interop}
|
||||
|
||||
Bridges for .NET APIs that want something a Bjolang function or value is not. A Bjolang function is a @code{Func} whose @code{void} return is the unit value; @code{as-delegate} and @code{as-delegate/type} wrap a function in another .NET delegate type such as @code{Action}, @code{EventHandler} or a library's custom delegate. @code{add-event-handler!} and @code{remove-event-handler!} subscribe a Bjolang function to a .NET object's event by name. @code{clr-default} produces .NET's @code{default(T)} (such as @code{null} for a reference type or a @code{Nullable<T>}) when a .NET call requires one.
|
||||
For more details, see @link["modules/std/interop.html"]{@code{(std interop)}}.
|
||||
|
||||
@subsection{std/ports and std/net}
|
||||
|
||||
@code{(std ports)} reads and writes bytes on the prelude's ports. The byte reads @code{read-some-evt}, @code{read-bytes-evt} and @code{eof-evt} are CML events: a read that loses its @code{choose} takes nothing, so a read can race a timeout. @code{read-line} and @code{read-bytes} can be used on the same port. The module also drains ports into lists and vecs, streams them as a @code{Seq} or a channel, and has @code{byte-pipe}, a pair of ports with no file and no network, for tests. @code{(std net)} gives a TCP connection as a pair of these ports, so a protocol written for ports also runs over TCP. @code{accept-evt} is an event too: a branch that loses accepts nothing.
|
||||
|
|
@ -158,6 +173,11 @@ For more details, see @link["modules/text/bjodat.html"]{@code{(text bjodat)}} an
|
|||
@code{(text json)} reads JSON, exactly as RFC 8259 has it, into a @code{Json}: a union with a case for each kind of value. @code{parse-json} reads a string and @code{read-json} a port. A document that is not JSON is an @code{Err} that says the line and column where it went wrong. A number without a fraction or an exponent is a @code{JsonInt}, and an object is a @code{(Map string Json)}, so the order of its keys is not kept. @code{(text json-codec)} reads a record straight from the tree and back: @code{def/json-type} declares a record and the instances of @code{->json} and @code{json->} for it, with defaults, optional fields and other names for the keys. An @code{Option} is @code{null} when it is @code{None}. There is no writer yet, so a @code{Json} cannot be written out as text.
|
||||
For more details, see @link["modules/text/json.html"]{@code{(text json)}} and @link["modules/text/json-codec.html"]{@code{(text json-codec)}}.
|
||||
|
||||
@subsection{text/csv and text/csv-codec}
|
||||
|
||||
@code{(text csv)} reads and writes CSV (RFC 4180), with configurable @code{#:separator}, @code{#:quote-char} and @code{#:strict?}. It reads in three layers: @code{csv-next!} pulls one row at a time, @code{csv-fold} and @code{csv-for-each} stream rows without keeping the document in memory, and @code{parse-csv} reads the whole input. Each row is an @code{(IArray string)}, and malformed input returns a @code{CsvError} with its line, row and field. @code{write-csv} and @code{csv->string} quote fields only when needed. @code{(text csv-codec)} maps rows to records and back: @code{def/csv-type} declares a record and its @code{CsvRecord} instance, matching columns by header name (or @code{#:csv} alias) or by position when @code{#:header? #f}, with @code{parse-csv-records}, @code{csv-for-each-record} and @code{write-csv-records}.
|
||||
For more details, see @link["modules/text/csv.html"]{@code{(text csv)}} and @link["modules/text/csv-codec.html"]{@code{(text csv-codec)}}.
|
||||
|
||||
@subsection{text/xml}
|
||||
|
||||
XML, in three modules over @code{System.Xml}. @code{(text xml)} is the tree: names, elements, texts, comments and processing instructions, built by @code{xml-element} and the others, and taken apart by views. @code{(text xml read)} reads XML in four layers: a stream of signals, a fold after SSAX, a tree of your own type, and @code{parse-xml}, which gives a @code{Document}. @code{xml-for-each} reads a large document one element at a time. The defaults are the safe ones: a document with a DOCTYPE is refused unless asked for, and nothing external is ever resolved. @code{(text xml write)} writes a node or a document to a port or a string. It chooses the namespace prefixes, and content that XML cannot hold is an @code{XmlWriteError} rather than an exception.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue