Merge pull request #2002 from wilzbach/1040-arrays

Revive #1040 - spec/arrays.d
merged-on-behalf-of: Sebastian Wilzbach <sebi.wilzbach@gmail.com>

spec/arrays.dd

@@ -112,6 +112,10 @@ a = s;     // a is initialized to point to the s array
 a = b;     // a points to the same array as b does
 ---------
 
+$(H2 $(LNAME2 indexing, Indexing))
+
+    $(P See also $(GLINK2 expression, IndexExpression).)
+
 $(H2 $(LNAME2 slicing, Slicing))
 
         $(P $(I Slicing) an array means to specify a subarray of it.
@@ -157,6 +161,9 @@ int* p;
 int[] b = p[0..8];
 ---------
 
+    $(P See also $(GLINK2 expression, SliceExpression).)
+
+
 $(H2 $(LNAME2 array-copying, Array Copying))
 
         $(P When the slice operator appears as the left-hand side of an
@@ -576,17 +583,7 @@ assert(cap == array.capacity);
 
 $(H3 $(LNAME2 func-as-property, Functions as Array Properties))
 
-        $(P If the first parameter to a function is an array, the
-        function can be called as if it were a property of the array:
-        )
-
----
-int[] array;
-void foo(int[] a, int x);
-
-foo(array, 3);
-array.foo(3);   // means the same thing
----
+        $(P See $(DDSUBLINK function, pseudo-member, Uniform Function Call Syntax (UFCS)).)
 
 $(H2 $(LNAME2 bounds, Array Bounds Checking))
 
@@ -635,6 +632,28 @@ int x = foo[3]; // error, out of bounds
         with a compile time switch.
         )
 
+        $(P An out of bounds memory access will cause undefined behavior,
+            therefore array bounds check is normally enabled in `@safe` functions.
+            The runtime behavior is part of the language semantics.
+        )
+
+        $(P See also $(DDSUBLINK function, safe-functions, Safe Functions).)
+
+$(H3 $(LNAME2 disable-bounds-check, Disabling Array Bounds Checking))
+
+        $(P Insertion of array bounds checking code at runtime may be
+            turned off with a compiler switch $(LINK2 $(ROOT_DIR)dmd.html#switch-boundscheck, `-boundscheck`).
+        )
+
+        $(P If the bounds check in `@system` or `@trusted` code is disabled,
+            the code correctness must still be guaranteed by the code author.
+        )
+
+        $(P On the other hand, disabling the bounds check in `@safe` code will
+            break the guaranteed memory safety by compiler. It's not recommended
+            unless motivated by speed measurements.
+        )
+
 $(H2 $(LNAME2 array-initialization, Array Initialization))
 
 $(H3 $(LNAME2 default-initialization, Default Initialization))
@@ -820,7 +839,7 @@ $(H4 $(LNAME2 printf, C's printf() and Strings))
 
 ---------
 str ~= "\0";
-printf("the string is '%s'\n", cast(char*)str);
+printf("the string is '%s'\n", str.ptr);
 ---------
 
         or:
@@ -834,15 +853,15 @@ printf("the string is '%s'\n", std.string.toStringz(str));
         can be used directly:)
 
 -----------
-printf("the string is '%s'\n", cast(char*)"string literal");
+printf("the string is '%s'\n", "string literal".ptr);
 -----------
 
         $(P So, why does the first string literal to printf not need
-        the cast? The first parameter is prototyped as a const(char)*, and
-        a string literal can be implicitly cast to a const(char)*.
+        the `.ptr`? The first parameter is prototyped as a `const(char)*`, and
+        a string literal can be implicitly `cast` to a `const(char)*`.
         The rest of the arguments to printf, however, are variadic
         (specified by ...),
-        and a string literal is passed as a (length,pointer) combination
+        and a string literal typed `immutable(char)[]` cannot pass
         to variadic parameters.)
 
         $(P The second way is to use the precision specifier.