Explicit Type Conversions

Flame provides a rich set of universal type conversion methods on all values. This avoids confusing implicit type coercion and ensures predictable runtime behavior.

---

String Parsing Methods

Flame offers both panicking and safe non-panicking (try*) conversion methods on strings:

Integer Parsing: .toInt() & .tryInt()

• .toInt(radix: Int = 10): Parses a string into an integer. Supports any radix base between 2 and 36. Throws a runtime error if parsing fails.
• .tryInt(radix: Int = 10): Non-panicking version. Returns Nil if the string cannot be parsed.

let dec = "42".toInt()          // 42
let hex = "1A".toInt(16)        // 26
let bin = "1010".toInt(2)       // 10

// Safe parsing
let safe_val = "100".tryInt()   // 100
let failed   = "abc".tryInt()   // Nil

Float Parsing: .toFloat() & .tryFloat()

• .toFloat() / .toDouble(): Converts a string decimal into a 64-bit Float.
• .tryFloat() / .tryDouble(): Non-panicking version. Returns Nil upon invalid format.

let pi = "3.14159".toFloat()
let invalid_pi = "not_a_number".tryFloat() // Nil

Boolean Parsing: .toBool() & .tryBool()

Converts case-insensitive strings like "true", "false", "1", or "0" into a boolean:

let is_prod = "true".toBool() // true
let flag = "0".toBool()       // false

UTF-8 Bytes: .toByte()

• .toByte(): Converts a string or integer into a dynamic array of UTF-8 byte values (or a single byte) (Value::Byte).
• .toByte(): Converts a valid integer (0-255) into a single 8-bit unsigned Byte value (Value::Byte).

let bytes = "Flame".toByte() // <Byte>
let single_byte = 65.toByte()  // <Byte> representing 'A'

---

Byte Manipulations

For Byte arrays (such as those returned by .toByte()), Flame provides built-in utilities:

• .toHex(): Converts a byte array into a continuous hexadecimal string.
• .toBase64(): Encodes the byte array using standard Base64 encoding.
• .toUtf8(): Attempts to parse the bytes as a UTF-8 encoded string. Throws an error on invalid sequences.
• .tryUtf8(): Non-panicking version of .toUtf8(). Returns Nil on invalid sequences.
• .concat(other): Appends another byte array, returning a new Bytes array.

let b1 = "hello".toByte()
let b2 = " world".toByte()

let combined = b1.concat(b2)
println(combined.toHex())    // "68656C6C6F20776F726C64"
println(combined.toBase64()) // "aGVsbG8gd29ybGQ="
println(combined.toUtf8())   // "hello world"

---

Universal Formatters & Character Conversion

.toString(precision: Int)

Every value (primitives, structs, formulas, vectors) can be converted to a readable string:

let list_str = [1, 2, 3].toString()  // "[1, 2, 3]"

// Float formatting with precision:
let pi_str = 3.14159265.toString(2)  // "3.14"

.type()

Returns a string representing the underlying type name of the variable.

let number = 100
println(number.type()) // "Int"

let text = "Flame"
println(text.type())   // "String"

---

Quick Reference Table

Method	Source Type	Return Type	Throws on Error?
.toInt(radix?)	String	Int	Yes
.tryInt(radix?)	String	Int | Nil	No (Nil)
.toFloat()	String	Float	Yes
.tryFloat()	String	Float | Nil	No (Nil)
.toBool()	String	Bool	Yes
.tryBool()	String	Bool | Nil	No (Nil)
.toByte()	String	Byte	No
.toByte()	Int	Byte	Yes
.toHex()	Byte	String	No
.toBase64()	Byte	String	No
.toUtf8()	Byte	String	Yes
.tryUtf8()	Byte	String | Nil	No (Nil)
.concat()	Byte	Byte	No
.type()	Any	String	No
.toString(precision?)	Any	String	No