From 919235745263b36bdd7a88374b79f34214b14a5f Mon Sep 17 00:00:00 2001 From: VoR0220 Date: Wed, 18 May 2016 15:53:36 -0500 Subject: [PATCH] updated docs types reference --- docs/types.rst | 56 +++++++++++++++++++++++++++++++++------ libsolidity/ast/Types.cpp | 17 +++++++++--- 2 files changed, 61 insertions(+), 12 deletions(-) diff --git a/docs/types.rst b/docs/types.rst index 93e70ddb0..d18a9490c 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -52,7 +52,7 @@ Operators: * Arithmetic operators: `+`, `-`, unary `-`, unary `+`, `*`, `/`, `%` (remainder), `**` (exponentiation) Division always truncates (it just maps to the DIV opcode of the EVM), but it does not truncate if both -operators are :ref:`literals` (or literal expressions). +operators are :ref:`literals` (or literal expressions). .. index:: address, balance, send, call, callcode, delegatecall @@ -135,20 +135,60 @@ As a rule of thumb, use `bytes` for arbitrary-length raw byte data and `string` for arbitrary-length string (utf-8) data. If you can limit the length to a certain number of bytes, always use one of `bytes1` to `bytes32` because they are much cheaper. -.. index:: literal, literal;integer +.. index:: ! ufixed, ! fixed, ! fixed point number -.. _integer_literals: +Fixed Point Numbers +------------------- -Integer Literals ------------------ +**bold** COMING SOON... **bold** -Integer Literals are arbitrary precision integers until they are used together with a non-literal. In `var x = 1 - 2;`, for example, the value of `1 - 2` is `-1`, which is assigned to `x` and thus `x` receives the type `int8` -- the smallest type that contains `-1`, although the natural types of `1` and `2` are actually `uint8`. +.. index:: literal, literal;rational -It is even possible to temporarily exceed the maximum of 256 bits as long as only integer literals are used for the computation: `var x = (0xffffffffffffffffffff * 0xffffffffffffffffffff) * 0;` Here, `x` will have the value `0` and thus the type `uint8`. +.. _rational_literals: + +Rational and Integer Literals +----------------------------- + +All number literals retain arbitrary precision until they are converted to a non-literal type (i.e. by +using them together with a non-literal type). This means that computations do not overflow but also +divisions do not truncate. + +For example, `(2**800 + 1) - 2**800` results in the constant `1` (of type `uint8`) +although intermediate results would not even fit the machine word size. Furthermore, `.5 * 8` results +in the integer `4` (although non-integers were used in between). + +If the result is not an integer, +an appropriate `ufixed` or `fixed` type is used whose number of fractional bits is as large as +required (approximating the rational number in the worst case). + +In `var x = 1/4;`, `x` will receive the type `ufixed0x8` while in `var x = 1/3` it will receive +the type `ufixed0x256` because `1/3` is not finitely representable in binary and will thus be +approximated. + +Any operator that can be applied to integers can also be applied to literal expressions as +long as the operators are integers. If any of the two is fractional, bit operations are disallowed +and exponentiation is disallowed if the exponent is fractional (because that might result in +a non-rational number). + +.. note:: + Most finite decimal fractions like `5.3743` are not finitely representable in binary. The correct type + for `5.3743` is `ufixed8x248` because that allows to best approximate the number. If you want to + use the number together with types like `ufixed` (i.e. `ufixed128x128`), you have to explicitly + specify the desired precision: `x + ufixed(5.3743)`. .. warning:: - Divison on integer literals used to truncate in earlier versions, but it will actually convert into a rational number in the future, i.e. `1/2` is not equal to `0`, but to `0.5`. + Division on integer literals used to truncate in earlier versions, but it will now convert into a rational number, i.e. `5 / 2` is not equal to `2`, but to `2.5`. +.. note:: + Literal expressions are converted to a permanent type as soon as they are used with other + expressions. Even though we know that the value of the + expression assigned to `b` in the following example evaluates to an integer, it still + uses fixed point types (and not rational number literals) in between and so the code + does not compile + +:: + uint128 a = 1; + uint128 b = 2.5 + a + 0.5; .. index:: literal, literal;string, string diff --git a/libsolidity/ast/Types.cpp b/libsolidity/ast/Types.cpp index e8ec32dca..d989cb061 100644 --- a/libsolidity/ast/Types.cpp +++ b/libsolidity/ast/Types.cpp @@ -346,9 +346,13 @@ TypePointer IntegerType::binaryOperatorResult(Token::Value _operator, TypePointe return TypePointer(); // Nothing else can be done with addresses if (auto intType = dynamic_pointer_cast(commonType)) + { if (intType->isAddress()) return TypePointer(); - + } + else if (auto fixType = dynamic_pointer_cast(commonType)) + if (Token::Exp == _operator) + return TypePointer(); return commonType; } @@ -436,9 +440,9 @@ string FixedPointType::toString(bool) const TypePointer FixedPointType::binaryOperatorResult(Token::Value _operator, TypePointer const& _other) const { if ( - _other->category() != Category::RationalNumber - && _other->category() != category() - && _other->category() != Category::Integer + _other->category() != Category::RationalNumber && + _other->category() != category() && + _other->category() != Category::Integer ) return TypePointer(); auto commonType = Type::commonType(shared_from_this(), _other); //might be fixed point or integer @@ -452,8 +456,13 @@ TypePointer FixedPointType::binaryOperatorResult(Token::Value _operator, TypePoi if (Token::isBitOp(_operator) || Token::isBooleanOp(_operator)) return TypePointer(); if (auto fixType = dynamic_pointer_cast(commonType)) + { if (Token::Exp == _operator) return TypePointer(); + } + else if (auto intType = dynamic_pointer_cast(commonType)) + if (intType->isAddress()) + return TypePointer(); return commonType; }