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.

Conversions

↦ converts a value to another type at runtime. It parses, coerces, and can fail — which is exactly what distinguishes it from casting.

Converting#

reader locale
faber convert --to en — English reader surface
main {
    let int n ← "42" ↦ int
    let string s ← 42 ↦ string
    let f64 f ← "3.14159" ↦ f64
    print n, s, f
}
faber convert --to la — canonical Faber
incipit {
    sit numerus n ← "42" ↦ numerus
    sit textus s ← 42 ↦ textus
    sit f64 f ← "3.14159" ↦ f64
    nota n, s, f
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด จํานวน n ← "42" ↦ จํานวน
    กำหนด ข้อความ s ← 42 ↦ ข้อความ
    กำหนด f64 f ← "3.14159" ↦ f64
    บันทึก n, s, f
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 整数 n ← "42" ↦ 整数
    设 文本 s ← 42 ↦ 文本
    设 f64 f ← "3.14159" ↦ f64
    显示 n, s, f
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 整數 n ← "42" ↦ 整數
    設為 文字 s ← 42 ↦ 文字
    設為 f64 f ← "3.14159" ↦ f64
    註記 n, s, f
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt số n ← "42" ↦ số
    đặt văn_bản s ← 42 ↦ văn_bản
    đặt f64 f ← "3.14159" ↦ f64
    ghi_chú n, s, f
}
faber convert --to ar — Arabic
بداية {
    ليكن عدد n ← "42" ↦ عدد
    ليكن نص s ← 42 ↦ نص
    ليكن f64 f ← "3.14159" ↦ f64
    اعرض n, s, f
}
faber convert --to hi — Hindi
आरंभ {
    बैठा संख्या n ← "42" ↦ संख्या
    बैठा पाठ s ← 42 ↦ पाठ
    बैठा f64 f ← "3.14159" ↦ f64
    दिखाओ n, s, f
}

Float to integer#

An integer becomes a float with a plain ↦. A float becomes an integer only with a rounding word, because the compiler will not pick one for you. A bare x ↦ int on a float is SEM016 float_to_integer_requires_rounding.

The words follow via: floor rounds toward negative infinity, ceil toward positive infinity, trunc toward zero, and half_even to the nearest integer, with ties going to the even neighbour.

main {
    let f64 x ← 2.5
    let f64 y ← 3.5
    let f64 z ← -2.5
    print x ↦ int via floor
    print x ↦ int via ceil
    print x ↦ int via half_even
    print y ↦ int via half_even
    print z ↦ int via trunc
    print z ↦ int via floor
}
$ faber run
2
3
2
4
-2
-3

⌊2.5⌉ is the same nearest-even rounding written as a bracket: it is 2, and ⌊3.5⌉ is 4. Leaving the word off is an error:

main {
    let f64 x ← 2.5
    let int n ← x ↦ int
    print n
}

Recovery on failure#

⊥ after a conversion supplies the value to use when it fails. Without it, a failed conversion travels down the error channel.

reader locale
faber convert --to en — English reader surface
main {
    let int good ← "42" ↦ int ⊥ 0
    let int bad ← "not a number" ↦ int ⊥ 0
    print good, bad
}
faber convert --to la — canonical Faber
incipit {
    sit numerus good ← "42" ↦ numerus ⊥ 0
    sit numerus bad ← "not a number" ↦ numerus ⊥ 0
    nota good, bad
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด จํานวน good ← "42" ↦ จํานวน ⊥ 0
    กำหนด จํานวน bad ← "not a number" ↦ จํานวน ⊥ 0
    บันทึก good, bad
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 整数 good ← "42" ↦ 整数 ⊥ 0
    设 整数 bad ← "not a number" ↦ 整数 ⊥ 0
    显示 good, bad
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 整數 good ← "42" ↦ 整數 ⊥ 0
    設為 整數 bad ← "not a number" ↦ 整數 ⊥ 0
    註記 good, bad
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt số good ← "42" ↦ số ⊥ 0
    đặt số bad ← "not a number" ↦ số ⊥ 0
    ghi_chú good, bad
}
faber convert --to ar — Arabic
بداية {
    ليكن عدد good ← "42" ↦ عدد ⊥ 0
    ليكن عدد bad ← "not a number" ↦ عدد ⊥ 0
    اعرض good, bad
}
faber convert --to hi — Hindi
आरंभ {
    बैठा संख्या good ← "42" ↦ संख्या ⊥ 0
    बैठा संख्या bad ← "not a number" ↦ संख्या ⊥ 0
    दिखाओ good, bad
}

⊥ is not the error channel. ⇥ only ever names the error type a function may fail with; ⊥ only ever holds a value. Read ⊥ 0 as on failure, 0.

Text to boolean#

Text becomes a boolean only when it is the code locale's word for one. In an English file "true" and "false" convert; any other text fails, so "yes" takes the ⊥ value here. Every target parses the words the same way.

main {
    print "true" ↦ bool ⊥ false
    print "false" ↦ bool ⊥ true
    print "yes" ↦ bool ⊥ false
}
$ faber run
true
false
false

Chaining#

Conversions apply left to right.

reader locale
faber convert --to en — English reader surface
main {
    let string roundtrip ← ("42" ↦ int) ↦ string
    print roundtrip
}
faber convert --to la — canonical Faber
incipit {
    sit textus roundtrip ← ("42" ↦ numerus) ↦ textus
    nota roundtrip
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด ข้อความ roundtrip ← ("42" ↦ จํานวน) ↦ ข้อความ
    บันทึก roundtrip
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 文本 roundtrip ← ("42" ↦ 整数) ↦ 文本
    显示 roundtrip
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 文字 roundtrip ← ("42" ↦ 整數) ↦ 文字
    註記 roundtrip
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt văn_bản roundtrip ← ("42" ↦ số) ↦ văn_bản
    ghi_chú roundtrip
}
faber convert --to ar — Arabic
بداية {
    ليكن نص roundtrip ← ("42" ↦ عدد) ↦ نص
    اعرض roundtrip
}
faber convert --to hi — Hindi
आरंभ {
    बैठा पाठ roundtrip ← ("42" ↦ संख्या) ↦ पाठ
    दिखाओ roundtrip
}

Converting to a width#

The target can name a precise width, not just a family.

reader locale
faber convert --to en — English reader surface
main {
    let i32 narrow ← "255" ↦ i32
    let f32 single ← "1.5" ↦ f32
    print narrow, single
}
faber convert --to la — canonical Faber
incipit {
    sit i32 narrow ← "255" ↦ i32
    sit f32 single ← "1.5" ↦ f32
    nota narrow, single
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด i32 narrow ← "255" ↦ i32
    กำหนด f32 single ← "1.5" ↦ f32
    บันทึก narrow, single
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 i32 narrow ← "255" ↦ i32
    设 f32 single ← "1.5" ↦ f32
    显示 narrow, single
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 i32 narrow ← "255" ↦ i32
    設為 f32 single ← "1.5" ↦ f32
    註記 narrow, single
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt i32 narrow ← "255" ↦ i32
    đặt f32 single ← "1.5" ↦ f32
    ghi_chú narrow, single
}
faber convert --to ar — Arabic
بداية {
    ليكن i32 narrow ← "255" ↦ i32
    ليكن f32 single ← "1.5" ↦ f32
    اعرض narrow, single
}
faber convert --to hi — Hindi
आरंभ {
    बैठा i32 narrow ← "255" ↦ i32
    बैठा f32 single ← "1.5" ↦ f32
    दिखाओ narrow, single
}

Bits and half floats#

A number converts to raw bits of the same width and back. Converting into f16 or bf16 rounds to that format at the store.

reader locale
faber convert --to en — English reader surface
main {
    let u32 n ← 255
    let b32 bits ← n ↦ b32
    let f16 half ← 0.1 ↦ f16
    print bits, bits ↦ u32, half ↦ f64
}
faber convert --to la — canonical Faber
incipit {
    sit u32 n ← 255
    sit b32 bits ← n ↦ b32
    sit f16 half ← 0.1 ↦ f16
    nota bits, bits ↦ u32, half ↦ f64
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด u32 n ← 255
    กำหนด b32 bits ← n ↦ b32
    กำหนด f16 half ← 0.1 ↦ f16
    บันทึก bits, bits ↦ u32, half ↦ f64
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 u32 n ← 255
    设 b32 bits ← n ↦ b32
    设 f16 half ← 0.1 ↦ f16
    显示 bits, bits ↦ u32, half ↦ f64
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 u32 n ← 255
    設為 b32 bits ← n ↦ b32
    設為 f16 half ← 0.1 ↦ f16
    註記 bits, bits ↦ u32, half ↦ f64
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt u32 n ← 255
    đặt b32 bits ← n ↦ b32
    đặt f16 half ← 0.1 ↦ f16
    ghi_chú bits, bits ↦ u32, half ↦ f64
}
faber convert --to ar — Arabic
بداية {
    ليكن u32 n ← 255
    ليكن b32 bits ← n ↦ b32
    ليكن f16 half ← 0.1 ↦ f16
    اعرض bits, bits ↦ u32, half ↦ f64
}
faber convert --to hi — Hindi
आरंभ {
    बैठा u32 n ← 255
    बैठा b32 bits ← n ↦ b32
    बैठा f16 half ← 0.1 ↦ f16
    दिखाओ bits, bits ↦ u32, half ↦ f64
}

This prints 0x000000ff 255 0.0999755859375. A width that does not match, such as u16 ↦ b32, is SEM016 bits_conversion_width_mismatch.

Conversion is not casting#

Conversion ↦Casting
WhenRuntimeCompile time
Can failYes — that is why ⊥ and the error channel existNo
Means"Parse or coerce this into that""I already know this is that"

A conversion does work: it reads "42" and produces a number, and it has to cope with "banana". A cast asserts something to the compiler and produces no runtime behaviour. If a value might not be what you claim, you want ↦ and a recovery, not a cast.

Related: Types and widths · Errors and catching