velt/text

API reference

Text processing: For a walkthrough, read the guide.

import { RegExp, StringBuilder, escapeHtml } from "velt/text";

Exports

escapeHtmls with &, <, >, " and ' replaced by &, <, >, " and ': safe inside element content and in single- or double-quoted attribute values.RegExpErrorAn invalid pattern or flags (JS throws SyntaxError).RegExpA compiled regular expression: new RegExp("(\\d+)-(\\d+)", "g").RegExpMatchOne match: the matched text, where it is, and its capture groups.StringBuilderA string built by appending: toString() and take() return it without a copy.PatternA regular expression as a value to test strings with: RegExp implements it.

function

escapeHtml

#std/text/html.vlt:15

Re-exported from velt/text/html

function escapeHtml(s: string): string

s with &, <, >, " and ' replaced by &, <, >, " and ': safe inside element content and in single- or double-quoted attribute values. Other characters (including non-ASCII) are kept as they are.

class

RegExpError

#std/text/regex/errors.vlt:4

Re-exported from velt/text/regex/errors

class RegExpError extends SyntaxError

An invalid pattern or flags (JS throws SyntaxError).

constructor(message: string)No doc comment yet

class

RegExp

#std/text/regex/regexp.vlt:42

Re-exported from velt/text/regex/regexp

class RegExp implements Pattern

A compiled regular expression: new RegExp("(\\d+)-(\\d+)", "g").

readonly source: string

The pattern text as given.

readonly flags: string

The flags as given.

readonly global: bool

g: replace replaces every match.

readonly sticky: bool

y: test/exec only match starting exactly at the start position.

constructor(pattern: string, flags: string = "")

Throws RegExpError for an invalid pattern or flags.

test(s: string, from?: usize): bool

Whether s matches (anywhere at or after position from; exactly at from when sticky). Without from, a g or y regex starts at lastIndex and updates it, like exec.

exec(s: string, from?: usize): RegExpMatch | null

The first match at or after position from (exactly at from when sticky), or null. Without from, a g or y regex starts at lastIndex and sets it past the match, or to 0 when there is none (JS exec); other regexes start at 0.

matchAll(s: string): RegExpMatch[]

Every non-overlapping match, in order (JS s.matchAll(re), whatever the flags).

matches(s: string): string[]

The text of every match (JS s.match(re) with the g flag); empty if none.

replace(s: string, replacement: string): string

JS s.replace(re, replacement): every match with the g flag, else the first. replacement expands $&, $1…$99, $<name>, $`, $' and $$. A sticky regex matches only at lastIndex (with g: from 0, each match where the previous one ended), and lastIndex changes as in JS.

replaceAll(s: string, replacement: string): string

Replaces every match, whatever the flags (JS replaceAll).

replaceWith<E>(s: string, f: (m: RegExpMatch) => string throws E): string throws E

Replaces matches (every one with g, else the first) with f(match); the matches are the ones replace replaces.

[ [REPLACE_CALLING]<E>(s: string, f: (m: RegExpMatch, s: string) => string throws E): string throws E

replaceWith for s.replace(re, (match, ...groups) => …): f gets the subject too.

[ [MATCH](s: string): string[] | null

JS s.match(re): every match's text with g (null if none), else exec's groups.

[ [MATCH_ALL](s: string): RegExpMatch[]

JS s.matchAll(re) (a g regex): every match from lastIndex on, which stays as is.

[ [SEARCH](s: string): i64

JS s.search(re): where the first match from 0 starts, or -1; lastIndex stays.

[ [SPLIT](s: string, limit: number | null | undefined): string[]

JS s.split(re, limit): no limit when null, [] for 0.

split(s: string, limit: usize = 0): string[]

JS s.split(re, limit): captured groups are included in the result; limit 0 = none.

get lastIndex(): number

Where exec(s) and test(s) of a g or y regex start, set past each match (0 after a failed one); s.replace, s.match and s.matchAll read and set it as in JS. Kept by the runtime, so the methods that update it don't need a mutable receiver.

set lastIndex(value: number)No doc comment yet

get groupCount(): usize

Number of capture groups (not counting the whole match).

static escape(s: string): string

s with every regex metacharacter escaped, for building patterns from text.

clone(): RegExp

An independent copy (compiles the pattern again). It cannot throw: the pattern compiled once already. So a deep copy for another task (spawn, a channel) can call it.

[Symbol.dispose]()

Drop hook: releases the compiled program.

class

RegExpMatch

#std/text/regex/regexp_match.vlt:6

Re-exported from velt/text/regex/regexp_match

One match: the matched text, where it is, and its capture groups.

Parameter ofRegExp.replaceWithReturned byRegExp.execUsed byRegExp.[REPLACE_CALLING]

index: number

Position of the match in the subject (code units).

end: number

Position just past the match.

value: string

The matched text (JS m[0]).

captures: (string | null)[]

Groups 1.. (JS m[1], m[2], …); null for a group that did not take part.

names: string[]

Name of each group in captures ("" when unnamed).

constructor(index: number, end: number, value: string, captures: (string | null)[], names: string[])No doc comment yet

[ [INDEX](n: usize): string

m[n]: group n (0 = the whole match), "" if it did not take part or does not exist.

group(n: usize): string | null

Group n (0 = the whole match); null if it did not take part or does not exist.

substitute(s: string, replacement: string): string

replacement for this match of s, with $&, $1…$99, $<name>, $`, $' and $$ expanded as JS's replace does.

named(name: string): string | null

The named group (?<name>…); null if it did not take part or does not exist.

class

StringBuilder

#std/text/string_builder.vlt:20

Re-exported from velt/text/string_builder

A string built by appending: toString() and take() return it without a copy.

Parameter ofvelt/encoding/jsonappendJsonStringappendJsonNumberappendJsonUintappendJsonValuewriteJson

constructor(capacity: usize = 0)

An empty builder with room for capacity bytes before it grows (a hint).

append(s: string): void

Appends s.

appendCodePoint(code: f64): void

Appends the character with code point (or UTF-16 code unit) code, as String.fromCodePoint.

appendInt(n: i64): void

Appends the decimal digits of n (with - when negative).

appendNumber(x: f64): void

Appends x as String(x) writes it (1e+21, NaN, -0 as 0).

get length(): i64

The length of the text so far, in UTF-16 code units (as toString().length).

toString(): string

The text built so far; the builder keeps it. Shared, not copied: the next append copies the text once (it never changes the string returned).

take(): string

The text built so far, handed over without a copy; the builder is empty again.

clear(): void

Empties the builder.

interface

Pattern

#std/text/regex/pattern.vlt:7

Re-exported from velt/text/regex/pattern

A regular expression as a value to test strings with: RegExp implements it.

Used byRegExp

readonly source: string

The pattern text as given.

readonly flags: string

The flags as given.

test(s: string, from?: usize): bool

Whether s matches (as RegExp's test).