Standard library · Numbers and collections

types

Recognising the type of a value from its text: a whole number, a decimal, a boolean or ordinary text?

import types

When data arrives from a CSV file, a form, an environment variable or the command line, everything is text. The types package says what kind of value a piece of text looks like, so you can decide before you convert it. It does not convert anything: once a check passes, conv does the parsing. For whole documents with their own typing rules use encoding.json or encoding.csv.

The checks trim spaces first and turn Persian and Arabic digits into English ones, so ۳۴ is a whole number. A kind is one of five int constants: null (empty text), bool, int, float and string. KindOf tries them in that order, so true is a bool and 12 is an int, never a float.

What people get wrong:

  • Thinking a check means the value fits. IsInt looks only at the characters, so a 20-digit number passes and then conv.ParseInt throws OutOfRange on it.
  • Expecting yes, 1 or on to be a bool. Only true and false count, in any letter case.
  • Expecting blank text to be null. Only text of length zero is TypeKindNull; three spaces are a string.

Check form input before converting it

A form field is text, and conv.ParseInt throws a Syntax error on bad text such as 12abc or abc. The checks here answer the same question without an error to catch: IsInt, IsNumeric and IsBool say whether the conversion makes sense, so you can show the user a clear message first. Persian digits pass the checks, and the parsers in conv read them too; this example still runs str.ToEnglishDigits so the text it keeps is plain ASCII. The Persian decimal separator ٫ is accepted by IsNumeric and is not changed by ToEnglishDigits, so replace it with a dot yourself.

types-guide-form.salam
import str
import conv
import types

func main throws:
    age := "۳۴"
    price := "۱۲٫۵"
    count := "12.0"
    subscribe := " Yes "
    if types.IsInt(age):
        println "age:", try conv.ParseInt(str.ToEnglishDigits(age))
    end
    if types.IsNumeric(price):
        clean := str.Replace(str.ToEnglishDigits(price), "٫", ".")
        println "price:", (try conv.ParseFloat(clean)) * 2.0, "for two"
    end
    if types.IsInt(count) == false:
        println "count must be a whole number, got", count, "which is", types.KindName(types.KindOf(count))
    end
    if types.IsBool(subscribe) == false:
        println "subscribe must be true or false, got [" + subscribe + "]"
    end
end
Outputage: 34 price: 25 for two count must be a whole number, got 12.0 which is float subscribe must be true or false, got [ Yes ]

The checks are strict about the characters: 12.0 is a decimal, not a whole number, and Yes is not a bool. Spaces around a value are ignored by the checks, and conv.ParseInt ignores them too, but trim the text yourself before you store it.

Branch on the kind of a value

KindOf returns one of the five TypeKind constants, which suits a switch. Empty text has its own kind, TypeKindNull, so a missing value can fall back to a default rather than being treated as text. Scientific notation such as 1e3 counts as a decimal.

types-guide-config.salam
import str
import types

func main:
    lines := ["port = 8080", "ratio = 0.75", "debug = false", "name = shop", "retries = -3", "timeout =", "limit = 1e3"]
    each line in lines:
        parts := str.Split(line, "=")
        key := str.Trim(parts.Get(0))
        value := str.Trim(parts.Get(1))
        k := types.KindOf(value)
        switch k:
            types.TypeKindInt:
                println key, "is a whole number:", value
                break
            end
            types.TypeKindFloat:
                println key, "is a decimal:", value
                break
            end
            types.TypeKindBool:
                println key, "is a switch:", str.Lower(value)
                break
            end
            types.TypeKindNull:
                println key, "has no value, the default is used"
                break
            end
            else:
                println key, "is text:", value
            end
        end
    end
end
Outputport is a whole number: 8080 ratio is a decimal: 0.75 debug is a switch: false name is text: shop retries is a whole number: -3 timeout has no value, the default is used limit is a decimal: 1e3

Guess the type of CSV columns

Before you import a CSV file into a database you need a type for each column. Look at every cell and widen the guess as you go: whole numbers and decimals together make a decimal column, any text makes a text column, and empty cells do not change the guess. KindName turns the result into a name for a report or a CREATE TABLE statement.

types-guide-columns.salam
import str
import types

func widen(old: int, cell: str): int:
    k := types.KindOf(str.Trim(cell))
    if k == types.TypeKindNull: ret old end
    if old == types.TypeKindNull or old == k: ret k end
    if (old == types.TypeKindInt and k == types.TypeKindFloat) or (old == types.TypeKindFloat and k == types.TypeKindInt):
        ret types.TypeKindFloat
    end
    ret types.TypeKindStr
end

func main:
    rows := ["id,name,price,stock,active", "1,Tea,4.5,120,true", "2,Coffee,7,,false", "3,Cocoa,5.25,80,TRUE", "4,Mate,6,n/a,true"]
    header := str.Split(rows[0], ",")
    mut kinds := Vector {} as Vector<int>
    defer kinds.Free()
    repeat header.Len():
        kinds.Push(types.TypeKindNull)
    end
    repeat 1 to rows.Len() - 1 in r:
        cells := str.Split(rows[r], ",")
        each c, cell in cells:
            kinds.Set(c, widen(kinds.Get(c), cell))
        end
    end
    each c, name in header:
        println name, "->", types.KindName(kinds.Get(c))
    end
end
Outputid -> int name -> string price -> float stock -> string active -> bool

Compare two vectors

Two vectors cannot be compared with ==; the compiler rejects it (E021). Equal compares them: the same length, and equal elements in the same order. It is generic, so it works for Vector<int>, Vector<str> and the other element types that support ==, and it is handy in small tests.

types-guide-equal.salam
import str
import types

func words(line: str): Vector<str>:
    mut out := Vector {} as Vector<str>
    each w in str.Split(line, " "):
        if w.Len() > 0: out.Push(w) end
    end
    ret out
end

func check(label: str, got: Vector<str>, want: Vector<str>):
    if types.Equal(got, want):
        println "pass", label
    else:
        println "FAIL", label, "got", got.Len(), "words, want", want.Len()
    end
end

func main:
    mut want := Vector {} as Vector<str>
    defer want.Free()
    want.Push("salam")
    want.Push("world")
    a := words("salam world")
    b := words("  salam   world ")
    c := words("salam big world")
    defer a.Free()
    defer b.Free()
    defer c.Free()
    check("single spaces", a, want)
    check("extra spaces", b, want)
    check("three words", c, want)
end
Outputpass single spaces pass extra spaces FAIL three words got 3 words, want 2

What the checks do not catch

A check answers "does this look like a number", not "is this a valid value for my field". A port, an age or a quantity needs a range check of its own after the kind check, and a length check before parsing guards against numbers too large for an int. Convert the digits first, because a Persian digit takes two bytes and would double the length. The function below turns a port setting into a number, with a default for an empty value and -1 for anything invalid.

types-guide-limits.salam
import str
import conv
import types

func port_from(text: str, fallback: int): int:
    t := str.ToEnglishDigits(str.Trim(text))
    if t.Len() == 0: ret fallback end
    if types.IsInt(t) == false or t.Len() > 5: ret -1 end
    n := conv.ParseIntOr(t, 0 - 1)
    if n < 1 or n > 65535: ret -1 end
    ret n as int
end

func main:
    println "blank is:", types.KindName(types.KindOf("   "))
    println "1e is a float:", types.IsFloat("1e")
    println "20 digits are an int:", types.IsInt("99999999999999999999")
    println "yes is a bool:", types.IsBool("yes")
    each raw in ["8080", " ۴۴۳ ", "", "70000", "99999999999999999999", "80a"]:
        println "[" + raw + "] ->", port_from(raw, 3000)
    end
end
Outputblank is: string 1e is a float: true 20 digits are an int: true yes is a bool: false [8080] -> 8080 [ ۴۴۳ ] -> 443 [] -> 3000 [70000] -> -1 [99999999999999999999] -> -1 [80a] -> -1

1e passes IsFloat because the check allows an exponent with no digits after it; but conv.ParseFloat rejects it with a Syntax error, since an exponent needs digits. Parse inside try rather than trusting the check alone.

QuestionUse
Can this text become an int?IsInt
Can it become a number of any kind?IsNumeric
Is it true or false?IsBool
What kind is it, for a switch?KindOf, then KindName to print it
Do two vectors hold the same values?Equal

Constants and variables

TypeKindNull

const TypeKindNull: i32 = 0
The kind of empty text, 0. Text of only spaces is TypeKindStr, not this.
types-KindOf.salam
import types

func main:
    each s in ["42", "3.5", "true", "hello", ""]:
        k := types.KindOf(s)
        println "[" + s + "]", k, types.KindName(k), types.IsInt(s), types.IsFloat(s), types.IsNumeric(s), types.IsBool(s)
    end
    println types.KindOf("7") == types.TypeKindInt, types.TypeKindNull, types.TypeKindBool, types.TypeKindFloat, types.TypeKindStr
end
Output[42] 2 int true false true false [3.5] 3 float false true true false [true] 1 bool false false false true [hello] 4 string false false false false [] 0 null false false false false true 0 1 3 4

TypeKindBool

const TypeKindBool: i32 = 1
The kind of a boolean, true or false; 1.

The example for this item is shown with the ones above: types-KindOf.salam

TypeKindInt

const TypeKindInt: i32 = 2
The kind of a whole number; 2.

The example for this item is shown with the ones above: types-KindOf.salam

TypeKindFloat

const TypeKindFloat: i32 = 3
The kind of a decimal number; 3.

The example for this item is shown with the ones above: types-KindOf.salam

TypeKindStr

const TypeKindStr: i32 = 4
Any other text; 4.

The example for this item is shown with the ones above: types-KindOf.salam

Functions

IsInt

func IsInt(s: str): bool
True when the text, after trimming spaces, is a whole number: an optional + or - and digits. Persian and Arabic digits are accepted. It does not check the size, so a number too large for int still passes.

The example for this item is shown with the ones above: types-KindOf.salam

IsFloat

func IsFloat(s: str): bool
True when the text is a decimal number: digits with one . or Persian ٫ (.5 and 5. both count), or scientific notation such as 2e5. A whole number does not count here. It also accepts a bare trailing exponent such as 1e.

The example for this item is shown with the ones above: types-KindOf.salam

IsNumeric

func IsNumeric(s: str): bool
True when the text is a whole or a decimal number: IsInt or IsFloat. inf and nan are not numbers here.

The example for this item is shown with the ones above: types-KindOf.salam

IsBool

func IsBool(s: str): bool
True when the trimmed text is true or false, in any letter case. yes, 1 and Persian words are not accepted.

The example for this item is shown with the ones above: types-KindOf.salam

KindOf

func KindOf(s: str): int
Returns the kind of the text as one of the constants above, testing null, bool, int and float in that order.

The example for this item is shown with the ones above: types-KindOf.salam

KindName

func KindName(k: int): str
Returns the English name of a kind: null, bool, int, float or string. Any other number also gives string.

The example for this item is shown with the ones above: types-KindOf.salam

Equal

func Equal<T>(a: Vector<T>, b: Vector<T>): bool
True when two vectors have the same length and equal elements in the same order. It is generic and needs an element type that supports ==.
types-Equal.salam
import types

func main:
    mut a := Vector {} as Vector<int>
    mut b := Vector {} as Vector<int>
    defer a.Free()
    defer b.Free()
    a.Push(1)
    a.Push(2)
    b.Push(1)
    b.Push(2)
    println types.Equal(a, b)
    b.Push(3)
    println types.Equal(a, b)
end
Outputtrue false