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

Author: MartinNowak

articles/code_coverage.dd

@@ -34,13 +34,15 @@ $(LI It can be used to track down why a particular section of code
 
 $(LI Since execution counts are given for each line, it is possible
      to use the coverage analysis to reorder the basic blocks in
-     a function to minimize jmps in the most used path, thus
-     optimizing it.)
-)
+     a function to minimize branches in the most used path, reducing stress
+     on the processor's pipeline (a run-of-the-mill X86 processor can usually handle 48 branches in its pipeline). This technique
+     is a special case of $(LINK2 https://en.wikipedia.org/wiki/Profile-guided_optimization, profile-guided optimization), which can
+     be performed automatically if either the `LLVM` or `GCC` backend is utilized.
+))
 
 $(P Experience with code coverage analyzers show that they dramatically
 reduce the number of bugs in shipping code.
-But it isn't a panacea, a code coverage analyzer won't help with:)
+But it isn't a panacea, a code coverage analyzer won't help (unlike Valgrind or the sanitizers available in GCC and LLVM) with:)
 
 $(OL
 $(LI Identifying race conditions.)
@@ -51,18 +53,18 @@ $(LI Verifying that the program got the correct result.)
 
 $(P Code coverage analysers are available for many popular languages,
 but they are often third party products that integrate
-poorly with the compiler, and are often very expensive.
+poorly with the compiler.
 A big problem with third party products is, in order to instrument
-the source code, they must include what is essentially a full blown
+the source code, they must include what is essentially a full-blown
 compiler front end for the same language. Not only is this an expensive
 proposition, it often winds up out of step with the various compiler
 vendors as their implementations change and as they evolve various extensions.
 ($(LINK2 http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html, gcov),
-the Gnu coverage analyzer, is an exception as it is both free
+the Gnu coverage analyzer is an exception as it is both free
 and is integrated into gcc.)
 )
 
-$(P The D code coverage analyser is built in as part of the D compiler.
+$(P The D code coverage analyser is part of the D compiler.
 Therefore, it is always in perfect synchronization with the language
 implementation. It's implemented by establishing a counter for each
 line in each module compiled with the $(DDSUBLINK dmd,switch-cov, $(B -cov)) switch.
@@ -78,7 +80,7 @@ $(P For example, consider the Sieve program:)
 
 import std.stdio;
 
-bool flags[8191];
+bool[8191] flags;
 
 int main()
 {
@@ -124,7 +126,7 @@ $(CONSOLE
        |
        |import std.stdio;
        |
-       |bool flags[8191];
+       |bool[8191] flags;
        |
        |int main()
        |{
@@ -163,13 +165,13 @@ as the execution count.
 At the end of the .lst file, the percent coverage is given.
 )
 
-$(P There are 3 lines with an exection count
+$(P There are 3 lines with an execution count
 of 1, these were each executed once. The declaration line for $(D i, prime),
 etc., has 5 because there are 5 declarations, and the initialization of
 each declaration counts as one statement.)
 
 $(P The first $(D for) loop shows 22. This is the sum of the 3 parts
-of the for header. If the for header is broken up into 3 lines, the
+of the for-header. If the for-header is broken up into 3 lines, the
 data is similarly divided:)
 
 $(CONSOLE
@@ -263,7 +265,7 @@ sieve --DRT-covopt="merge:1 dstpath:reports"
 
 $(H3 References)
 
-$(LINK2 https://en.wikipedia.org/wiki/Code_coverage, Wikipedia)
+$(LINK2 https://en.wikipedia.org/wiki/Code_coverage, Wikipedia: "Code Coverage")
 
 )
 

articles/variadic-function-templates.dd

@@ -124,33 +124,32 @@ $(H2 $(LNAME2 d-solutions, D Programming Language Solutions))
 
 $(H3 The D Look Ma No Templates Solution)
 
-        $(P It is not practical to solve this problem in C++ without
-        using templates. In D, one can because D supports typesafe
-        variadic function parameters.
+        $(P The current best practice, e.g. as espoused by the standard library, favours
+        the variadic template solution. However, if the template solution is not practical, D provides a runtime solution
+        utilizing the $(D TypeInfo) system (An example is shown below). There is a lexical similarity with the
+        non-template variadic functions provided by C and C++ ($(D va_list)), however the solution D provides is
+        typesafe whereas the aforementioned alternative is not.
         )
 
 ------
 import core.vararg;
 import core.stdc.stdio;
-import std.format;
-
+/*
+This function was part of D1.0, but does not exist anymore, it has been
+resurrected here to give a realistic example of how this feature could be used.
+*/
+void doFormat(void delegate(dchar) putc, TypeInfo[] arguments, va_list argptr);
 void print(...)
 {
     void putc(dchar c)
     {
         fputc(c, stdout);
     }
 
-    std.format.doFormat(&putc, _arguments, _argptr);
+    doFormat(&putc, _arguments, _argptr);
 }
 ------
 
-        $(P It isn't elegant or the most efficient,
-        but it does work. However it is not the recommended way to write variadic functions.
-        (It relies on the parameters `_argptr` and `_arguments` imported from `core.vararg`
-        which give a pointer to the values and their types, respectively.)
-        )
-
 $(H3 Translating the Variadic C++ Solution into D)
 
         $(P Variadic templates in D enable a straightforward translation
@@ -195,7 +194,7 @@ $(H3 The Static If Solution)
 
         $(P It would be nice to encapsulate all the logic into a
         single function. One way to do that is by using
-        $D(static if)s, which provide for conditional compilation:
+        $(D static if)s, which provide for conditional compilation:
         )
 
 ---

changelog/2.096.0.dd

@@ -22,7 +22,7 @@ $(LI $(RELATIVE_LINK2 dtoh-improvements,Improvements for the C++ header generati
 $(LI $(RELATIVE_LINK2 dwarf-switch,Add `-gdwarf=<version>` switch for the DMD compiler.))
 $(LI $(RELATIVE_LINK2 getVisibility,Introduced `__traits(getVisibility, Sym)` as an alias to `getProtection`))
 $(LI $(RELATIVE_LINK2 runtime-synchronized,Plain `synchronized` statements now use run-time allocated mutexes.))
-$(LI $(RELATIVE_LINK2 shortfunctions,Allow shortened function implementations for single-expresssion functions.))
+$(LI $(RELATIVE_LINK2 shortfunctions,Allow shortened function implementations for single-expression functions.))
 
 )
 
@@ -375,7 +375,7 @@ $(BUGSTITLE_BUGZILLA DMD Compiler regression fixes,
 
 $(LI $(BUGZILLA 20661): opEquals not recognized for AA key $(LPAREN)take two$(RPAREN))
 $(LI $(BUGZILLA 21319): DMD crashes on immutable circular reference)
-$(LI $(BUGZILLA 21547): Oder of constructor declaration affects struct initializer)
+$(LI $(BUGZILLA 21547): Order of constructor declaration affects struct initializer)
 $(LI $(BUGZILLA 21678): "_d_arraysetlengthT is not callable using argument types" on chained array length assignment)
 $(LI $(BUGZILLA 21696): DMD 2.095.1 Compilation Crash)
 )

comparison.dd

@@ -67,7 +67,7 @@ $(ITEMIZE
                 $(A spec/template-mixin.html, Mixins),
                 $(A spec/version.html#staticif, static if),
                 $(A spec/expression.html#IsExpression, expressions),
-                $(A spec/declaration.html#Typeof, typeof),
+                $(A spec/type.html#Typeof, typeof),
                 $(A spec/statement.html#ForeachStatement, foreach),
                 $(A spec/declaration.html#AutoDeclaration, Implicit Type Inference)
         ),

deprecate.dd

@@ -18,7 +18,7 @@ $(SPEC_S Deprecated Features,
         $(TROW $(DEPLINK Using the result of a comma expression),                 2.072,  2.072,  2.079,  )
         $(TROW $(DEPLINK delete),                                                  , 2.079,  ,  )
         $(TROW $(DEPLINK scope as a type constraint),                              , 2.087,  ,  )
-        $(TROW $(DEPLINK Imaginary and complex types),                            future,  ,  ,  )
+        $(TROW $(DEPLINK Imaginary and complex types),                            future, 2.097,  ,  )
         $(TROW $(DEPLINK Implicit catch statement),                               2.072, 2.072,  2.081,   )
         $(TROW $(DEPLINK .sort and .reverse properties for arrays),               ?,     2.072,   , 2.075)
         $(TROW $(DEPLINK C-style array pointers),                                 ?,     2.072,  2.082,  )

foundation/sponsors.dd

@@ -52,31 +52,36 @@ $(LINK2 mailto:social@dlang.org, social@dlang.org). We're eager to add you to it
 )
 
 $(UL
-    $(LI Andrei Alexandrescu)
-    $(LI Etienne Cimon)
+    $(LI Vijay Nayar)
+    $(LI George Toutoungis)
     $(LI John Hall)
     $(LI Gerhardus Jansen)
     $(LI Radu Racariu)
-    $(LI Vijay Nayar)
-    $(LI George Toutoungis)
     $(LI Bastiaan Veelo)
+    $(LI Jared Hanson)
+    $(LI C. Piker)
     $(LI Sepany)
+    $(LI JR)
     $(LI Ali Çehreli)
     $(LI Longinus Ulyanovsky)
     $(LI Jack Applegame)
     $(LI Emil Nicolaie Perhinschi)
-    $(LI JR)
+    $(LI Alex Semenikhine)
     $(LI Georges Robert)
-    $(LI C. Piker)
+    $(LI Ross Lonstein)
     $(LI D. Gilliland)
     $(LI Alexander Bothe)
     $(LI Unity Technologies ApS)
-    $(LI Jared Hanson)
     $(LI Zhang Zongren)
     $(LI Dag)
+    $(LI Jeffrey Buhr)
+    $(LI Matthew Strawbridge)
     $(LI Paul)
-    $(LI Alex Semenikhine)
+    $(LI Andrii Bazylevych)
+    $(LI Aaron Disibio)
     $(LI Sebastian Wilzbach)
+    $(LI Andrei Alexandrescu)
+    $(LI Etienne Cimon)
 )
 )
 

glossary.dd

@@ -56,7 +56,7 @@ $(DL
         $(DD Refers to the ability to instantiate a template function
     without having to explicitly pass in the types to the template.
     Instead, the types are inferred automatically from the types of the
-    runtime arguments.)
+    runtime arguments. See $(LINK2 spec/template.html#ifti, spec) for details.)
 
         $(DT Illegal)
         $(DD A code construct is illegal if it does not conform to the

index.dd

@@ -103,16 +103,16 @@ $(EXTRA_EXAMPLE_RUNNABLE Sort an Array at Compile-Time,
 ----
 void main()
 {
-    import std.algorithm, std.conv, std.stdio;
+    import std.algorithm, std.stdio;
 
     "Starting program".writeln;
 
-    // Sort a constant declaration at Compile-Time
     enum a = [ 3, 1, 2, 4, 0 ];
+    // Sort data at compile-time
     static immutable b = sort(a);
 
     // Print the result _during_ compilation
-    pragma(msg, text("Finished compilation: ", b));
+    pragma(msg, "Finished compilation: ", b);
 }
 ----
 )

spec/abi.dd

@@ -284,6 +284,7 @@ $(GNAME Value):
     $(GLINK CharWidth) $(GLINK Number) $(B _) $(GLINK HexDigits)
     $(B A) $(GLINK Number) $(GLINK Value)...
     $(B S) $(GLINK Number) $(GLINK Value)...
+    $(B f) $(GLINK MangledName)
 
 $(GNAME HexFloat):
     $(B NAN)

spec/arrays.dd

@@ -666,14 +666,15 @@ array.length = i;
 ---------
 )
 
-        $(P Picking a good initial guess is an art, but you usually can
-        pick a value covering 99% of the cases.
+        $(P Base selection of the initial size on expected common
+        use cases, which can be determined by instrumenting the code,
+        or simply using good judgement.
         For example, when gathering user
         input from the console - it's unlikely to be longer than 80.
         )
 
-        $(P Also, you may wish to utilize the $(D reserve)
-        function to pre-allocate array data to use with the append operator.)
+        $(P The $(D reserve)
+        function expands an array's capacity for use by the append operator.)
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ---------