Merge remote-tracking branch 'upstream/master' into stable

Author: dkorpel

areas-of-d-usage.dd

@@ -92,8 +92,8 @@ $(AREA_SECTION3 $(LNAME2 games, Games), $(ARTICLE_FA_ICON gamepad),
     Many pure-D open source projects show the rising popularity
     of D among game developers.
     Examples are the 3D game engine
-    $(HTTP https://github.com/gecko0307/dagon, Dagon) and the  cross-platform D game development engine
-    $(HTTPS https://github.com/MrcSnm/HipremeEngine, HipremeEngine).
+    $(HTTPS github.com/gecko0307/dagon, Dagon) and the  cross-platform D game development engine
+    $(HTTPS github.com/MrcSnm/HipremeEngine, HipremeEngine).
 )
 
 $(AREA_SECTION3 $(LNAME2 web, Web applications), $(ARTICLE_FA_ICON cloud),
@@ -157,7 +157,7 @@ $(AREA_SECTION3 $(LNAME2 embedded, Embedded applications), $(ARTICLE_FA_ICON gea
 
     Using $(HTTPS github.com/ldc-developers/ldc, LDC) (the LLVM D compiler)
     enables targeting most popular CPU architectures,
-    starting from ARM and MIPS-based embedded systems and smartphones,
+    starting from ARM, RISC-V and MIPS-based embedded systems and smartphones,
     ranging to server systems based on POWER and Sparc, and up to the "big iron" z Systems.
 
 ))

spec/attribute.dd

@@ -259,8 +259,8 @@ $(GNAME AlignAttribute):
         $(LI struct, union, and class types)
         )
 
-        $(P $(D align $(LPAREN) default $(RPAREN)) (re)sets it to the default, which matches the default member alignment
-        of the companion C compiler. $(D align) by itself is the same as $(D align $(LPAREN) default $(RPAREN)).)
+        $(P $(D align$(LPAREN)default$(RPAREN)) (re)sets it to the default, which matches the default member alignment
+        of the companion C compiler. $(D align) by itself is the same as $(D align$(LPAREN)default$(RPAREN)).)
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
 --------

spec/class.dd

@@ -253,11 +253,30 @@ $(H3 $(LNAME2 field_properties, Field Properties))
 
 $(H2 $(LNAME2 member-functions, Member Functions (a.k.a. Methods)))
 
-        $(P Non-static member functions have an extra hidden parameter
+        $(P Non-static member functions must be called on an instance of their class.
+        They have an extra hidden parameter
         called $(DDSUBLINK spec/expression, this, `this`) through which the class object's other members
         can be accessed.
+        Inside the function body, the class instance members are in scope.
         )
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+class C
+{
+    int a;
+
+    void foo()
+    {
+        a = 3; // assign to `this.a`
+    }
+}
+
+auto c = new C;
+c.foo();
+assert(c.a == 3);
+---
+)
         $(P Non-static member functions can have, in addition to the usual
         $(GLINK2 function, FunctionAttribute)s, the attributes
         $(D const), $(D immutable), $(D shared), $(D inout), $(D scope) or $(D return scope).
@@ -268,6 +287,7 @@ $(SPEC_RUNNABLE_EXAMPLE_FAIL
 class C
 {
     int a;
+
     void foo() const
     {
         a = 3; // error, 'this' is const
@@ -430,22 +450,31 @@ $(H2 $(LNAME2 class-instantiation, Class Instantiation))
 
 $(H3 $(LNAME2 constructors, Constructors))
 
+        $(P A constructor is a special $(RELATIVE_LINK2 member-functions, member function)
+        which is normally $(RELATIVE_LINK2 instantiation-process, invoked by the compiler)
+        when the class instance is created.)
+
 $(GRAMMAR
 $(GNAME Constructor):
     $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, FunctionBody)
     $(D this) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT) $(GLINK2 function, MissingFunctionBody)
     $(GLINK2 template, ConstructorTemplate)
 )
 
-        $(P Constructors are defined with a function name of $(D this)
-        and have no return value:)
+        $(P A constructor is declared with a function name of $(D this)
+        and no return type:)
 
         $(SPEC_RUNNABLE_EXAMPLE_RUN
         ------
         class A
         {
             int i;
 
+            this() // constructor taking no arguments
+            {
+                i = 2; // initialize `this.i`
+            }
+
             this(int i) // constructor taking an int argument
             {
                 this.i = i; // initialize field `i` from parameter `i`
@@ -454,11 +483,17 @@ $(GNAME Constructor):
 
         void main()
         {
-            A a = new A(3);
+            A a = new A; // instantiate A and call `A.this()`
+            assert(a.i == 2);
+
+            a = new A(3); // instantiate A and call `A.this(3)`
             assert(a.i == 3);
         }
         ------
         )
+        $(P Explicitly returning a value in a constructor is not allowed,
+        however `return;` may be used to exit the function early.)
+
 
 $(H3 $(LNAME2 base-construction, Base Class Construction))
 
@@ -503,6 +538,8 @@ $(H3 $(LNAME2 delegating-constructors, Delegating Constructors))
         }
         ------
 
+$(H3 $(LNAME2 ctor-restrictions, Restrictions))
+
         $(P The following restrictions apply:)
 
     $(OL
@@ -520,14 +557,16 @@ $(H3 $(LNAME2 delegating-constructors, Delegating Constructors))
         calls.)
         )
 
-        $(LI If a constructor's code contains a delegating constructor call, all
+        $(LI If a constructor's code contains a delegating/base constructor call, all
         possible execution paths through the constructor must make exactly one
-        delegating constructor call:
+        of those calls:
 
         ------
-        this() { a || super(); }       // illegal
+        this() { a || super(); } // illegal, 0 or 1 call
 
-        this() { (a) ? this(1) : super(); }     // ok
+        this() { (a) ? this(1) : super(); } // OK
+
+        this() { super(); this(1); } // illegal, 2 calls
 
         this()
         {
@@ -540,11 +579,14 @@ $(H3 $(LNAME2 delegating-constructors, Delegating Constructors))
         )
 
         $(LI It is illegal to refer to $(D this) implicitly or explicitly
-        prior to making a delegating constructor call.)
+        prior to making a delegating/base constructor call.)
 
-        $(LI Delegating constructor calls cannot appear after labels.)
+        $(LI Delegating/base constructor calls cannot appear after labels.)
     )
 
+    $(P See also: $(RELATIVE_LINK2 field-init, field initialization).)
+
+
 $(H3 $(LNAME2 implicit-base-construction, Implicit Base Class Construction))
 
         $(P If there is no constructor for a class, but there is a constructor

spec/expression.dd

@@ -2084,7 +2084,8 @@ $(TROW `(` *Expression* `)`, Evaluate an expression - useful as a
 
 $(H3 $(LNAME2 this, this))
 
-    $(P Within a constructor or non-static member function, $(D this) resolves to
+    $(P Within a constructor or $(DDSUBLINK spec/class, member-functions,
+        non-static member function), $(D this) resolves to
         a reference to the object for which the function was called.
     )
     $(P $(DDSUBLINK spec/type, typeof-this, `typeof(this)`) is valid anywhere
@@ -3269,9 +3270,16 @@ static assert(!is(immutable int == const));
         )
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ---
+Object o;
+static assert(!is(o == class)); // `o` is not a type
 static assert(is(Object == class));
 static assert(is(ModuleInfo == struct));
 static assert(!is(int == class));
+
+void f();
+static assert(!is(f == function)); // `f` is not a type
+static assert(is(typeof(f) == function));
+static assert(!is(typeof(&f) == function)); // function pointer is not a function
 ---
 )
         $(P The `module` and `package` forms are satisfied when *Type* is a symbol, not a *type*,

spec/function.dd

@@ -3600,17 +3600,16 @@ void main()
 ---
 )
 
-    $(P The function must have a $(GLINK SpecifiedFunctionBody).)
+    $(P The function must have a $(GLINK FunctionBody).)
 
     $(P CTFE is subject to the following restrictions:)
 
     $(OL
-    $(LI Expressions may not reference any global or local
-        static variables.)
+    $(LI Expressions may not reference any mutable static variables.)
 
     $(LI $(DDSUBLINK spec/iasm, asmstatements, AsmStatements) are not permitted)
 
-    $(LI Non-portable casts (eg, from $(D int[]) to $(D float[])), including
+    $(LI Non-portable casts (e.g., from $(D int[]) to $(D float[])), including
         casts which depend on endianness, are not permitted.
         Casts between signed and unsigned types are permitted.)
 
@@ -3656,7 +3655,7 @@ void main()
         )
 
         $(LI
-        Equality comparisons (==, !=, $(D_KEYWORD is), $(D_KEYWORD !is)) are
+        Equality comparisons ($(D ==), $(D !=), $(D is), $(D !is)) are
         permitted between all pointers, without restriction.
         )
 
@@ -3668,7 +3667,7 @@ void main()
     )
 
     $(P The above restrictions apply only to expressions which are
-        actually executed. For example:
+        actually evaluated. For example:
     )
 ---
 static int y = 0;
@@ -3703,7 +3702,7 @@ static assert(countTen(12) == 12);  // invalid, modifies y.
 
     $(IMPLEMENTATION_DEFINED
     Functions executed via CTFE can give different results
-    from run time when implementation-defined occurs.
+    from run time when implementation-defined behavior occurs.
     )
 
 

spec/hash-map.dd

@@ -81,8 +81,7 @@ $(H2 $(LNAME2 testing_membership, Testing Membership))
 
 $(H2 $(LNAME2 using_classes_as_key, Using Classes as the KeyType))
 
-        $(P Classes can be used as the $(I KeyType). For this to work,
-        the class definition must override the following member functions
+        $(P Classes can be used as the $(I KeyType). The behavior is controlled by the following member functions
         of class $(D Object):)
 
         $(UL
@@ -109,6 +108,8 @@ $(H2 $(LNAME2 using_classes_as_key, Using Classes as the KeyType))
             }
         }
         ---
+        The default implementation of $(D opEquals) uses the address of the instance for comparisons,
+        and the default implementation of $(D toHash) hashes the address of the instance.
 
         $(IMPLEMENTATION_DEFINED
         `opCmp` is not used to check for equality by the