Standard library · Basics

conv

Converting numbers and booleans to text and back, including Persian digits, with errors for text that is not a number.

import conv

Text arriving from a user, a file or the network is always a string; to do arithmetic with it you have to turn it into a number, and to show the result you turn it back into text. The conv package does both halves of that.

The parsing functions also understand Persian digits (۰۱۲۳۴۵۶۷۸۹) and Arabic ones (٠١٢٣٤٥٦٧٨٩), so a number typed on a Persian keyboard is read without any fuss. Spaces, tabs and line breaks around the text are ignored, and one + or - may come first. Anything else makes the parser throw an Error instead of guessing: an empty string, a stray character such as the abc in 12abc, a sign with no digits, or a number too large for its type. Catch it with try: ... catch e:, or pass it on with try in a function that is itself throws.

When a bad value should simply turn into a default, use the Or form of the parser: ParseIntOr, AtoiOr, ParseFloatOr, ParseBoolOr and ParseHexOr take the fallback as their second argument and never throw.

fmt wraps the formatting half of this package with padding and templates; reach for conv when you need the parsing half, or one of the three float formats below. The string methods to_int and to_float are the old lenient readers: they report nothing and give 0 for text that is not a number, so prefer the functions here for anything a user typed.

Things that catch people out:

  • Atoi returns an int, which is 32 bits, so Atoi("3000000000") throws OutOfRange. Use ParseInt for ids, sizes and timestamps.
  • Separators are not digits: 1_000, 1 000 and 1,000 all throw, and so does a decimal point in ParseInt.
  • ParseBool is case sensitive: True and YES throw.
  • A comma is not a decimal separator: ParseFloat("1,5") throws. The Persian separator ٫ is fine.
  • The error says where the problem is. e.kind is Syntax or OutOfRange, e.code is one of conv.empty, conv.no_digits, conv.invalid_char, conv.not_bool and conv.overflow, and e.offset, e.line and e.column point at the bad character.

Rejecting bad user input

A form has to say no to 12abc or an empty field, and tell the user why. ParseInt does the checking for you: wrap it in try: and show the message from the error.

conv-guide-strict.salam
import conv

func main:
    each typed in ["42", " ۱۴۰۳ ", "+7", "12abc", "", "-0015", "99999999999999999999"]:
        try:
            n := conv.ParseInt(typed)
            println "[" + typed + "]", "->", n
        catch e:
            println "[" + typed + "]", "rejected:", e.message, "at column", e.column
        end
    end
end
Output[42] -> 42 [ ۱۴۰۳ ] -> 1403 [+7] -> 7 [12abc] rejected: invalid character 'a' at column 3 [] rejected: empty input at column 1 [-0015] -> -15 [99999999999999999999] rejected: number does not fit in 64 bits at column 1

Persian digits and the spaces around ۱۴۰۳ are accepted as they are, and leading zeros, as in -0015, are fine too. e.message names the character that broke the number and e.column says where it is, so the user can find it. A number past the 64-bit range is an OutOfRange error rather than a wrapped value.

Adding up numbers in mixed digits

Text pasted from different sources often mixes ASCII, Persian and Arabic digits, and writes the decimal point as . or as the Persian separator ٫. The parsing functions accept all of them, so no clean up is needed before the arithmetic.

conv-guide-sum.salam
import conv
import str

func main throws:
    line := "۱۲ 7 ٣٠ 4.5 ۰٫۵"
    parts := str.Fields(line)
    defer parts.Free()
    mut whole := 0 as i64
    mut exact := 0.0
    each p in parts:
        whole += conv.ParseIntOr(p, 0)
        exact += try conv.ParseFloat(p)
    end
    println "numbers:", parts.Len()
    println "sum of whole parts:", whole
    println "exact sum:", conv.FormatFloatShort(exact)
end
Outputnumbers: 5 sum of whole parts: 49 exact sum: 54

A whole number has no decimal point, so ParseInt rejects 4.5 and ۰٫۵; here ParseIntOr counts them as 0, which is why the two sums differ. Use ParseFloat whenever a value may have a fraction. FormatFloatShort prints the result without a trailing .0 or long tails of digits.

Booleans and hex values from a settings file

Settings files spell their switches in many ways. ParseBool reads true, 1, yes and on as true and false, 0, no and off as false, in lower case, with any spaces around them; anything else throws. Where a misspelled switch should just stay off, ParseBoolOr with a fallback of false does that. ParseHex reads colors, masks and ids written in base sixteen, in either case.

conv-guide-settings.salam
import conv
import str

func main throws:
    raw := HashMap {} as HashMap<str, str>
    defer raw.Free()
    raw.Put("debug", " yes ")
    raw.Put("cache", "0")
    raw.Put("accent", "#1E90FF")
    raw.Put("limit", "۲۵۰")
    raw.Put("compress", "Yes")
    debug := try conv.ParseBool(raw.Get("debug"))
    cache := try conv.ParseBool(raw.Get("cache"))
    compress := conv.ParseBoolOr(raw.Get("compress"), false)
    color := try conv.ParseHex(str.TrimPrefix(raw.Get("accent"), "#"))
    limit := try conv.Atoi(raw.Get("limit"))
    println "debug:", conv.FormatBool(debug), "cache:", conv.FormatBool(cache), "compress:", conv.FormatBool(compress)
    println "red:", color >> 16, "green:", (color >> 8) & 255, "blue:", color & 255
    println "limit doubled:", limit * 2
    println "accent back to hex:", conv.FormatHex(color as u64)
end
Outputdebug: true cache: false compress: false red: 30 green: 144 blue: 255 limit doubled: 500 accent back to hex: 1e90ff

The prefix 0x is optional for ParseHex (the upper case 0X throws), and so does #, so it is cut first with str.TrimPrefix. The shifts and masks then take the three color channels out of the single number.

Choosing a float format

A decimal number can be turned into text in three ways, and each one suits a different job. FormatFloat writes every digit needed to read back exactly the same number, which is what you want in a file another program will read. FormatFloatShort rounds to six significant digits, like %g in C, which is what a person expects to see. FormatFloatPrec rounds to a fixed number of places, for money and reports.

conv-guide-floats.salam
import conv

func main throws:
    price := 0.1 * 3.0
    println "FormatFloat:     ", conv.FormatFloat(price)
    println "FormatFloatShort:", conv.FormatFloatShort(price)
    println "FormatFloatPrec: ", conv.FormatFloatPrec(price, 2)
    back := try conv.ParseFloat(conv.FormatFloat(price))
    println "round trip exact:", back == price
    short := try conv.ParseFloat(conv.FormatFloatShort(price))
    println "short is exact:  ", short == price
    println conv.FormatFloatPrec(1.0 / 3.0, 4), conv.FormatFloatShort(1e21)
end
OutputFormatFloat: 0.30000000000000004 FormatFloatShort: 0.3 FormatFloatPrec: 0.30 round trip exact: true short is exact: false 0.3333 1e+21

The output shows the trade off: the short form of 0.1 * 3.0 reads as 0.3, but parsing that text gives a slightly different number. Save data with FormatFloat and show it with one of the other two.

PurposeFunction
Saving a value to read back laterFormatFloat
Showing a value to a personFormatFloatShort
Prices, percentages, aligned columnsFormatFloatPrec
Detecting a NaN after parsingIsNaNF

Functions

FormatUint

func FormatUint(x: u64): str
Turns an unsigned 64-bit number into text.
conv-FormatInt.salam
import conv

func main:
    println conv.FormatInt(-1200)
    println conv.FormatUint(18446744073709551615 as u64)
    println conv.FormatBool(false)
    println conv.FormatHex(4096 as u64)
end
Output-1200 18446744073709551615 false 1000

FormatInt

func FormatInt(n: i64): str
Turns a 64-bit whole number into text, with a minus sign for negative values.

The example for this item is shown with the ones above: conv-FormatInt.salam

FormatBool

func FormatBool(b: bool): str
Turns true into "true" and false into "false".

The example for this item is shown with the ones above: conv-FormatInt.salam

FormatFloat

func FormatFloat(x: f64): str
Turns a decimal number into text with every digit needed to read exactly the same number back.
conv-ParseFloat.salam
import conv

func main throws:
    x := try conv.ParseFloat("۳٫۷۵")
    println x * 2
    println conv.FormatFloat(0.1 + 0.2)
    println conv.FormatFloatShort(0.1 + 0.2)
    println conv.FormatFloatPrec(2.0 / 3.0, 3)
    nan := try conv.ParseFloat("nan")
    println conv.IsNaNF(nan), conv.IsNaNF(x)
end
Output7.5 0.30000000000000004 0.3 0.667 true false

ScanFloat

func ScanFloat(s: str): f64
Reads the decimal number at the start of the text without reporting any problem: Persian digits and a Persian decimal separator are accepted, "12abc" reads as 12, and text with no number in it gives 0. It is the unchecked reader behind ParseFloat; use ParseFloat when bad input must be an error.

The example for this item is shown with the ones above: conv-ParseFloat.salam

FormatUint

func FormatUint(x: u64): str
Turns an unsigned 64-bit number into text.

The example for this item is shown with the ones above: conv-FormatInt.salam

FormatInt

func FormatInt(n: i64): str
Turns a 64-bit whole number into text, with a minus sign for negative values.

The example for this item is shown with the ones above: conv-FormatInt.salam

FormatBool

func FormatBool(b: bool): str
Turns true into "true" and false into "false".

The example for this item is shown with the ones above: conv-FormatInt.salam

ParseBool

func ParseBool(s: str): Throws<bool>
Turns a string into a boolean. "true", "1", "yes" and "on" are true, "false", "0", "no" and "off" are false, with any spaces around them. Anything else throws a Syntax error (code conv.not_bool, or conv.empty for an empty string). The check is case sensitive, so "True" throws.
conv-ParseInt.salam
import conv

func main throws:
    println try conv.ParseInt("  -۲۷ "), try conv.ParseInt("-27")
    println try conv.Atoi("+15")
    println try conv.ParseHex("0xff"), try conv.ParseHex("1A")
    println try conv.ParseBool("yes"), try conv.ParseBool(" off ")
    try:
        _ := conv.ParseInt("12abc")
    catch e:
        println e.kind_name(), e.code, e.column, e.ToStr()
    end
    try:
        _ := conv.Atoi("3000000000")
    catch e:
        println e.is(ErrorKind.OutOfRange), e.message
    end
end
Output-27 -27 15 255 26 true false syntax error conv.invalid_char 3 conv: invalid character 'a' (line 1, column 3) true number does not fit in 32 bits

ParseBoolOr

func ParseBoolOr(s: str, fallback: bool): bool
Like ParseBool, but returns fallback instead of throwing.
conv-ParseIntOr.salam
import conv

func main:
    println conv.ParseIntOr("12abc", 0), conv.ParseIntOr(" ۴۲ ", 0)
    println conv.AtoiOr("", 8080), conv.AtoiOr("443", 8080)
    println conv.ParseFloatOr("n/a", 0.5), conv.ParseFloatOr("۱٫۲۵", 0.5)
    println conv.ParseBoolOr("True", false), conv.ParseBoolOr("on", false)
    println conv.ParseHexOr("#fff", 0 - 1), conv.ParseHexOr("ff", 0 - 1)
end
Output0 42 8080 443 0.5 1.25 false true -1 255

ParseInt

func ParseInt(s: str): Throws<i64>
Reads a whole number, a 64-bit i64. Spaces around it are ignored and one + or - sign may come first; Persian, Arabic and English digits are all understood, even mixed. Throws a Syntax error for an empty string, a sign with no digits or any other character (a decimal point, a separator, a letter), with the offset, line and column of that character, and OutOfRange (code conv.overflow) when the number does not fit in 64 bits.

The example for this item is shown with the ones above: conv-ParseInt.salam

ParseIntOr

func ParseIntOr(s: str, fallback: i64): i64
Like ParseInt, but returns fallback instead of throwing.

The example for this item is shown with the ones above: conv-ParseIntOr.salam

Atoi

func Atoi(s: str): Throws<int>
The same as ParseInt, but returns an int, which is 32 bits; a number outside that range throws OutOfRange.

The example for this item is shown with the ones above: conv-ParseInt.salam

AtoiOr

func AtoiOr(s: str, fallback: int): int
Like Atoi, but returns fallback instead of throwing.

The example for this item is shown with the ones above: conv-ParseIntOr.salam

ParseFloat

func ParseFloat(s: str): Throws<f64>
Reads a decimal number. Scientific notation such as 2.5e3, a leading or trailing point (.5, 5.), inf, infinity and nan in any case, and Persian digits with the Persian decimal separator (۳٫۷۵) are all accepted, with spaces around. A comma, a second point, an exponent with no digits or any other character throws a Syntax error; a number too large for a 64-bit float throws OutOfRange. A number too small to represent becomes 0.

The example for this item is shown with the ones above: conv-ParseFloat.salam

ParseFloatOr

func ParseFloatOr(s: str, fallback: f64): f64
Like ParseFloat, but returns fallback instead of throwing.

The example for this item is shown with the ones above: conv-ParseIntOr.salam

IsNaNF

func IsNaNF(x: f64): bool
Returns true when the number is "not a number" (NaN), for instance the result of parsing "nan". No comparison with == can detect this case, because NaN is not even equal to itself.

The example for this item is shown with the ones above: conv-ParseFloat.salam

FormatFloat

func FormatFloat(x: f64): str
Turns a decimal number into text with every digit needed to read exactly the same number back.

The example for this item is shown with the ones above: conv-ParseFloat.salam

FormatFloatShort

func FormatFloatShort(x: f64): str
Rounds to six significant digits and drops trailing zeros, like %g in C: 0.1 + 0.2 comes out as 0.3 and 3.14159265 as 3.14159. From a million up, and below 0.0001, it switches to an exponent, so 1234567.0 is 1.23457e+06.

The example for this item is shown with the ones above: conv-ParseFloat.salam

FormatFloatPrec

func FormatFloatPrec(x: f64, prec: int): str
Turns a decimal number into text with the number of decimal places you ask for, rounding halves away from zero. At most 15 places are written, and a value above about 9e14 falls back to FormatFloat.

The example for this item is shown with the ones above: conv-ParseFloat.salam

FormatHex

func FormatHex(x: u64): str
Writes the number in base sixteen in lower case, with no 0x prefix.

The example for this item is shown with the ones above: conv-FormatInt.salam

ParseHex

func ParseHex(s: str): Throws<i64>
Reads a base sixteen number. The 0x prefix is optional and both upper and lower case digits are accepted, but the prefix itself must be a lower case 0x; spaces around are ignored and there is no sign. Up to 16 digits fit; a value above 7fffffffffffffff comes back negative with the same 64 bits, and a longer one throws OutOfRange. Any other character throws a Syntax error.

The example for this item is shown with the ones above: conv-ParseInt.salam

ParseHexOr

func ParseHexOr(s: str, fallback: i64): i64
Like ParseHex, but returns fallback instead of throwing.

The example for this item is shown with the ones above: conv-ParseIntOr.salam