ranger-compiler 3.2.0 → 3.4.0

package/dist/lib/core/README.md

@@ -0,0 +1,251 @@
+# `lib/core` — the Ranger Core API
+
+Portable, dependency-free Ranger classes for the things every language's standard
+library has and Ranger does not: IEEE-754 arithmetic, 32-bit integer algebra,
+string/Unicode handling, dates, formatting, hashing.
+
+One implementation, compiled to every target. No `systemclass`, no operator
+templates, no per-target branches.
+
+**Status: first slice, wired into the JS engine.** `RgNum`, `RgU32`, `RgText`
+and `RgBase` are landed and gated, and `ComponentEngine.rgr` now delegates 16 of
+its own functions here instead of carrying copies (268 lines deleted). The rest
+is planned in [PLAN_JS_STDLIB.md](../../PLAN_JS_STDLIB.md).
+
+| File | What | State |
+| --- | --- | --- |
+| `RgNum.rgr` | IEEE-754 doubles: rounding, `exp`, `log`, `pow`, signed zero, ToInt32/ToUint32, float32 | landed |
+| `RgU32.rgr` | 32-bit unsigned algebra: and/or/xor/not, shifts, rotations, add/sub, clz, popcount, big-endian bytes | landed |
+| `RgText.rgr` | UTF-16 code-unit addressing over all three string models; code points; UTF-8 bytes | landed |
+| `RgBase.rgr` | hex, base64, base64url, and `RgBytesResult` | landed |
+| `RgDate.rgr` | ES5 time algebra, ISO parsing and formatting | planned |
+| `RgIntl.rgr` | collation, number and date formatting over CLDR | planned |
+| `RgCrypto.rgr` | SHA-2, HMAC, PBKDF2, secure random, UUID | planned |
+
+## Why this is not `lib/stdlib.rgr`
+
+`lib/stdlib.rgr` and `lib/stdops.rgr` contain **only operator templates** — no
+classes at all. "stdlib" in this repository already means "language-level
+operator definitions with a per-target template each". This directory is the
+opposite: plain Ranger classes with one body that every target compiles.
+
+The rest of `lib/` is mostly host shims — `lib/Time.rgr` is `es6`-only,
+`lib/Crypto.rgr` has a `java7` template and nothing else. Those work on the
+target they were written for. `lib/core` is for code that has to work on all of
+them.
+
+## Rules for a file in here
+
+1. **No host operators with partial coverage.** If an operator has no `*`
+   fallback and is missing on a target, it does not belong in a signature here.
+2. **No `EvHandle`, `EvalValue`, `TSNode` or any engine type.** These are
+   callable from a native Ranger program with no interpreter present.
+3. **Primitive types only** in signatures: `int`, `double`, `boolean`, `string`,
+   `char`, `[T]`, and classes declared in `lib/core/`.
+4. **No `throw`.** Where JavaScript throws, return a result carrier — the value
+   plus an error kind — so the same function can become a JS exception on one
+   side and an ordinary check on the other.
+5. **No mutable file-level state**, so two callers cannot interfere.
+6. **Every claim gets a vector.** Anything asserted about behaviour goes in
+   `tests/native/core_vectors.rgr` and is compared against Node and across
+   targets. See [Testing](#testing).
+
+### Naming: the `D` suffix, and why
+
+**A static method may not take the name of a global operator.** The resolver
+rewrites `RgNum.floor(x)` into the operator call and then reports
+`Class RgNum does not have method floor`. `EvValueBridge.rgr` documents the same
+trap for `isArray`.
+
+Nine names are affected: `floor`, `ceil`, `sqrt`, `sin`, `cos`, `tan`, `asin`,
+`acos`, `atan2`. Each carries a `D` suffix here — `RgNum.floorD`, `RgNum.ceilD`,
+`RgNum.sqrtD` — which is the convention `DateTime.rgr` already uses for `floorD`,
+`truncD` and `modD`. For `floor` and `ceil` the suffix marks a real distinction:
+**the operators return `int`**, and these return `double`.
+
+Two more names collide for the same reason and are spelled around it: `wrap` (the
+optional-wrapping operator) is `RgU32.wrap32`, and `add` is `RgU32.addU`.
+Instance methods are unaffected — only statics enter the operator namespace.
+
+### Class names the compiler has already taken
+
+Separately from the operator namespace, `compiler/Lang.rgr` **emits helper
+classes into target output**, and a Ranger class of the same name lands beside
+them in the same file. These are reserved:
+
+```
+RgFiles   RgHash   RgList   RgParse   RgPath   RgSort   RgStr   RgUtf8
+```
+
+`RgStr` is why this file's string class is called **`RgText`** — the C# template
+for `strsplit` emits `static class RgStr { … Split … }` (`Lang.rgr:4645`), so any
+C# program using both would have declared the class twice. Nothing caught it,
+because C# has no toolchain on the machine the suite runs on; it turned up on a
+grep. Check a new class name against this list, not only against the operators:
+
+```
+grep -oE "(static )?class (Rg[A-Za-z0-9_]*)" compiler/Lang.rgr | sort -u
+```
+
+Before adding a method, check the name:
+
+```
+node -e 'const fs=require("fs");const n=process.argv[1];
+ const re=/^\s{4,20}([a-zA-Z_][\w]*)\s+(?:_|[a-zA-Z_][\w]*)(?:@\([^)]*\))?\s*:/;
+ for(const f of ["compiler/Lang.rgr","lib/stdops.rgr","lib/stdlib.rgr"])
+  for(const l of fs.readFileSync(f,"utf8").split("\n")){const m=l.match(re);
+   if(m&&m[1]===n)console.log("COLLIDES with an operator in",f);}' floor
+```
+
+## What was measured
+
+Everything below came out of running the same Ranger source on five targets. It
+is written down because each item silently rules out an implementation that looks
+obviously correct.
+
+### `int` is not one type
+
+|  | es6 | python | go | cpp | rust |
+| --- | --- | --- | --- | --- | --- |
+| `2147483647 + 1` | 2147483648 | 2147483648 | 2147483648 | **-2147483648** | 64-bit |
+| `bit_shl 1 31` | **-2147483648** | 2147483648 | 2147483648 | -2147483648 | 64-bit |
+| `bit_shl 1 40` | **256** | 1099511627776 | 1099511627776 | **0** | 64-bit |
+| `bit_ushr (0-1) 4` | 268435455 | 268435455 | **1152921504606846975** | 64-bit | 64-bit |
+
+- **`int` is 32-bit signed on C++.** Plain *arithmetic* overflows there. A u32
+  cannot be held as an `int` in `[0, 2^32)`, because that range does not exist.
+- **`bit_shl` is not portable.** On es6 it is JavaScript's `<<`: the result wraps
+  to 32 bits and the **count is taken mod 32**, so `1 << 40` is 256. On C++ it is
+  undefined past the width and gives 0. On go/python/rust it grows unbounded.
+- **`bit_ushr` is three different operators** — 32-bit on es6 and python, 64-bit
+  on go, cpp, rust and swift. `RgU32` does not use it at all.
+
+`RgU32` therefore carries a u32 as a **signed 32-bit bit pattern**, keeps every
+intermediate under 2^31 by splitting into 16-bit halves, and never writes a
+literal above 2147483647.
+
+### Double literals may be emitted as int literals
+
+`def z:double 0.0` compiles to `z = 0` on the **Python** target — an int. So
+
+```ranger
+def z:double 0.0
+return (z * (0.0 - 1.0))     ; +0 on Python. The sign was gone a line earlier.
+```
+
+The C++ writer has the same habit for bare literals, which is why the JS engine's
+`negativeZero()` bound the value first. That fixes C++ and not Python.
+
+**A division cannot be folded into an int on any target**, because every one of
+them routes double division through a helper (Python's `/` raises
+`ZeroDivisionError`, so `r_div_f64` is already generated). `RgNum.negZero()` is
+therefore `-1 / Infinity`, and the cross-target suite is what found this.
+
+### Strings have three models, and all three are live
+
+| `strlen` | es6 | python | go | rust | cpp |
+| --- | --- | --- | --- | --- | --- |
+| `"é"` | 1 | 1 | 1 | 1 | **2** |
+| `"😀"` | **2** | 1 | 1 | 1 | **4** |
+
+es6 counts UTF-16 code units, python/go/rust count code points, C++ counts UTF-8
+bytes. `charAt` follows suit: on `"é"` it answers 233 on the first four and 195
+on C++. `RgText` encapsulates all three and exposes UTF-16 code units, so
+`RgText.len("😀")` is 2 everywhere.
+
+### `strfromcode` encodes a code point; it cannot emit a byte
+
+On C++, `strfromcode 195` answers the **two-byte** UTF-8 encoding of U+00C3, not
+the single byte 0xC3. So a UTF-8 encoder assembled from per-byte `strfromcode`
+calls — which is the obvious way to write one, and the way the JS engine writes
+it — double-encodes: `"héllo"` came back as `"éllo"`. Two consequences, both in
+`RgText`:
+
+- `encodeUtf8(cp)` is just `strfromcode cp`, because that already IS the UTF-8
+  encoding on a byte-model target.
+- `byteSlice` uses `substring`, which is byte-indexed on a byte-model target,
+  rather than rebuilding the run byte by byte.
+
+Separately, `strfromcode` used **directly as an argument** does not compile on
+Rust (the writer emits a `char` and then calls a `String` method on it), so every
+call here is bound to a `string` first. And on es6 it is `String.fromCharCode`,
+which truncates to 16 bits — `fromCodePoint` builds a surrogate pair there.
+
+### Mutating an array parameter does not reach the caller on Go
+
+```ranger
+sfn appendAll:void (into:[string] more:[string]) {
+    push into (itemAt more 0)      ; the caller never sees this on Go
+}
+```
+
+A Go slice is passed by value and `append` rebinds the local. The symptom is
+silent: every individual vector set was correct while the combined `all` set came
+out **empty**, on Go only. Functions here return new arrays instead.
+
+### "Byte offset" has to mean UTF-8, not "whatever the target indexes by"
+
+The engine's `cuByteOf` means "the offset the target's own string search
+reports" — code units on es6, bytes elsewhere. Lifted unchanged, it answered 3 on
+es6 and 5 everywhere else for the same call, because that contract is
+target-relative by construction. `RgText.utf8ByteOfUnit` and `unitOfUtf8Byte`
+are defined over UTF-8 on every target instead. A bridge to native search offsets
+is a real need, but it belongs to whoever is calling the native search.
+
+### There is no `exp`, `log`, `pow`, `round`, `min` or `atan` operator
+
+`sqrt`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan2` and `fabs` exist as host
+operators. `exp`, `log` and `pow` **do not exist on any target**, and
+`floor`/`ceil` return `int`. So `RgNum` implements them: `exp` by range reduction
+plus a Taylor series, `log` by reduction plus the atanh series, `pow` by squaring
+for integer exponents and the identity otherwise.
+
+The trade is explicit. These land **1 ULP** from each platform's libm — so they
+are *not* bit-identical to `Math.exp` in Node. In exchange they are **identical
+across all five targets**, which delegating to each platform's libm would not
+have been. For a program that has to agree with itself on Go and on Node, that is
+the direction worth being wrong in. The suite asserts the ULP bound rather than
+equality, so a regression in the series cannot hide behind "it was never exact".
+
+## Testing
+
+```bash
+npm run test:core          # oracle + every target
+```
+
+Five targets are **built and run**: es6, python, go, cpp, rust. The other five —
+csharp, kotlin, dart, swift6, java7 — have no toolchain on the machine this was
+developed on, so they are only checked as far as *the Ranger compiler writing
+them without error*, which is still worth doing: it is how the `RgStr` clash
+above would have been caught. Scala does not write, because `shell_arg` and
+`shell_arg_cnt` have no Scala template — a gap in the harness's `main`, not in
+`lib/core`, and Scala is outside the large-program CI path anyway.
+
+Three legs, in `tests/core-targets.test.ts` over
+`tests/native/core_vectors.rgr`:
+
+1. **Node as oracle.** Every expectation is computed by the JavaScript built-in
+   the function mirrors, never hand-written. `CONFORMANCE.md` records
+   hand-written expectations encoding a misunderstanding three separate times.
+2. **Byte-for-byte across targets.** Compiled to es6, python, go, cpp and rust;
+   built and run where the toolchain is on `PATH`; output compared character for
+   character against the es6 run.
+3. **The `D` bound** on `exp`/`log`, asserted as a bound.
+
+Doubles are never printed directly — each target's own number formatter
+disagrees about trailing `.0`, exponent spelling and digit count. `showD`
+decomposes a double into sign, a 52-bit mantissa in two halves, and a binary
+exponent, and the test does the same decomposition in JavaScript.
+
+Current reading: **173 vectors, identical on es6 / python / go / cpp / rust;
+170 of them exact against Node**, the other three being the `exp`/`log` series.
+
+The second gate is the JS engine itself. `ComponentEngine.rgr` delegates to this
+directory, so `npm run test:tsengine` — 45,221 lines of interpreter compiled to
+six targets and checked against Node's answers for seven workloads — is also a
+test of `lib/core`. Verified by hand here (vitest is not installed on this
+machine): all seven answers correct on es6 and on Go, and the engine still writes
+for kotlin, csharp, dart and swift6.
+
+`strmodel` is the one set that is reported rather than compared — `RgText.kind()`
+is 0 on es6, 2 on python/go/rust and 1 on cpp, and that is the point.

package/dist/lib/core/RgBase.rgr

@@ -0,0 +1,313 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; RgBase — hex, base64 and base64url
+; =============================================================================
+; There is no portable base64 in Ranger. There is no portable hex either. Both
+; are wanted by anything that moves bytes: data URIs, JWTs, HTTP basic auth,
+; digests printed for a human, binary embedded in JSON. `RgCrypto` needs all
+; three, and `btoa`/`atob` on the JS side map straight onto them.
+;
+; Bytes are `[int]` with each element in [0, 255]. Not `string`, because a Ranger
+; string is bytes on C++, code points on python/go/rust and UTF-16 units on es6
+; (see RgText) — "base64 of a string" would encode different input per target,
+; which is the exact bug this library exists to prevent. Text goes through
+; `RgText.toUtf8Bytes` first, which is the single place the string model is
+; handled.
+;
+; Decoding returns `RgBytesResult` rather than throwing: the core layer has no
+; `throw` (see lib/core/README.md), so a caller checks `ok` and the JS binding
+; turns `errorKind` into the exception the spec names.
+;
+; RFC 4648 throughout, including the parts people skip: padding is REQUIRED and
+; validated for base64, forbidden for base64url, and a non-zero tail bit in the
+; final quantum is rejected rather than silently discarded.
+; =============================================================================
+
+Import "RgText.rgr"
+
+; A decode either produced bytes or says why it did not.
+class RgBytesResult {
+    def ok:boolean false
+    def value:[int]
+    ; "" when ok. Otherwise the DOM/JS error name the binding should throw:
+    ; InvalidCharacterError for a bad character or a bad length.
+    def errorKind:string ""
+    def errorMessage:string ""
+
+    static sfn good:RgBytesResult (bytes:[int]) {
+        def r (new RgBytesResult)
+        r.ok = true
+        r.value = bytes
+        return r
+    }
+
+    static sfn bad:RgBytesResult (kind:string message:string) {
+        def r (new RgBytesResult)
+        r.ok = false
+        r.errorKind = kind
+        r.errorMessage = message
+        return r
+    }
+}
+
+class RgBase {
+
+    ; ---- alphabets ---------------------------------------------------------
+    ; As strings rather than arrays so the tables cost one literal each. Indexed
+    ; with RgText.unitAt, which is ASCII-safe on every model.
+
+    static sfn hexDigits:string () {
+        return "0123456789abcdef"
+    }
+
+    static sfn b64Alphabet:string () {
+        return "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    }
+
+    static sfn b64UrlAlphabet:string () {
+        return "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+    }
+
+    ; The value of one base64 character, or -1. A table scan rather than
+    ; arithmetic on ranges: the two alphabets differ only in the last two
+    ; entries, so one function serves both and there is no second place for the
+    ; `+/` versus `-_` distinction to be got wrong.
+    static sfn b64ValueOf:int (alphabet:string ch:int) {
+        def i:int 0
+        while (i < 64) {
+            if ((RgText.unitAt(alphabet i)) == ch) {
+                return i
+            }
+            i = (i + 1)
+        }
+        return (0 - 1)
+    }
+
+    static sfn hexValueOf:int (ch:int) {
+        if ((ch >= 48) && (ch <= 57)) {
+            return (ch - 48)
+        }
+        if ((ch >= 97) && (ch <= 102)) {
+            return ((ch - 97) + 10)
+        }
+        if ((ch >= 65) && (ch <= 70)) {
+            return ((ch - 65) + 10)
+        }
+        return (0 - 1)
+    }
+
+    ; ---- hex ----------------------------------------------------------------
+
+    ; Lowercase, two characters per byte, no separator. This is what every
+    ; digest in the wild is printed as.
+    static sfn hexEncode:string (bytes:[int]) {
+        def digits:string (RgBase.hexDigits())
+        def out:string ""
+        def i:int 0
+        def n:int (array_length bytes)
+        while (i < n) {
+            def b:int (bit_and (itemAt bytes i) 255)
+            def hi:int (bit_shr b 4)
+            def lo:int (bit_and b 15)
+            out = (out + (RgText.substr(digits hi (hi + 1))))
+            out = (out + (RgText.substr(digits lo (lo + 1))))
+            i = (i + 1)
+        }
+        return out
+    }
+
+    ; Accepts either case. An odd length is an error rather than a silent
+    ; zero-pad, because "0f" and "f0" are different bytes and guessing which one
+    ; a caller meant is not this function's business.
+    static sfn hexDecode:RgBytesResult (s:string) {
+        def n:int (RgText.len(s))
+        if ((bit_and n 1) != 0) {
+            return (RgBytesResult.bad("InvalidCharacterError" "hex string has an odd length"))
+        }
+        def out:[int]
+        def i:int 0
+        while (i < n) {
+            def hi:int (RgBase.hexValueOf((RgText.unitAt(s i))))
+            def lo:int (RgBase.hexValueOf((RgText.unitAt(s (i + 1)))))
+            if ((hi < 0) || (lo < 0)) {
+                return (RgBytesResult.bad("InvalidCharacterError" "hex string has a non-hex character"))
+            }
+            push out ((hi * 16) + lo)
+            i = (i + 2)
+        }
+        return (RgBytesResult.good(out))
+    }
+
+    ; ---- base64 -------------------------------------------------------------
+
+    ; Shared by both alphabets. `pad` is what separates base64 (RFC 4648 §4,
+    ; padded) from base64url (§5, unpadded by convention and by every consumer
+    ; that matters — JWT forbids the padding outright).
+    static sfn encodeWith:string (alphabet:string bytes:[int] pad:boolean) {
+        def out:string ""
+        def n:int (array_length bytes)
+        def i:int 0
+        while ((i + 2) < n) {
+            def b0:int (bit_and (itemAt bytes i) 255)
+            def b1:int (bit_and (itemAt bytes (i + 1)) 255)
+            def b2:int (bit_and (itemAt bytes (i + 2)) 255)
+            def t:int (((b0 * 65536) + (b1 * 256)) + b2)
+            def c0:int (bit_and (bit_shr t 18) 63)
+            def c1:int (bit_and (bit_shr t 12) 63)
+            def c2:int (bit_and (bit_shr t 6) 63)
+            def c3:int (bit_and t 63)
+            out = (out + (RgText.substr(alphabet c0 (c0 + 1))))
+            out = (out + (RgText.substr(alphabet c1 (c1 + 1))))
+            out = (out + (RgText.substr(alphabet c2 (c2 + 1))))
+            out = (out + (RgText.substr(alphabet c3 (c3 + 1))))
+            i = (i + 3)
+        }
+        def left:int (n - i)
+        if (left == 1) {
+            def a0:int (bit_and (itemAt bytes i) 255)
+            def d0:int (bit_shr a0 2)
+            def d1:int (bit_and (a0 * 16) 63)
+            out = (out + (RgText.substr(alphabet d0 (d0 + 1))))
+            out = (out + (RgText.substr(alphabet d1 (d1 + 1))))
+            if pad {
+                out = (out + "==")
+            }
+        }
+        if (left == 2) {
+            def e0:int (bit_and (itemAt bytes i) 255)
+            def e1:int (bit_and (itemAt bytes (i + 1)) 255)
+            def f0:int (bit_shr e0 2)
+            def f1:int (bit_and ((e0 * 16) + (bit_shr e1 4)) 63)
+            def f2:int (bit_and (e1 * 4) 63)
+            out = (out + (RgText.substr(alphabet f0 (f0 + 1))))
+            out = (out + (RgText.substr(alphabet f1 (f1 + 1))))
+            out = (out + (RgText.substr(alphabet f2 (f2 + 1))))
+            if pad {
+                out = (out + "=")
+            }
+        }
+        return out
+    }
+
+    ; `strict` demands correct padding and rejects a final quantum whose unused
+    ; low bits are non-zero. A decoder that ignores those accepts several
+    ; different strings for the same bytes, which is how base64 malleability
+    ; bugs get in.
+    static sfn decodeWith:RgBytesResult (alphabet:string s:string requirePad:boolean) {
+        def units:[int] (RgText.toCodeUnits(s))
+        def clean:[int]
+        def padCount:int 0
+        def i:int 0
+        def n:int (array_length units)
+        while (i < n) {
+            def ch:int (itemAt units i)
+            if (ch == 61) {
+                padCount = (padCount + 1)
+            } {
+                if (padCount > 0) {
+                    return (RgBytesResult.bad("InvalidCharacterError" "base64 has a character after the padding"))
+                }
+                def v:int (RgBase.b64ValueOf(alphabet ch))
+                if (v < 0) {
+                    return (RgBytesResult.bad("InvalidCharacterError" "base64 has a character outside the alphabet"))
+                }
+                push clean v
+            }
+            i = (i + 1)
+        }
+        if (padCount > 2) {
+            return (RgBytesResult.bad("InvalidCharacterError" "base64 has more than two padding characters"))
+        }
+        def m:int (array_length clean)
+        def rem:int (m - ((idiv m 4) * 4))
+        if (rem == 1) {
+            return (RgBytesResult.bad("InvalidCharacterError" "base64 has a one-character final quantum"))
+        }
+        if requirePad {
+            if (rem != 0) {
+                def want:int 0
+                if (rem == 2) {
+                    want = 2
+                }
+                if (rem == 3) {
+                    want = 1
+                }
+                if (padCount != want) {
+                    return (RgBytesResult.bad("InvalidCharacterError" "base64 is not padded to a multiple of four"))
+                }
+            }
+        }
+        def out:[int]
+        def k:int 0
+        while ((k + 3) < m) {
+            def q0:int (itemAt clean k)
+            def q1:int (itemAt clean (k + 1))
+            def q2:int (itemAt clean (k + 2))
+            def q3:int (itemAt clean (k + 3))
+            def t:int ((((q0 * 262144) + (q1 * 4096)) + (q2 * 64)) + q3)
+            push out (bit_and (bit_shr t 16) 255)
+            push out (bit_and (bit_shr t 8) 255)
+            push out (bit_and t 255)
+            k = (k + 4)
+        }
+        def tail:int (m - k)
+        if (tail == 2) {
+            def r0:int (itemAt clean k)
+            def r1:int (itemAt clean (k + 1))
+            ; The low 4 bits of the second character are not part of any byte.
+            if ((bit_and r1 15) != 0) {
+                return (RgBytesResult.bad("InvalidCharacterError" "base64 final quantum has non-zero unused bits"))
+            }
+            push out (bit_and ((r0 * 4) + (bit_shr r1 4)) 255)
+        }
+        if (tail == 3) {
+            def u0:int (itemAt clean k)
+            def u1:int (itemAt clean (k + 1))
+            def u2:int (itemAt clean (k + 2))
+            ; The low 2 bits of the third character are likewise unused.
+            if ((bit_and u2 3) != 0) {
+                return (RgBytesResult.bad("InvalidCharacterError" "base64 final quantum has non-zero unused bits"))
+            }
+            push out (bit_and ((u0 * 4) + (bit_shr u1 4)) 255)
+            push out (bit_and ((u1 * 16) + (bit_shr u2 2)) 255)
+        }
+        return (RgBytesResult.good(out))
+    }
+
+    static sfn base64Encode:string (bytes:[int]) {
+        return (RgBase.encodeWith((RgBase.b64Alphabet()) bytes true))
+    }
+
+    static sfn base64Decode:RgBytesResult (s:string) {
+        return (RgBase.decodeWith((RgBase.b64Alphabet()) s true))
+    }
+
+    static sfn base64UrlEncode:string (bytes:[int]) {
+        return (RgBase.encodeWith((RgBase.b64UrlAlphabet()) bytes false))
+    }
+
+    static sfn base64UrlDecode:RgBytesResult (s:string) {
+        return (RgBase.decodeWith((RgBase.b64UrlAlphabet()) s false))
+    }
+
+    ; ---- text convenience ---------------------------------------------------
+    ; UTF-8 in, UTF-8 out. These are what a caller actually reaches for, and
+    ; routing them through RgText keeps the string model in one place.
+
+    static sfn base64EncodeText:string (text:string) {
+        return (RgBase.base64Encode((RgText.toUtf8Bytes(text))))
+    }
+
+    static sfn base64DecodeText:string (s:string) {
+        def r:RgBytesResult (RgBase.base64Decode(s))
+        if (false == r.ok) {
+            return ""
+        }
+        return (RgText.fromUtf8Bytes(r.value))
+    }
+
+    static sfn hexEncodeText:string (text:string) {
+        return (RgBase.hexEncode((RgText.toUtf8Bytes(text))))
+    }
+}