arithmetic expressions

docs/arithmetic_expression.rst

@@ -1,4 +1,39 @@
 .. _arithmetic_expressions:
 
-Arithmetic Expression
-=====================
+Arithmetic Expressions
+======================
+
+An arithmetic expression is an expression that results in a :code:`TealType.uint64` value.
+In PyTeal, arithmetic expressions include integer arithmetics operators and boolean operators.
+We overloaded all integer arithmetics operator in Python.
+
+==================== =========== ================================================= =========================
+Operator             Overloaded  Semantics                                         Example
+==================== =========== ================================================= =========================
+:code:`Lt(a, b)`     :code:`<`   `1` if a is less than b, `0` otherwise            :code:`Int(1) < Int(5)`
+:code:`Gt(a, b)`     :code:`>`   `1` if a is greater than b, `0` otherwise         :code:`Int(1) > Int(5)`
+:code:`Le(a, b)`     :code:`<=`  `1` if a is no greater than b, `0` otherwise      :code:`Int(1) <= Int(5)`
+:code:`Ge(a, b)`     :code:`>=`  `1` if a is no less than b, `0` otherwise         :code:`Int(1) >= Int(5)`
+:code:`Add(a, b)`    :code:`+`   `a + b`, error (panic) if overflow                :code:`Int(1) + Int(5)`
+:code:`Minus(a, b)`  :code:`-`   `a - b`, error if underflow                       :code:`Int(5) - Int(1)`
+:code:`Mul(a, b)`    :code:`*`   `a * b`, error if overflow                        :code:`Int(2) * Int(3)`
+:code:`Div(a, b)`    :code:`/`   `a / b`, error if devided by zero                 :code:`Int(3) / Int(2)`
+:code:`Mod(a, b)`    :code:`%`   `a % b`, modulo operation                         :code:`Int(7) % Int(3)`
+:code:`Eq(a, b)`     :code:`==`  `1` if a equals b, `0` otherwise                  :code:`Int(7) == Int(7)`
+==================== =========== ================================================= =========================
+
+
+All these operators takes two :code:`TealType.uint64` values.
+In addition, :code:`Eq(a, b)` (:code:`==`)  is polymorphic:
+it also takes two `TealType.bytes` values. For example, :code:`Arg(0) == Arg(1)` is a valid PyTeal expression.
+
+While using overloaded Python arithmatic operators, the associativity and precedence is the same as the
+`original python operators <https://docs.python.org/3/reference/expressions.html#operator-precedence>`_ . For example:
+
+ * :code:`Int(1) + Int(2) + Int(3)` is equivalent to :code:`Add(Add(Int(1), Int(2)), Int(3))`
+ * :code:`Int(1) + Int(2) * Int(3)` is equivalent to :code:`Add(Int(1), Mul(Int(2), Int(3)))` 
+
+
+
+
+

docs/data_type.rst

@@ -5,30 +5,33 @@ Data Types and Constants
 
 A PyTeal expression has one of the following two data types:
 
- * `TealType.uint64`, 64 bit unsigned integer
- * `TealType.bytes`, a slice of bytes
+ * :code:`TealType.uint64`, 64 bit unsigned integer
+ * :code:`TealType.bytes`, a slice of bytes
 
 
-For example, all the transaction arguments (e.g. `Arg(0)`) are of type `TealType.bytes`.
-The first valid round of current transaction (`Txn.first_valid()`) is typed `TealType.uint64`.
+For example, all the transaction arguments (e.g. :code:`Arg(0)`) are of type :code:`TealType.bytes`.
+The first valid round of current transaction (:code:`Txn.first_valid()`) is typed :code:`TealType.uint64`.
 
-`Int(n)` creates a `TealType.uint64` constant, where `n >= 0 and n < 2 ** 64`.
+:code:`Int(n)` creates a :code:`TealType.uint64` constant, where :code:`n >= 0 and n < 2 ** 64`.
 
-`Bytes(encoding, value)` creates a `TealType.bytes` constant, where `encoding` could be either
+:code:`Bytes(encoding, value)` creates a :code:`TealType.bytes` constant, where :code:`encoding` could be either
 of the following:
 
- * `"base16"`, its paired `value` needs to be a `RFC 4648 <https://tools.ietf.org/html/rfc4648>`_ base16 encoded string, e.g. `"0xA21212EF"` or
-   `"A21212EF"`
- * `"base32"`, its paired `value` needs to be a RFC 4648 base32 encoded string **without padding**, e.g. `"7Z5PWO2C6LFNQFGHWKSK5H47IQP5OJW2M3HA2QPXTY3WTNP5NU2MHBW27M"`
- * `"base64"`, its paired `value` needs to be a RFC 4648 base64 encoded string, e.g. `"Zm9vYmE="`
+ * :code:`"base16"`: its paired :code:`value` needs to be a `RFC 4648 <https://tools.ietf.org/html/rfc4648>`_ base16 encoded string, e.g. :code:`"0xA21212EF"` or
+   :code:`"A21212EF"`
+ * :code:`"base32"`: its paired :code:`value` needs to be a RFC 4648 base32 encoded string **without padding**, e.g. :code:`"7Z5PWO2C6LFNQFGHWKSK5H47IQP5OJW2M3HA2QPXTY3WTNP5NU2MHBW27M"`
+ * :code:`"base64"`: its paired :code:`value` needs to be a RFC 4648 base64 encoded string, e.g. :code:`"Zm9vYmE="`
 
 All PyTeal expressions are type checked at construction time, for example, running
-the following code triggers a `TealTypeError`:  ::
+the following code triggers a :code:`TealTypeError`:  ::
 
   Int(0) < Arg(0)
 
-Since `<` (overloaded Python operator, see :ref:`arithmetic_expressions` for more details)
-requires both operands of type `TealType.uint64`,
-while `Arg(0)` is of type `TealType.bytes`.
+Since :code:`<` (overloaded Python operator, see :ref:`arithmetic_expressions` for more details)
+requires both operands of type :code:`TealType.uint64`,
+while :code:`Arg(0)` is of type :code:`TealType.bytes`.
 
+Converting a value to its corresponding value in the other data type is supported by the following two operators:
 
+ * :code:`Itob(n)`: generate a :code:`TealType.bytes` value from a :code:`TealType.uint64` value :code:`n`
+ * :code:`Btoi(b)`: generate a :code:`TealType.uint64` value from a :code:`TealType.bytes` value :code:`b`