Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

↦

Translation status: English reader-locale proof. Term names and code fences follow the en pack; supporting prose may still be English.

Converts a value with explicit runtime parsing or coercion semantics.

Aliases: convert, conversio

Syntax: <expression> ↦ <type> [⊥ <recovery>]

Category#

conversion

  • ∷
  • ⊥

Examples#

radix/corpus/reference/operator-group/conversion/conversio.fab (canonical · operator-group)#

Converts a value with explicit runtime parsing or coercion semantics.

# =============================================================================
# ↦ — Converts a value with explicit runtime parsing or coercion semantics.
# =============================================================================
#
# What this teaches:
#   • Core conversion — the `↦` operator converts between types with explicit parsing (string→int) and coercion (int→string).
#   • Default with `⊥` — the `⊥` operator supplies a default value when conversion fails at runtime (`⇥` only names error types).
#   • Chaining — `↦` composes left-to-right for roundtrip conversions.
#
# Common mistakes:
#   • Confusing `∷` (compile-time type ascription) with `↦` (runtime conversion) and using `vel` instead of `⊥` for conversion recovery.
#
# See also: ∷, ⊥
# =============================================================================

# conversion — type conversion operator (↦)
#
# <expr> ↦ <type>
# <expr> ↦ <type><params>
#
# GRAMMAR:
#   convertExpr :← expr '↦' type
#
# EXPECTED OUTPUT:
#   conversio.expected
#
# BACKEND:
#   Siblings radix.fab and bivalens.fab compile-only until Go semantics align.

main {
    # ↦ converts string → int
    let _ n1 ← "42" ↦ int
    # ⊥ supplies a default on failure
    let _ n2 ← "invalid" ↦ int ⊥ 0
    let _ n3 ← "255" ↦ i32
    let _ f1 ← "3.14159" ↦ float
    let _ f2 ← "invalid" ↦ float ⊥ 0.0
    let _ s1 ← 42 ↦ string
    let _ s2 ← 3.14 ↦ string
    let _ s3 ← true ↦ string

    # chained ↦ left-to-right
    let _ roundtrip ← ("42" ↦ int) ↦ string
    print n1
    print n2
    print n3
    print f1
    print f2
    print s1
    print s2
    print s3
    print roundtrip
}

Expected output:

42
0
255
3.14159
0.0
42
3.14
true
42

radix/corpus/reference/reject/conversion/conversio-lista-to-textus-reject.fab (supporting · reject)#

Rejected route: a list of strings does not convert to a string.

# =============================================================================
# list to string — rejected route
# =============================================================================
#
# What this teaches:
#   • No list converts to text, whatever its element type; the checker refuses
#     `list<T> ↦ string` with one named diagnostic (need 03277dd2).
#   • Say the meaning instead: list<b8|b16|b32> first, then ↦ string; or the
#     format string "§"(xs).
#
# Common mistakes:
#   • reading ↦ as "join the elements" — it is not a join.
# =============================================================================

main {
    let list<string> a ← ["x", "y"]
    let string s ← a ↦ string
    print s
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/decimal-radix-reject.fab (supporting · reject)#

Rejected route: radix hints are integer machinery and do not apply to a decimal.

# =============================================================================
# decimal radix hint — a scaled decimal has no radix digits
# =============================================================================
#
# What this teaches:
#   • `via Hex` / `Bin` / `Oct` parse integer digits in that radix. A `d64` is
#     a scaled decimal: it has a mantissa and a scale, not radix digits, so the
#     parse is refused by name (SEM016 decimal_radix_hint_rejected) instead of
#     falling through to a generic type mismatch.
#   • The same issue covers the reverse direction: a decimal source packed
#     into `ascii<size N> via Hex` is refused for the same reason.
#
# How to make it legal:
#   • an integer with a radix:   "ff" ↦ i32 via Hex
#   • a decimal from plain decimal text: "1.5" ↦ d64
#
# Common mistakes:
#   • assuming a radix hint changes a decimal's scale — it never applies.
#
# See also: ↦, via, d64
# =============================================================================

main {
    let _ v ← "ff" ↦ d64 via Hex
    print v
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/failable-no-handler-reject.fab (supporting · reject)#

Rejected route: a failable narrowing outside main needs a ⊥ default, a catch, or a ⇥ E channel.

# =============================================================================
# failable conversion with no handler — a helper must handle its own failure
# =============================================================================
#
# What this teaches:
#   • A narrowing `↦` can fail at run time, so outside `main` it must say what
#     happens on failure. With no handler the checker refuses it with one named
#     diagnostic (SEM011 failable_conversio_requires_handler).
#   • The `main` (main) body is exempt: an unhandled conversion directly
#     there panics on every backend. Helpers called from main are NOT exempt,
#     which is why the failure below sits in `narrow`.
#
# How to make it legal (pick one):
#   • a `⊥` default:        return x ↦ u8 ⊥ 0
#   • a local catch:        do { return x ↦ u8 } catch err { return 0 }
#   • an error channel:     fn narrow(int x) → u8 ⇥ string { return x ↦ u8 }
#
# Common mistakes:
#   • expecting `main`'s exemption to cover a helper it calls — it does not.
#
# See also: ↦, ⊥, ⇥, do, catch — and the channel form in
# corpus/decimal/conversio_channel.fab.
# =============================================================================

fn narrow(int x) → u8 {
    return x ↦ u8
}

main {
    print "narrow is rejected"
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/float-to-int-reject.fab (supporting · reject)#

Rejected route: a bare float or decimal to integer conversion has no rounding choice.

# =============================================================================
# float to integer — rejected without a rounding choice
# =============================================================================
#
# What this teaches:
#   • A bare `float ↦ int` is a compile error: the checker refuses it with one
#     named diagnostic (SEM016 float_to_integer_requires_rounding, need ea7cfde1).
#   • Say the rounding: `via Floor`, `via Ceil`, `via HalfEven` or `via Trunc`.
#
# Common mistakes:
#   • expecting `↦` to truncate — there is no default rounding.
# =============================================================================

main {
    let float a ← 2.5
    let int n ← a ↦ int
    print n
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/num-to-bytes-reject.fab (supporting · reject)#

Rejected route: a bare number has no byte layout without a width and an endianness.

# =============================================================================
# number to bytes — no layout until a width and an endianness are chosen
# =============================================================================
#
# What this teaches:
#   • Bytes come from a bit pattern, not from a bare number. An unsized
#     number-to-bytes conversion leaves both the width and the endianness
#     unstated, so the checker refuses it (SEM016 numeric_to_octeti_unspecified).
#   • Choose the width and byte order first: a sized numeric scalar writes
#     into a fixed-width carrier with `n ↦ list<b8, size N> via Be` (or `via Le`),
#     where N is the source's exact byte width.
#   • The bit pattern works too, once the source is a sized slot:
#     `n ↦ b64` gives the bits and `bits ↦ list<b8>` gives their octets.
#
# How to make it legal:
#   • let i64 n ← 300
#     let list<b8, size 8> raw ← n ↦ list<b8, size 8> via Be      (big endian)
#   • let list<b8, size 8> raw ← n ↦ list<b8, size 8> via Le      (little endian)
#
# Common mistakes:
#   • assuming a default width — a number has no implicit byte layout.
#   • omitting `via Be` / `via Le` — the endianness is part of the request.
#
# See also: ↦, via, list — and the working forms in
# corpus/conversio/octeti-scalar-write.fab (pack) and
# corpus/conversio/octeti-endian.fab (unpack).
# =============================================================================

main {
    let _ raw ← 1.5 ↦ list<b8>
    print raw
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/textus-to-lista-reject.fab (supporting · reject)#

Rejected route: a string does not convert to a list.

# =============================================================================
# string to list — rejected route
# =============================================================================
#
# What this teaches:
#   • A string is not a list of strings — the element type does not say which
#     encoding, so the checker refuses "abc" ↦ list<string> with one named
#     diagnostic (SEM016 textus_to_lista_unsupported, need 5dccc092).
#   • Say the encoding: ↦ list<b8> gives the UTF-8 octets (list<b16> and
#     list<b32> are the wider rows), or build the character list explicitly.
#
# Common mistakes:
#   • reading ↦ as "split the characters" — the element type is not an
#     encoding choice.
# =============================================================================

main {
    let list<string> cs ← "abc" ↦ list<string>
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/via-bits-retired-reject.fab (supporting · reject)#

Rejected route: via Bits is retired; a bit pattern is an explicit ↦ bN.

# =============================================================================
# via Bits — retired spelling for a bit-pattern route
# =============================================================================
#
# What this teaches:
#   • `via Bits` is retired and refused by name (SEM016
#     conversio_via_bits_retired). A bit pattern is an explicit `↦ bN` step,
#     never a hint on the conversion.
#   • Say the width: `let f16 h ← n ↦ b16 ↦ f16` reads the bits, then
#     reinterprets them as the target type.
#
# Common mistakes:
#   • copying the old `↦ f16 via Bits` spelling — drop the `via` clause and
#     step through an explicit bit width instead.
# =============================================================================

main {
    let u16 n ← 15360
    let f16 h ← n ↦ f16 via Bits
    print h
}

Expected: compilation rejects this example.

radix/corpus/reference/reject/conversion/word-recovery-reject.fab (supporting · reject)#

A conversion into a policy word is total, so a recovery slot is not accepted.

# =============================================================================
# Policy-word recovery — total conversions have no failure to recover from.
# =============================================================================
#
# What this teaches:
#   • A conversion into a policy word cannot fail, so a `⊥` recovery slot is
#     refused rather than accepted and ignored.
#   • Wrap and clamp are values, not failures.
#
main {
    let int n ← 300
    let wrapping<u8> w ← n ↦ wrapping<u8> ⊥ 0
}

Expected: compilation rejects this example.