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:
Atoireturns anint, which is 32 bits, soAtoi("3000000000")throwsOutOfRange. UseParseIntfor ids, sizes and timestamps.- Separators are not digits:
1_000,1 000and1,000all throw, and so does a decimal point inParseInt. ParseBoolis case sensitive:TrueandYESthrow.- A comma is not a decimal separator:
ParseFloat("1,5")throws. The Persian separator٫is fine. - The error says where the problem is.
e.kindisSyntaxorOutOfRange,e.codeis one ofconv.empty,conv.no_digits,conv.invalid_char,conv.not_boolandconv.overflow, ande.offset,e.lineande.columnpoint 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.
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
endPersian 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.
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)
endA 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.
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)
endThe 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.
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)
endThe 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.
| Purpose | Function |
|---|---|
| Saving a value to read back later | FormatFloat |
| Showing a value to a person | FormatFloatShort |
| Prices, percentages, aligned columns | FormatFloatPrec |
| Detecting a NaN after parsing | IsNaNF |
Functions
FormatUint
func FormatUint(x: u64): strimport conv
func main:
println conv.FormatInt(-1200)
println conv.FormatUint(18446744073709551615 as u64)
println conv.FormatBool(false)
println conv.FormatHex(4096 as u64)
endFormatInt
func FormatInt(n: i64): strThe example for this item is shown with the ones above: conv-FormatInt.salam
FormatBool
func FormatBool(b: bool): strtrue 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): strimport 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)
endScanFloat
func ScanFloat(s: str): f64"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): strThe example for this item is shown with the ones above: conv-FormatInt.salam
FormatInt
func FormatInt(n: i64): strThe example for this item is shown with the ones above: conv-FormatInt.salam
FormatBool
func FormatBool(b: bool): strtrue 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>"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.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
endParseBoolOr
func ParseBoolOr(s: str, fallback: bool): boolParseBool, but returns fallback instead of throwing.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)
endParseInt
func ParseInt(s: str): Throws<i64>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): i64ParseInt, 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>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): intAtoi, 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>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): f64ParseFloat, 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"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): strThe example for this item is shown with the ones above: conv-ParseFloat.salam
FormatFloatShort
func FormatFloatShort(x: f64): str%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): strFormatFloat.The example for this item is shown with the ones above: conv-ParseFloat.salam
FormatHex
func FormatHex(x: u64): str0x prefix.The example for this item is shown with the ones above: conv-FormatInt.salam
ParseHex
func ParseHex(s: str): Throws<i64>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): i64ParseHex, but returns fallback instead of throwing.The example for this item is shown with the ones above: conv-ParseIntOr.salam