Spec updates for ranges and domains (#23521)

This PR makes the following changes, mostly in the language spec:

* Remove the difference between the definitions of "the range has
  ambiguous alignment" and "the range is ambiguously aligned".
* Add implicit conversions for ranges and updates explicit conversions
  for ranges and domains.
* Remove several counter-productive where-clauses from online docs.
* Indicate that `domain` written by itself is generic.

TODO:
* [ ] Add implicit conversions for domains.
* [ ] Move these configs out of the spec because they are
      purely about the implementation:
      newSliceRule, newRangeLiteralType, noNegativeStrideWarnings.
* [ ] Replace "ambiguously aligned" and "alignment is unambiguous"
      with "[un]aligned" throughout ChapelRange.chpl.

r: @DanilaFe

Author: vasslitvinov

doc/rst/language/spec/conversions.rst

@@ -53,6 +53,8 @@ the referenced subsections:
    compile-time
    constant (:ref:`Implicit_Compile_Time_Constant_Conversions`),
 
+-  ranges (:ref:`Implicit_Range_Conversions`),
+
 -  class types (:ref:`Implicit_Class_Conversions`), and
 
 -  when the source type is a subtype of the target type (including when
@@ -174,6 +176,30 @@ implicitly convert:
  * to ``uint`` of matching or greater size or to ``real``
  * or, to ``complex`` of any size.
 
+.. _Implicit_Range_Conversions:
+
+Implicit Range Conversions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implicit conversions among range types are allowed when all values
+representable in the source type can also be represented in the target
+type, retaining their full precision. In particular, an implicit
+conversion is allowed when:
+
+* the ``idxType`` of the source can be implicitly converted
+  to the ``idxType`` of the target,
+
+* the ``bounds`` of the source and the target are the same, and
+
+* one of the following holds:
+
+ - the ``strides`` of the source and the target are the same,
+ - the ``strides`` of the target is ``any``,
+ - the ``strides`` of the target is ``positive``
+   and the ``strides`` of the source is ``one``, or
+ - the ``strides`` of the target is ``negative``
+   and the ``strides`` of the source is ``negOne``.
+
 .. _Implicit_Class_Conversions:
 
 Implicit Class Conversions
@@ -389,7 +415,8 @@ the following program locations:
 Implicit conversions for initialization or assignment are allowed between
 numeric and boolean types (:ref:`Implicit_NumBool_Conversions`), numeric
 types in the special case when the expression’s value is a compile-time
-constant (:ref:`Implicit_Compile_Time_Constant_Conversions`), class types
+constant (:ref:`Implicit_Compile_Time_Constant_Conversions`), ranges
+(:ref:`Implicit_Range_Conversions`), class types
 (:ref:`Implicit_Class_Conversions`), and for generic target types
 (:ref:`Subtype_Arg_Conversions`).
 
@@ -478,7 +505,8 @@ type of the corresponding formal argument, if the formal’s intent is
 Implicit conversions for function calls are allowed between numeric
 and boolean types (:ref:`Implicit_NumBool_Conversions`), numeric types
 in the special case when the expression’s value is a compile-time
-constant (:ref:`Implicit_Compile_Time_Constant_Conversions`), class
+constant (:ref:`Implicit_Compile_Time_Constant_Conversions`),
+ranges (:ref:`Implicit_Range_Conversions`), class
 types (:ref:`Implicit_Class_Conversions`), and for generic target
 types (:ref:`Subtype_Arg_Conversions`).
 
@@ -768,18 +796,28 @@ expression or a type expression.
 Explicit Range Conversions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An expression of a range type with ``strides=strideKind.any``
-can be explicitly converted to a range type with ``strides=strideKind.one``,
-changing the stride to 1 in the process.
+An expression of a range type can be explicitly converted to another
+range type with the same ``bounds`` parameter. Upon such conversion,
+each non-infinite bound of the source is explicitly converted
+to the target's ``idxType``. The explicit conversion for ranges
+is not allowed when the explicit conversion between their ``idxTypes``
+is not allowed.
+
+The explicit conversion results in an error when the ``stride`` value
+of the source is not legal for the target type. This may be the case
+either because the source stride is not representable within the
+target's stride type or it is of the opposite sign than expected
+by the target's ``strides`` parameter.
 
 .. _Explicit_Domain_Conversions:
 
 Explicit Domain Conversions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-An expression of a domain type with ``strides=strideKind.any``
-can be explicitly converted to a domain type with ``strides=strideKind.one``,
-changing all strides to 1 in the process.
+An expression of a rectangular domain type can be explicitly converted
+to another rectangular domain type of the same ``rank``.
+Such conversion is performed dimension-wise following the rules
+for explicit range conversions (see :ref:`Explicit_Range_Conversions`).
 
 .. _Explicit_String_to_Bytes_Conversions:
 

doc/rst/language/spec/domains.rst

@@ -134,6 +134,10 @@ types include all of the associative domain types.
 These base domain types are discussed in turn in the following
 subsections.
 
+The keyword ``domain``, when not followed by parentheses, refers to
+a generic type that can be instantiated with any domain type.
+This type may also be written as ``domain(?)``.
+
 Rectangular Domains
 ~~~~~~~~~~~~~~~~~~~
 

doc/rst/language/spec/ranges.rst

@@ -46,7 +46,10 @@ follows.
    explicitly. Instead, infinite bound(s) are represented implicitly in
    the range’s type (:ref:`Range_Types`). When the low and/or high
    bound is :math:`\infty`, the represented sequence is unbounded in the
-   corresponding direction(s).
+   corresponding direction(s). However, when indices are drawn from
+   a finite type, such as booleans or enum constants, the represented
+   sequence always terminates when it runs out of legal indices
+   of this type.
 
 -  The *stride* is a non-zero integer. It defines the distance between
    any two adjacent members of the represented sequence. The sign of the
@@ -58,55 +61,39 @@ follows.
 
 -  The *alignment* is either a specific index value or is *ambiguous*.
    It defines how the represented sequence’s members are aligned
-   relative to the stride. For a range with a stride other than 1 or -1,
-   ambiguous alignment means that the represented sequence is undefined.
-   In such a case, certain operations discussed later result in an
-   error.
-   The alignment is always between zero and :math:`|stride|-1`,
-   inclusively.
-
-More formally, the represented sequence for the range
-:math:`(low, high, stride, alignmt)` contains all indices :math:`ix`
-such that:
-
-=========================================================================== ============================================
-:math:`low \leq ix \leq high`                                               if :math:`stride = 1` or :math:`stride = -1`
-:math:`low \leq ix \leq high` and :math:`ix \equiv alignmt \pmod{|stride|}` if :math:`alignmt` is not ambiguous
-the represented sequence is undefined                                       otherwise
-=========================================================================== ============================================
-
-The sequence, if defined, is increasing if :math:`stride > 0` and
-decreasing if :math:`stride < 0`.
+   relative to the stride. The alignment, when unambiguous,
+   is always between zero and :math:`|stride|-1`, inclusively.
+
+A range with unambiguous alignment is called *aligned*. Otherwise
+the range is *unaligned* and its represented sequence is undefined.
+
+The represented sequence for an aligned range
+:math:`(low, high, stride, alignmt)`
+with integral indices contains all indices :math:`ix` such that:
+
+   :math:`low \leq ix \leq high` and :math:`ix \equiv alignmt \pmod{|stride|}`
 
 If the represented sequence is defined but there are no indices
-satisfying the applicable equation(s) above, the range and its
+satisfying the above equation, the range and its
 represented sequence are *empty*. A common case of this occurs when the
 low bound is greater than the high bound.
 
 We say that a value :math:`ix` is *aligned* w.r.t. the range
 :math:`(low, high, stride, alignmt)` if:
 
--  :math:`alignmt` is not ambiguous and
-   :math:`ix \equiv alignmt \pmod{|stride|}`, or
-
--  :math:`stride` is 1 or -1.
+   :math:`alignmt` is not ambiguous and
+   :math:`ix \equiv alignmt \pmod{|stride|}`.
 
 Furthermore, :math:`\infty` is never aligned.
 
 Ranges have the following additional properties.
 
--  A range is *ambiguously aligned* if
-
-   -  its alignment is ambiguous, and
-
-   -  its stride is neither 1 nor -1.
-
 -  The *first index* is the first member of the represented sequence.
 
    A range *has no* first index when the first member is undefined, that
    is, in the following cases:
 
-   -  the range is ambiguously aligned,
+   -  the range is unaligned,
 
    -  the represented sequence is empty,
 
@@ -121,7 +108,7 @@ Ranges have the following additional properties.
    A range *has no* last index when the last member is undefined, that
    is, in the following cases:
 
-   -  it is ambiguously aligned,
+   -  the range is unaligned,
 
    -  the represented sequence is empty,
 
@@ -156,8 +143,8 @@ Range Types
 The type of a range is characterized by three properties:
 
 -  ``idxType`` is the type of the values in the range’s represented
-   sequence. However, when the range’s low and/or high bound is
-   :math:`\infty`, the represented sequence also contains indices that
+   sequence. However, when the range’s represented sequence is infinite,
+   it also contains indices that
    are not representable by ``idxType``.
 
    ``idxType`` must be an integral, boolean, or enumerated type and is
@@ -242,8 +229,8 @@ header:
                 param bounds  = boundKind.both,
                 param strides = strideKind.one) type
 
-As a special case, the keyword ``range`` without a parenthesized
-argument list refers to the range type with the default values of all
+As a special case, the keyword ``range`` written without a parenthesized
+argument list refers to the concrete range type with the default values of all
 its parameters, i.e., ``range(int, boundKind.both, strideKind.one)``.
 
    *Example (rangeVariable.chpl)*.
@@ -346,7 +333,7 @@ The value of a range literal is as follows:
 
 -  The stride is 1.
 
--  The alignment is ambiguous.
+-  The alignment is 0.
 
 .. _Range_Default_Values:
 
@@ -378,11 +365,6 @@ the type’s ``bounds`` parameter as follows:
    ``high``-bounded range (or visa versa) produces an empty range,
    matching the default value for a ``both``-bounded range
 
-.. warning::
-
-   Default initialization of ranges with ``boundKind.low`` or
-   ``boundKind.high`` is unstable.
-
 Default values of ranges with boolean ``idxType`` are similar, but
 substituting ``false`` and ``true`` for 0 and 1 above.  Ranges with
 ``enum`` ``idxType`` use the 0th and 1st values in the enumeration in
@@ -391,6 +373,12 @@ default value uses the 0th value as the low bound and has an undefined
 high bound; the ``.size`` query should be used with such ranges before
 querying the high bound to determine whether or not it is valid.
 
+.. warning::
+
+   Default initialization of ranges with ``boundKind.low`` or
+   ``boundKind.high`` is unstable w.r.t. the value of their
+   finite bound.
+
 .. _Ranges_Common_Operations:
 
 Common Operations
@@ -445,12 +433,9 @@ Ranges can be compared using equality and inequality.
 
 .. warning::
 
-   Equality comparisons for ranges over ``enum`` or ``bool`` types
-   when one of the ranges is bounded and the other is unbounded
-   is currently unstable.
-   We currently treat both ranges as being bounded.
-   This might change in the future.
-
+   Equality comparisons currently treat ranges over ``enum`` or ``bool`` types
+   as bounded on both ends regardless of their ``bounds`` parameters.
+   This behavior is unstable and might change in the future.
 
 .. function:: operator ==(r1: range(?), r2: range(?)): bool
 
@@ -844,8 +829,7 @@ the specified number of indices. Specifically:
 It is an error to apply the count operator with a positive count to a
 range that has no first index. It is also an error to apply the count
 operator with a negative count to a range that has no last index. It is
-an error to apply the count operator to a range that is ambiguously
-aligned.
+an error to apply the count operator to an unaligned range.
 It is an error if the count is greater than the ``size`` of the range.
 
    *Example (rangeCountOperator.chpl)*.
@@ -872,6 +856,12 @@ It is an error if the count is greater than the ``size`` of the range.
    Each of these ranges represents the ordered set of three indices: 6,
    4, 2.
 
+.. warning::
+
+   The count operator currently treats ranges over ``enum`` or ``bool`` types
+   as bounded on both ends regardless of their ``bounds`` parameters.
+   This behavior is unstable and might change in the future.
+
 .. _Range_Arithmetic:
 
 Arithmetic Operators
@@ -897,8 +887,8 @@ the result range are the same as for the input range.
 The stride of the resulting range is the same as the stride of the
 original. The alignment of the resulting range is shifted by the same
 amount as the high and low bounds. It is permissible to apply the shift
-operators to a range that is ambiguously aligned. In that case, the
-resulting range is also ambiguously aligned.
+operators to an unaligned range. In that case, the
+resulting range is also unaligned.
 
    *Example (rangeAdd.chpl)*.
 
@@ -922,6 +912,11 @@ resulting range is also ambiguously aligned.
 
       (0..3, 1..4)
 
+.. warning::
+
+   These operators are unstable.
+   They may be removed or change behavior in the future.
+
 .. _Range_Slicing:
 
 Range Slicing
@@ -969,8 +964,8 @@ Range slicing is specified by the syntax:
 
       (1..20, 3..20, 1..20 by 2, 1..20 by 6 align 3)
 
-It is an error for the first operand to be ambiguously aligned.
-If the second operand is ambiguously aligned, it is replaced
+It is an error for the first operand to be unaligned.
+If the second operand is unaligned, it is replaced
 with a range that is identical except it is given an alignment
 in such a way that that the intersection of the two ranges'
 represented sequences is non-empty, if possible.

modules/internal/ChapelDomain.chpl

@@ -2889,6 +2889,7 @@ module ChapelDomain {
        do not fit in the new idxType or when the original stride(s)
        are not legal for the new `strides` parameter.
      */
+    pragma "no where doc"
     proc tryCast(type t: domain)
       where chpl__isRectangularDomType(t) && this.isRectangular()
         &&  this.chpl_domainTryCastIsSafe(t)

modules/internal/ChapelRange.chpl

@@ -677,12 +677,14 @@ module ChapelRange {
 
 
   /* Returns the range's stride. */
+  pragma "no where doc"
   inline proc range.stride where !hasParamStride() do return _stride;
 
   @chpldoc.nodoc proc range.stride param where hasParamStride() do
     return (if strides == strideKind.one then 1 else -1) : strType;
 
   /* Returns the range's alignment. */
+  pragma "no where doc"
   inline proc range.alignment where !hasParamAlignment() do
     return chpl_intToIdx(if hasParamAlignmentField() then 0 else _alignment);
 
@@ -691,6 +693,7 @@ module ChapelRange {
 
   /* Returns ``true`` if the range's alignment is unambiguous,
      ``false`` otherwise. */
+  pragma "no where doc"
   inline proc range.isAligned() where !hasParamAligned() do
     return _alignment != unalignedMark;
 
@@ -699,6 +702,7 @@ module ChapelRange {
 
   /* Returns ``true`` if the range's alignment is unambiguous,
      ``false`` otherwise. */
+  pragma "no where doc"
   @deprecated("'range.aligned' is deprecated; please use '.isAligned()' instead")
   inline proc range.aligned where !hasParamAligned() do
     return isAligned();
@@ -1242,6 +1246,7 @@ module ChapelRange {
 
   /* Returns ``true`` if this range is naturally aligned, ``false``
      otherwise. */
+  pragma "no where doc"
   @deprecated("'range.isNaturallyAligned()' is deprecated; please feel encouraged to file a GitHub issue requesting it: https://github.com/chapel-lang/chapel/issues")
   proc range.isNaturallyAligned()
     where ! hasPosNegUnitStride() && bounds != boundKind.neither
@@ -1253,6 +1258,7 @@ module ChapelRange {
   do return chpl_isNaturallyAligned();
 
   // tells whether omitting the 'align' clause results in the same range
+  pragma "no where doc"
   proc range.chpl_isNaturallyAligned()
     where ! hasPosNegUnitStride() && bounds != boundKind.neither
   do if bounds == boundKind.both {
@@ -1274,6 +1280,7 @@ module ChapelRange {
 
   /* Returns ``true`` if the range is ambiguously aligned, ``false``
      otherwise. */
+  pragma "no where doc"
   @deprecated("'range.isAmbiguous()' is deprecated; please use '! range.isAligned()' instead")
   proc range.isAmbiguous() param where hasPosNegUnitStride() do
     return ! isAligned();