diff --git a/static_core/plugins/ets/doc/spec/2_lexical.rst b/static_core/plugins/ets/doc/spec/2_lexical.rst index 2474bfe6c57c4f2b39af7fa611ef8a1d36fca128..230c0fcdba81879cae140446ddb320a38eaed08e 100644 --- a/static_core/plugins/ets/doc/spec/2_lexical.rst +++ b/static_core/plugins/ets/doc/spec/2_lexical.rst @@ -489,7 +489,7 @@ Numeric Literals .. meta: frontend_status: Done -Integer and Floating-Point literals are numeric literals. +Integer and floating-point literals are numeric literals. | diff --git a/static_core/plugins/ets/doc/spec/4_names.rst b/static_core/plugins/ets/doc/spec/4_names.rst index c69657cc94d200821c519be2ea8aeef74c58237f..a7e3839d7c329c59397f9bba354cc1f5c716518e 100644 --- a/static_core/plugins/ets/doc/spec/4_names.rst +++ b/static_core/plugins/ets/doc/spec/4_names.rst @@ -425,7 +425,7 @@ follows: or interface properties; - Function or method name is used to call the function or method; - Variable name is used to read or change the value of the variable; -- Compilation unit name introduced as a result of import with Bind All with +- Name of a compilation unit introduced as a result of import with Bind All with Qualified Access (see :ref:`Bind All with Qualified Access`) is used to deal with exported entities. diff --git a/static_core/plugins/ets/doc/spec/5_generics.rst b/static_core/plugins/ets/doc/spec/5_generics.rst index f86dcee3c72d74356bd0f17ecd8ccdecbb194316..1447cd2aa3e10af843fa1119b57284cba328c8aa 100644 --- a/static_core/plugins/ets/doc/spec/5_generics.rst +++ b/static_core/plugins/ets/doc/spec/5_generics.rst @@ -68,10 +68,10 @@ Type Parameters .. meta: frontend_status: Done -The type parameter is declared in the type parameter section. It can be used as +*Type parameter* is declared in the type parameter section. It can be used as an ordinary type inside a *generic*. -Syntactically, a type parameter is an unqualified identifier with a proper +Syntax-wise, a *type parameter* is an unqualified identifier with a proper scope (see :ref:`Scopes` for the scope of type parameters). Each type parameter can have a *constraint* (see :ref:`Type Parameter Constraint`). A type parameter can have a default type (see :ref:`Type Parameter Default`), and can @@ -118,9 +118,9 @@ specify its *in-* or *out-* variance (see :ref:`Type Parameter Variance`). A generic class, interface, type alias, method, function, or lambda defines a set of parameterized classes, interfaces, unions, arrays, methods, functions, or -lambdas respectively (see :ref:`Generic Instantiations`). -One type argument can define only one set for each possible parameterization of -the type parameter section. +lambdas respectively (see :ref:`Generic Instantiations`). A single type argument +can define only one set for each possible parameterization of the type parameter +section. .. index:: generic declaration @@ -178,7 +178,7 @@ Type Parameter Constraint frontend_status: Done If possible instantiations need to be constrained, then an individual -*constraint* can be set for every type parameter. +*constraint* can be set for each type parameter. A constraint of any type parameter can follow the keyword ``extends``. The constraint is denoted as a type reference, or a union type. If no constraint is @@ -187,7 +187,7 @@ methods or fields available for use. Lack of constraint effectively means ``extends Object|null|undefined``. If type parameter *T* has type constraint *S*, then the actual type of the generic instantiation must be compatible with *S* (see :ref:`Type Compatibility`). If the constraint *S* is a non-nullish -type (see :ref:`Nullish Types`), then *T* is non-nullish too. +type (see :ref:`Nullish Types`), then *T* is also non-nullish. .. index:: constraint @@ -381,8 +381,8 @@ argument types. derived class base class -Special markers are used to specify the *declaration-site variance*. The -markers are to be added to generic parameter declarations. These markers are +Special markers are used to specify *declaration-site variance*. The +markers are to be added to generic parameter declarations. The markers are expressed as keywords ``in`` or ``out`` (a *variance modifier* that specifies the variance of the type parameter). @@ -462,9 +462,9 @@ type parameter *F* defines the subtyping between ``T`` and ``T`` (in the case of declaration-site variance with two different types ``A`` <: ``B``) as follows: -- Covariant :ref:`Covariance` (*out F*): ``T`` <: ``T``; -- Contravariant :ref:`Contravariance` (*in F*): ``T`` :> ``T``; -- Invariant (default) (*F*). +- Covariant -- :ref:`Covariance` (*out F*): ``T`` <: ``T``; +- Contravariant -- :ref:`Contravariance` (*in F*): ``T`` :> ``T``; +- Invariant -- default (*F*). .. index:: type parameter @@ -532,7 +532,7 @@ generic instantiation, then the compiler actually replaces it as follows: method (p: A) {} // Here A is a new non-generic type } -**Note**. Built-in arrays are not generics, thus ``number[]`` contains elements +**Note**. Built-in arrays are not generic, thus ``number[]`` contains elements of type ``number`` but not ``Number``. .. index:: @@ -562,7 +562,7 @@ Type Arguments .. meta: frontend_status: Done -Type arguments is a non-empty list of types being used for instantiation. +Type arguments are a non-empty list of types that are used for instantiation. .. code-block:: abnf @@ -571,7 +571,8 @@ Type arguments is a non-empty list of types being used for instantiation. ; -Below is the example of instantiations with different forms of type arguments: +The example below represents instantiations with different forms of type +arguments: .. code-block:: typescript :linenos: @@ -660,8 +661,8 @@ parameterized declaration ranging over them. A generic instantiation *G* <``T``:sub:`1`, ``...``, ``T``:sub:`n`> is *well-formed* if **all** of the following is true: -- The generic declaration name is *G*. -- The number of type arguments equals the number of type parameters of *G*. +- The generic declaration name is *G*; +- The number of type arguments equals the number of type parameters of *G*; and - All type arguments are compatible with the corresponding type parameter constraint (see :ref:`Type Compatibility`). @@ -705,7 +706,7 @@ Implicit Generic Instantiations In an *implicit* instantiation, type arguments are not specified explicitly. Such type arguments are inferred (see :ref:`Type Inference`) from the context -the generic is referred in as in the example below: +in which a generic is referred. It is represented in the example below: .. code-block:: typescript :linenos: @@ -744,7 +745,7 @@ Utility Types frontend_status: Done |LANG| supports several embedded types, called *utility* types. Utility types -allow constructing new types by adjusting properties of the initial types. +allow constructing new types by adjusting properties of initial types. .. index:: embedded type @@ -762,8 +763,9 @@ Partial Utility Type frontend_status: Done Type ``Partial`` constructs a type with all properties of ``T`` set to -optional. ``T`` must be a class or an interface type. No method (including any +optional. ``T`` must be a class or an interface type. No method (not even any getter or setter) of ``T`` is part of the ``Partial`` type. +It is represented in the example below: .. code-block:: typescript :linenos: @@ -782,7 +784,7 @@ getter or setter) of ``T`` is part of the ``Partial`` type. process({title: "aa"}) // description is undefined In the example above, type ``Partial`` is transformed to a distinct but -analogous type: +analogous type as follows: .. code-block:: typescript :linenos: @@ -807,7 +809,8 @@ literals. **Note**. If class ``T`` has a user-defined getter, setter, or both, then none of those is called when object literal is used with ``Partial`` variables. -Object literal has its own built-in getters and setters to modify its variables: +Object literal has its own built-in getters and setters to modify its variables. +It is represented in the example below: .. code-block:: typescript :linenos: @@ -849,8 +852,9 @@ Required Utility Type Type ``Required`` is opposite to ``Partial``, and constructs a type with all properties of ``T`` set to required (i.e., not optional). ``T`` must be a -class or an interface type. No method (including any getter or setter) of ``T`` +class or an interface type. No method (not even any getter or setter) of ``T`` is part of the ``Required`` type. +It is represented in the example below: .. code-block:: typescript :linenos: @@ -865,7 +869,7 @@ is part of the ``Required`` type. } In the example above, type ``Required`` is transformed to a distinct -but analogous type: +but analogous type as follows: .. code-block:: typescript :linenos: @@ -901,10 +905,10 @@ Readonly Utility Type frontend_status: Done Type ``Readonly`` constructs a type with all properties of ``T`` set to -readonly. It means that the properties of the constructed value cannot be -reassigned. ``T`` must be a class or an interface type. No method (including -any getter or setter) of ``T`` is part of the ``Readonly`` type. - +``readonly``. It means that the properties of the constructed value cannot be +reassigned. ``T`` must be a class or an interface type. No method (not even +any getter or setter) of ``T`` is part of the ``Readonly`` type. It is +represented in the example below: .. code-block:: typescript :linenos: @@ -954,10 +958,11 @@ Record Utility Type frontend_status: Done Type ``Record`` constructs a container that maps keys (of type ``K``) -to values (of type ``V``). +to values of type ``V``. -Type ``K`` is restricted to numeric types (see :ref:`Numeric Types`), type -``string``, string literal types, and union types constructed from these types. +Type ``K`` is restricted to numeric types (see :ref:`Numeric Types`). Type +``string``, string literal types, and union types are constructed from these +types. A :index:`compile-time error` occurs if any other type, or literal of any other type is used in place of this type: @@ -984,7 +989,7 @@ type is used in place of this type: type R3 = Record<"salary" | "bonus", number> // ok type R4 = Record<"salary" | boolean, number> // compile-time error -There are no restrictions on type ``V``. +Type ``V`` has no restrictions. A special form of object literals is supported for instances of type ``Record`` (see :ref:`Object Literal of Record Type`). @@ -1033,9 +1038,9 @@ Utility Type Private Fields .. meta: frontend_status: Done -As utility types are built on top of other types private fields of the initial +Utility types are built on top of other types. Private fields of the initial type stay in the utility type but they are not accessible and cannot be -accessed in any form. +accessed in any way. It is represented in the example below: .. code-block:: typescript :linenos: diff --git a/static_core/plugins/ets/doc/spec/6_conversions.rst b/static_core/plugins/ets/doc/spec/6_conversions.rst index dd2149cf1b874d10d4df0c41dec3814f110980eb..647911fe4071920cc0f82f31acab9d8306d75fd7 100644 --- a/static_core/plugins/ets/doc/spec/6_conversions.rst +++ b/static_core/plugins/ets/doc/spec/6_conversions.rst @@ -124,9 +124,9 @@ Contexts can be of the following kinds: - :ref:`Assignment-like Contexts` where the expression value is bound to a variable; -- :ref:`String Operator Contexts` with ``string`` concatenation (operator ``+``); +- :ref:`String Operator Contexts` with ``string`` concatenation (operator '``+``'); -- :ref:`Numeric Operator Contexts` with all numeric operators (``+``, ``-``, etc.); +- :ref:`Numeric Operator Contexts` with all numeric operators ('``+``', '``-``', etc.); - :ref:`Casting Contexts and Conversions`, i.e., the conversion of an expression value to a type explicitly specified by a cast expression (see @@ -234,7 +234,7 @@ The examples are presented below: let a: number[] = [str.length, 11] In all these cases, the expression type either must be equal to the *target -type* or can be converted to the *target type* by using one of the conversions +type*, or can be converted to the *target type* by using one of the conversions discussed below. Otherwise, a :index:`compile-time error` occurs. Assignment-like contexts allow using of one of the following: @@ -291,14 +291,14 @@ String Operator Contexts frontend_status: Done *String context* applies only to a non-*string* operand of the binary operator -``+`` if the other operand is ``string``. +'``+``' if the other operand is ``string``. *String conversion* for a non-``string`` operand is evaluated as follows: - The operand of a nullish type that has a nullish value is converted as described below: - - The operand ``null`` is converted to string ``null``. + - The operand ``null`` is converted to string ``null``; - The operand ``undefined`` is converted to string ``undefined``. - An operand of a reference type or ``enum`` type is converted by applying the @@ -306,16 +306,16 @@ String Operator Contexts - An operand of an integer type (see :ref:`Integer Types and Operations`) is converted to type ``string`` with a value that represents the operand in - the decimal form; + the decimal form. - An operand of a floating-point type (see :ref:`Floating-Point Types and Operations`) is converted to type ``string`` with a value that represents the operand in - the decimal form (without the loss of information); + the decimal form (without the loss of information). - An operand of type ``boolean`` is converted to type ``string`` with the - values ``true`` or ``false``; + values ``true`` or ``false``. -- An operand of type ``char`` is converted by using :ref:`Character to String Conversions`; +- An operand of type ``char`` is converted by using :ref:`Character to String Conversions`. - An operand of enumeration type (see :ref:`Enumerations`) is converted to type ``string`` with the value of the corresponding enumeration constant @@ -381,17 +381,17 @@ The type of this operand is assumed to be ``int``. string context type int -The numeric contexts are actually the forms of the following expressions: +Numeric contexts actually take the following forms: -- Unary (see :ref:`Unary Expressions`); -- Multiplicative (see :ref:`Multiplicative Expressions`); -- Additive (see :ref:`Additive Expressions`); -- Shift (see :ref:`Shift Expressions`); -- Relational (see :ref:`Relational Expressions`); -- Equality (see :ref:`Equality Expressions`); -- Bitwise and Logical (see :ref:`Bitwise and Logical Expressions`); -- Conditional-And (see :ref:`Conditional-And Expression`); -- Conditional-Or (see :ref:`Conditional-Or Expression`). +- :ref:`Unary Expressions`; +- :ref:`Multiplicative Expressions`; +- :ref:`Additive Expressions`; +- :ref:`Shift Expressions`; +- :ref:`Relational Expressions`; +- :ref:`Equality Expressions`; +- :ref:`Bitwise and Logical Expressions`; +- :ref:`Conditional-And Expression`; +- :ref:`Conditional-Or Expression`. .. index:: numeric context @@ -483,7 +483,7 @@ conversion can lose precision or range, resulting in the following: Double ``NaN`` is converted to float ``NaN``. -Double infinity is converted to same-signed floating-point infinity. +Double infinity is converted to the same-signed floating-point infinity. A numeric conversion of a floating-point type operand to target types ``long`` or ``int`` is performed by the following rules: @@ -499,7 +499,7 @@ or ``int`` is performed by the following rules: *round-toward-zero* mode. A numeric casting conversion of a floating-point type operand to types -``short``, ``byte``, or ``char`` is performed in the following two steps: +``short``, ``byte``, or ``char`` is performed in two steps as follows: - The casting conversion to ``int`` is performed first (see above); - Then, the ``int`` operand is cast to the target type. @@ -605,7 +605,7 @@ Casting Conversions from Type Parameter .. meta: frontend_status: Done -A *casting conversion from a type parameter* attempts to convert an expression +*Casting conversion from a type parameter* attempts to convert an expression of the type parameter to any reference type (see :ref:`Reference Types`) which is to be specified as a target type. @@ -636,7 +636,7 @@ Casting Conversions from Union .. meta: frontend_status: Done -A *casting conversion from union* converts an expression of union type to one +*Casting conversion from union* converts an expression of union type to one of the types of the union, or to a type that is derived from such one type. For union type ``U = T``:sub:`1` ``| ... | T``:sub:`N`, the *casting conversion @@ -687,9 +687,9 @@ type of an expression is not the *target type*. Another form of *conversion from union* is implicit conversion from union type to the target type. The conversion is only possible if each type in a union is compatible (see :ref:`Type Compatibility`) with the target type. If so, the -conversion never causes a runtime error. If at least one type of a union is not -compatible with the target type, then the conversion causes a -:index:`compile-time error`: +conversion never causes a runtime error. The conversion causes a +:index:`compile-time error` if at least one type of a union is not compatible +with the target type: .. code-block-meta: expect-cte @@ -705,7 +705,7 @@ compatible with the target type, then the conversion causes a let b: Base = d // OK, as Derived1 and Derived2 are compatible with Base let x: Double | Base = ... - let y: double = x // Compile-time error, as Base cannot be converted into double + let y: double = x // Compile-time error, as Base cannot be converted to double .. index:: target type @@ -752,7 +752,7 @@ Primitive Types Conversions .. meta: frontend_status: Done -A *primitive type conversion* is one of the following: +*Primitive type conversion* is one of the following: - :ref:`Widening Primitive Conversions`; @@ -894,9 +894,8 @@ corresponding reference type. If the unboxed *target type* is larger than the expression type, then a *widening primitive conversion* is performed as the first step of a *boxing conversion* of numeric types and type ``char``. - For example, a *boxing conversion* converts *i* of primitive value type ``int`` -into a reference *n* of class type ``Number``: +to a reference *n* of class type ``Number`` as follows: .. code-block-meta: not-subset @@ -911,9 +910,8 @@ into a reference *n* of class type ``Number``: let c: char = 'a' let l: Long = c // char -> long -> Long -These conversions can cause ``OutOfMemoryError`` thrown if the storage -available for the creation of a new instance of the reference type is -not sufficient. +*Boxing conversions* can cause ``OutOfMemoryError`` to be thrown if the storage +available to create a new instance of the reference type is not sufficient. .. index:: widening conversion @@ -939,9 +937,8 @@ a corresponding primitive type. If the *target type* is larger than the unboxed expression type, then a *widening primitive conversion* is performed as the second step of the *unboxing conversion* of numeric types and type ``char``. - For example, the *unboxing conversion* converts *i* of reference type ``Int`` -into type ``long``: +to type ``long`` as follows: .. code-block-meta: not-subset @@ -973,18 +970,18 @@ Widening Union Conversions .. meta: frontend_status: Done -There are three options of *widening union conversion* as follows: +*Widening union conversion* can be of the following three options: - Conversion from a union type to a wider union type; - Conversion from a non-union type to a union type; - Conversion from a union type that consists of literals only to a non-union type. -These conversions never cause runtime errors. +*Widening union conversions* never cause runtime errors. -Union type ``U`` (``U``:sub:`1` ``| ... | U``:sub:`n`) can be converted into a -different union type ``V`` (``V``:sub:`1` ``| ... | V``:sub:`m`) if the following -is true after normalization (see :ref:`Union Types Normalization`): +Union type ``U`` (``U``:sub:`1` ``| ... | U``:sub:`n`) can be converted to a +different union type ``V`` (``V``:sub:`1` ``| ... | V``:sub:`m`) if after +normalization (see :ref:`Union Types Normalization`) the following is true: .. lines 724 764 initially was *U*:sub:`1` | ... | *U*:sub:`n` line 725 initially was *V*:sub:`1` | ... | *V*:sub:`m` @@ -1008,7 +1005,6 @@ is true after normalization (see :ref:`Union Types Normalization`): **Note**. If union type normalization issues a single type or value, then this type or value is used instead of the initial set of union types or values. - This concept is illustrated by the example below: .. code-block:: typescript @@ -1044,7 +1040,7 @@ if ``T`` is compatible with one of ``U``:sub:`i` types. u = "aa" // ok u = true // compile-time error -Union type ``U`` (``U``:sub:`1` ``| ... | U``:sub:`n`) can be converted into +Union type ``U`` (``U``:sub:`1` ``| ... | U``:sub:`n`) can be converted to non-union type ``T`` if each ``U``:sub:`i` is a literal that can be implicitly converted to type ``T``. @@ -1075,7 +1071,7 @@ Widening Reference Conversions .. meta: frontend_status: Done -A *widening reference conversion* handles any subtype (see :ref:`Subtyping`) as +*Widening reference conversion* handles any subtype (see :ref:`Subtyping`) as a supertype (see :ref:`Supertyping`). It requires no special action at runtime, and never causes an error. @@ -1198,12 +1194,8 @@ Constant String to Character Conversions *Constant string to character conversion* converts an expression of type ``string`` to type ``char``. The initial type ``string`` expression must be a constant expression (see :ref:`Constant Expressions`). The length of this -expression equals 1. - -The resultant ``char`` is the first and only character of the converted -``string``. - -This conversion never causes runtime errors. +expression equals 1. The resultant ``char`` is the first and only character +of the converted ``string``. This conversion never causes runtime errors. .. index:: character to string conversion @@ -1230,7 +1222,8 @@ A *function types conversion* is valid if the following conditions are met: parameter; - Return types are converted by using *covariance* (:ref:`Covariance`). -See :ref:`Type Compatibility` for details. +Contravariance and covariance are discussed in detail in +:ref:`Type Compatibility`. .. index:: function types conversion @@ -1261,7 +1254,7 @@ See :ref:`Type Compatibility` for details. bb = bd /* OK: identical (invariant) parameter types, and compatible return type */ bb = dd - /* Compile-time error: compatible parameter type(covariance), type unsafe */ + /* Compile-time error: compatible parameter type (covariance), type unsafe */ db = bd /* OK: contravariant parameter types, and compatible return type */ } @@ -1271,7 +1264,7 @@ See :ref:`Type Compatibility` for details. /* OK: identical (invariant) parameter types, and compatible return type */ let foo2: (p: Base) => Base = (p: Derived): Derived => new Derived() - /* Compile-time error: compatible parameter type(covariance), type unsafe */ + /* Compile-time error: compatible parameter type (covariance), type unsafe */ let foo3: (p: Derived) => Base = (p: Base): Derived => new Derived() /* OK: contravariant parameter types, and compatible return type */ @@ -1321,7 +1314,7 @@ Tuple Types Conversions *Tuple types conversion* is the conversion of one tuple type to another. Tuple type ``T`` = [``T``:sub:`1`, ``T``:sub:`2`, ``...``, ``T``:sub:`n`] can be -converted into tuple type ``U`` = [``U``:sub:`1`, ``U``:sub:`2`, ``...``, ``U``:sub:`m`] +converted to tuple type ``U`` = [``U``:sub:`1`, ``U``:sub:`2`, ``...``, ``U``:sub:`m`] if the following conditions are met: - Tuple types have the same number of elements, thus n == m. @@ -1344,7 +1337,6 @@ Enumeration to Constants Type Conversions A value of an *enumeration* type is converted to type ``int`` if enumeration constants of this type are of type ``int``. - This conversion never causes runtime errors. .. code-block:: typescript @@ -1366,7 +1358,6 @@ This conversion never causes runtime errors. A value of ``enumeration`` type is converted to type ``string`` if enumeration constants of this type are of type ``string``. - This conversion never causes runtime errors. .. code-block:: typescript @@ -1393,10 +1384,11 @@ Constant to Enumeration Conversions .. meta: frontend_status: None -A constant value of some integer type is converted to *enumeration* type if +A constant value of some integer type is converted to *enumeration* type if: + +- Enumeration constants are of type ``int``; +- Value is equal to the value of an enumeration constant. -- enumeration constants are of type ``int``. -- a value is equal to the value of an enumeration constant. This conversion never causes runtime errors. diff --git a/static_core/plugins/ets/doc/spec/7_expressions.rst b/static_core/plugins/ets/doc/spec/7_expressions.rst index b433fc9355ba7916efd15d69225c527a44c07ba2..54044ba7af4ad6ac0575d966f98d7d361bd449d8 100644 --- a/static_core/plugins/ets/doc/spec/7_expressions.rst +++ b/static_core/plugins/ets/doc/spec/7_expressions.rst @@ -1156,7 +1156,7 @@ These situations are presented in the examples below: If a class has accessors (see :ref:`Accessor Declarations`) for some property -then this properety can be used as a part of object literal if its setter is +then this property can be used as a part of object literal if its setter is provided. Otherwise it is a :index:`compile-time error`. .. code-block:: typescript @@ -1243,7 +1243,7 @@ occurs if the interface type ``I`` contains a method: let i : I = {name: "Bob"} // compile-time error, interface has methods If an interface has accessors (see :ref:`Accessor Declarations`) for some -property then if properety is used in an object literal then a +property then if property is used in an object literal then a :index:`compile-time error` occurs. .. code-block:: typescript