From ca89931ca910b62adfa1b40a5f00b1b5474b7c68 Mon Sep 17 00:00:00 2001 From: Celestino Amoroso Date: Wed, 15 May 2024 22:06:26 +0200 Subject: [PATCH] Doc: more details on the syntax of the numbers --- doc/Expr.adoc | 93 +++++++++++++++++------ doc/Expr.html | 202 ++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 225 insertions(+), 70 deletions(-) diff --git a/doc/Expr.adoc b/doc/Expr.adoc index f1c085b..68f74f7 100644 --- a/doc/Expr.adoc +++ b/doc/Expr.adoc @@ -22,7 +22,7 @@ Expressions calculator toc::[] -#TODO: Work in progress (last update on 2024/05/10, 06:52 a.m.)# +#TODO: Work in progress (last update on 2024/05/15, 10:00 p.m.)# == Expr _Expr_ is a GO package capable of analysing, interpreting and calculating expressions. @@ -113,37 +113,84 @@ Here are some examples of execution. _Expr_ supports numerical, string, relational, boolean expressions, and mixed-type lists. === Numbers -Numbers can be integers (GO int64) or float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats. +_Expr_ supports three type of numbers: + +. [blue]#Integers# +. [blue]#Floats# +. [blue]#Factions# internally are stored as _pairs of_ Golang _int64_ values. + +In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type take place. + +==== Integers +__Expr__'s integers are a subset of the integer set. Internally they are stored as Golang _int64_ values. + +.Integer literal syntax +==== +*_integer_* = [_sign_] _digit-seq_ + +_sign_ = "**+**" | "**-**" + +_digit-seq_ = _dec-seq_ | _bin-seq_ | _oct-seq_ | _hex-seq_ + +_dec-seq_ = {__dec-digit__} + +_dec-digit_ = "**0**"|"**1**"|...|"**9**" + +_bin-seq_ = "**0b**"{__bin-digit__} + +_bin-digit_ = "**0**"|"**1**" + +_oct-seq_ = "**0o**"{__oct-digit__} + +_oct-digit_ = "**0**"|"**1**"|...|"**7**" + +_hex-seq_ = "**0x**"{__hex-digit__} + +_hex-digit_ = "**0**"|"**1**"|...|"**9**"|"**a**"|...|"**z**"|"**A**"|...|"**Z**" +==== + +Value range: *-9223372036854775808* to *9223372036854775807* .Arithmetic operators [cols="^1,^2,6,4"] |=== | Symbol | Operation | Description | Examples - -| [blue]`+` / [blue]`-` | _change sign_ | Change the sign of values | [blue]`-1` _[-1]_ + -[blue]`-(+2)` _[-2]_ - -| [blue]`+` | _sum_ | Add two values | [blue]`-1 + 2` _[1]_ + -[blue]`4 + 0.5` _[4.5]_ - -| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` _[2]_ + -[blue]`4 - 0.5` _[3.5]_ - -| [blue]`*` | _product_ | Multiply two values | `-1 * 2` _[-2]_ + -[blue]`4 * 0.5` _[2.0]_ - -| [blue]`/` | _Division_ | Divide the left value by the right one | [blue]`-1 / 2` _[0]_ + -[blue]`1.0 / 2` _[0.5]_ - -| [blue]`./` | _Float division_ | Force float division | [blue]`-1 ./ 2` _[-0.5]_ - -| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` _[1]_ - +| [blue]`+` | _sum_ | Add two values | [blue]`-1 + 2` -> 1 +| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`3 - 1` -> 2 +| [blue]`*` | _product_ | Multiply two values | [blue]`-1 * 2` -> -2 +| [blue]`/` | _Division_ | Divide the left value by the right one^(*)^ | [blue]`-10 / 2` -> 5 +| [blue]`%` | _Modulo_ | Remainder of the integer division | [blue]`5 % 2` -> 1 |=== -=== Fractions +^(*)^ See also the _float division_ [blue]`./` below. + + +==== Floats +__Expr__'s floats are a subset of the rational number set. Note that they can't hold the exact value of an unlimited number; floats can only approximate them. Internally floats are stored as Golang's _float64_ values. + + +.Float literal syntax +==== +*_float_* = [_sign_] _dec-seq_ "**.**" [_dec-seq_] [("**e**"|"**E**") [_sign_] _dec-seq_] + +_sign_ = "**+**" | "**-**" + +_dec-seq_ = _see-integer-literal-syntax_ +==== + + +.Arithmetic operators +[cols="^1,^2,6,4"] +|=== +| Symbol | Operation | Description | Examples +| [blue]`+` | _sum_ | Add two values | [blue]`4 + 0.5` -> 4.5 +| [blue]`-` | _subtraction_ | Subtract the right value from the left one | [blue]`4 - 0.5` -> 3.5 +| [blue]`*` | _product_ | Multiply two values | [blue]`4 * 0.5` -> 2.0 +| [blue]`/` | _Division_ | Divide the left value by the right one | [blue]`1.0 / 2` -> 0.5 +| [blue]`./`| _Float division_ | Force float division | [blue]`-1 ./ 2` -> -0.5 +|=== + +==== Fractions _Expr_ also supports fractions. Fraction literals are made with two integers separated by a vertical bar `|`. +.Fraction literal syntax +==== +*_fraction_* = [__sign__] (_num-den-spec_ | _float-spec_) + +_sign_ = "**+**" | "**-**" + +_num-den-spec_ = _digit-seq_ "**|**" _digit-seq_ + +_float-spec_ = _dec-seq_ "**.**" [_dec-seq_] "**(**" _dec-seq_ "**)**" + +_dec-seq_ = _see-integer-literal-syntax_ + +_digit-seq_ = _see-integer-literal-syntax_ + +==== + .Examples // [source,go] // ---- diff --git a/doc/Expr.html b/doc/Expr.html index 78f198c..4801cd5 100644 --- a/doc/Expr.html +++ b/doc/Expr.html @@ -541,11 +541,16 @@ pre.rouge .ss {
  • 2. Data types
  • 3. Dictionaries
    • @@ -579,7 +584,7 @@ pre.rouge .ss {
    -

    TODO: Work in progress (last update on 2024/05/10, 06:52 a.m.)

    +

    TODO: Work in progress (last update on 2024/05/15, 10:00 p.m.)

    @@ -721,7 +726,49 @@ pre.rouge .ss {

    2.1. Numbers

    -

    Numbers can be integers (GO int64) or float (GO float64). In mixed operations involving integers and floats, integers are automatically promoted to floats.

    +

    Expr supports three type of numbers:

    +
    +
    +
      +
    1. +

      Integers

      +
      2. +
    2. +

      Floats

      +
      3. +
    3. +

      Factions internally are stored as pairs of Golang int64 values.

      +
      4. +
    +
    +
    +

    In mixed operations involving integers, fractions and floats, automatic type promotion to the largest type take place.

    +
    +
    +

    2.1.1. Integers

    +
    +

    Expr's integers are a subset of the integer set. Internally they are stored as Golang int64 values.

    +
    +
    +
    Example 1. Integer literal syntax
    +
    +
    +

    integer = [sign] digit-seq
    +sign = "+" | "-"
    +digit-seq = dec-seq | bin-seq | oct-seq | hex-seq
    +dec-seq = {dec-digit}
    +dec-digit = "0"|"1"|…​|"9"
    +bin-seq = "0b"{bin-digit}
    +bin-digit = "0"|"1"
    +oct-seq = "0o"{oct-digit}
    +oct-digit = "0"|"1"|…​|"7"
    +hex-seq = "0x"{hex-digit}
    +hex-digit = "0"|"1"|…​|"9"|"a"|…​|"z"|"A"|…​|"Z"

    +
    +
    +
    +
    +

    Value range: -9223372036854775808 to 9223372036854775807

    @@ -731,70 +778,130 @@ pre.rouge .ss { - - - - - - - - - - - - + + + + - + - + - + - - - - - - - - + + - + + + +
    Table 1. Arithmetic operators
    SymbolOperationDescriptionExamples

    + / -

    change sign

    Change the sign of values

    -1 [-1]
    --(+2) [-2]

    Symbol

    Operation

    Description

    Examples

    +

    sum

    Add two values

    -1 + 2 [1]
    -4 + 0.5 [4.5]

    -1 + 2 → 1

    -

    subtraction

    Subtract the right value from the left one

    3 - 1 [2]
    -4 - 0.5 [3.5]

    3 - 1 → 2

    *

    product

    Multiply two values

    -1 * 2 [-2]
    -4 * 0.5 [2.0]

    -1 * 2 → -2

    /

    Division

    Divide the left value by the right one

    -1 / 2 [0]
    -1.0 / 2 [0.5]

    ./

    Float division

    Force float division

    -1 ./ 2 [-0.5]

    Divide the left value by the right one(*)

    -10 / 2 → 5

    %

    Modulo

    Remainder of the integer division

    5 % 2 [1]

    5 % 2 → 1

    +
    +

    (*) See also the float division ./ below.

    +
    +
    +
    +

    2.1.2. Floats

    +
    +

    Expr's floats are a subset of the rational number set. Note that they can’t hold the exact value of an unlimited number; floats can only approximate them. Internally floats are stored as Golang’s float64 values.

    +
    +
    +
    Example 2. Float literal syntax
    +
    +
    +

    float = [sign] dec-seq "." [dec-seq] [("e"|"E") [sign] dec-seq]
    +sign = "+" | "-"
    +dec-seq = see-integer-literal-syntax

    +
    +
    +
    + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Table 2. Arithmetic operators

    Symbol

    Operation

    Description

    Examples

    +

    sum

    Add two values

    4 + 0.5 → 4.5

    -

    subtraction

    Subtract the right value from the left one

    4 - 0.5 → 3.5

    *

    product

    Multiply two values

    4 * 0.5 → 2.0

    /

    Division

    Divide the left value by the right one

    1.0 / 2 → 0.5

    ./

    Float division

    Force float division

    -1 ./ 2 → -0.5
    -
    -

    2.2. Fractions

    +
    +

    2.1.3. Fractions

    Expr also supports fractions. Fraction literals are made with two integers separated by a vertical bar |.

    +
    +
    Example 3. Fraction literal syntax
    +
    +
    +

    fraction = [sign] (num-den-spec | float-spec)
    +sign = "+" | "-"
    +num-den-spec = digit-seq "|" digit-seq
    +float-spec = dec-seq "." [dec-seq] "(" dec-seq ")"
    +dec-seq = see-integer-literal-syntax
    +digit-seq = see-integer-literal-syntax

    +
    +
    +
    Examples

    >>> 1 | 2
    @@ -828,8 +935,9 @@ pre.rouge .ss { 1.5

    +
    -

    2.3. Strings

    +

    2.2. Strings

    Strings are character sequences enclosed between two double quote ". Example: "I’m a string".

    @@ -837,7 +945,7 @@ pre.rouge .ss {

    Some arithmetic operators can also be used with strings.

    - +@@ -892,12 +1000,12 @@ pre.rouge .ss {
    -

    2.4. Boolean

    +

    2.3. Boolean

    Boolean data type has two values only: true and false. Relational and Boolean expressions produce Boolean values.

    Table 2. String operatorsTable 3. String operators
    - +@@ -958,7 +1066,7 @@ pre.rouge .ss {
    Table 3. Relational operatorsTable 4. Relational operators
    - +@@ -1027,7 +1135,7 @@ pre.rouge .ss {
    -

    2.5. Lists

    +

    2.4. Lists

    Expr supports list of mixed-type values, also specified by normal expressions.

    @@ -1042,7 +1150,7 @@ pre.rouge .ss {
    Table 4. Boolean operatorsTable 5. Boolean operators
    - +@@ -1261,7 +1369,7 @@ The value on the left side of = must be an identifier.

    The table below shows all supported operators by decreasing priorities.

    Table 5. List operatorsTable 6. List operators
    - +@@ -1519,7 +1627,7 @@ The value on the left side of = must be an identifier.
    Table 6. Operators prioritiesTable 7. Operators priorities