http://d.puremagic.com/issues/show_bug.cgi?id=4551

           Summary: D2 Language Docs:
                    http://www.digitalmars.com/d/2.0/arrays.html
           Product: D
           Version: D2
          Platform: Other
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: www.digitalmars.com
        AssignedTo: nobody@puremagic.com
        ReportedBy: andrej.mitrovich@gmail.com


--- Comment #0 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2010-08-01 09:23:10 PDT ---
"Usage"

In the code example, the lines:

p = s;        // p points to the first element of the array s. p = a;        // p points to the first element of the array a.

Give compiler errors:

Error: cannot implicitly convert expression (s) of
type int[3u] to int*
Error: cannot implicitly convert expression (a) of
type int[] to int*

These should probably be replaced with:

p = &s[0];        // p points to the first element of the array s. p = &a[0];        // p points to the first element of the array a.



"Array Properties"

In the first code example there are missing declarations. Add these before the first line:

int* p;
int[3] s;
int[] a;



"Setting Dynamic Array Length"

From the comments in the first example, it states:
    ''// always resized in place because it is sliced
      // from a[] which has enough memory for 15 chars''

But I am not seeing this behavior. I've added two asserts, showing that manipulating the contents of b[] after it was resized does not affect a[] or c[]:

void main() {
    char[] a = new char[20];
    char[] b = a[0..10];
    char[] c = a[10..20];

    b.length = 15;    // always resized in place because it is sliced
                      // from a[] which has enough memory for 15 chars
    b[11] = 'x';

    assert(b[11] != a[11]);     // a[11] is not affected
    assert(b[11] != c[1]);      // c[1] is not affected
}



"Functions as Array Properties"

The body of foo() in the example code is not defined and we get the usual
linker nonsense.
Replace the example code with the following:

void foo(int[] a, int x) { };

void main() {
    int[] array;
    foo(array, 3);
    array.foo(3);    // means the same thing
}



"Array Bounds Checking"

In the example code, "ArrayBoundsError" should be replaced with "RangeError"



"Static Initialization of Static Arrays"

The documentation states:
"These arrays are static when they appear in global scope. Otherwise, they need
to be marked with const or static storage classes to make them static arrays."

In non-global scope, I can only compile if the array is marked with static or static const.

const alone will not compile for me:

enum Color { red, blue, green };

void main() {
    const int value[Color.max + 1] = [ Color.blue:6, Color.green:2, Color.red:5
];
}

test2.d(192): Error: Integer constant expression expected instead of Color.blue
test2.d(192): Error: Integer constant expression expected instead of
Color.green
test2.d(192): Error: Integer constant expression expected instead of Color.red
test2.d(192): Error: Integer constant expression expected instead of Color.blue
test2.d(192): Error: Integer constant expression expected instead of
Color.green
test2.d(192): Error: Integer constant expression expected instead of Color.red



"Special Array Types"

The 6th code example from the title:
    cast(wchar [])"abc"    // this is an array of wchar characters
    "abc"w              // so is this

There's a difference. The first is a mutable wchar[] type, while the second is immutable(wchar)[] type.

The next example has this line:
    w = \r[0];        // w is assigned the carriage return wchar character

Which errors out:
test2.d(200): Escape String literal \r is deprecated, use double quoted string
literal "\r" instead

Replace that line with:
w = "\r"[0];    // w is assigned the carriage return wchar character



"Using Classes as the KeyType"
The example code mixes "f" and "foo", there is only an "f" identifier so
it doesn't compile.

But I would replace f with foo anyways, since it makes the example more
readable.
The compilable code is then:

class Foo
{
    int a, b;

    hash_t toHash() { return a + b; }

    bool opEquals(Object o)
    {
        Foo foo = cast(Foo) o;
        return foo && a == foo.a && b == foo.b;
    }

    int opCmp(Object o)
    {
        Foo foo = cast(Foo) o;
        if (!foo)
            return -1;
        if (a == foo.a)
            return b - foo.b;
        return a - foo.a;
    }
}



"Using Structs or Unions as the KeyType"

This line in the code example:
foreach (char c; s)

Should be replaced with:
foreach (char c; str)

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551


Steven Schveighoffer <schveiguy@yahoo.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |schveiguy@yahoo.com


--- Comment #1 from Steven Schveighoffer <schveiguy@yahoo.com> 2010-08-05 15:43:28 PDT ---
changeset http://www.dsource.org/projects/phobos/changeset/1810

Note, I left a few things unfixed that you pointed out:

(In reply to comment #0)
> "Usage"
> 
> In the code example, the lines:
> 
> p = s;        // p points to the first element of the array s. p = a;        // p points to the first element of the array a.
> 
> Give compiler errors:
> 
> Error: cannot implicitly convert expression (s) of
> type int[3u] to int*
> Error: cannot implicitly convert expression (a) of
> type int[] to int*
> 
> These should probably be replaced with:
> 
> p = &s[0];        // p points to the first element of the array s. p = &a[0];        // p points to the first element of the array a.

Don already fixed these

> "Functions as Array Properties"
> 
> The body of foo() in the example code is not defined and we get the usual
> linker nonsense.
> Replace the example code with the following:
> 
> void foo(int[] a, int x) { };
> 
> void main() {
>     int[] array;
>     foo(array, 3);
>     array.foo(3);    // means the same thing
> }

The example isn't meant to be a complete program.  Prototypes without implementation are allowed as long as you define the function later.  Yes, there is no point in defining a D prototype since the function must be defined in the module itself, but essentially, the implementation of foo isn't of importance here, just the fact you can call it that way.

> "Static Initialization of Static Arrays"
> 
> The documentation states:
> "These arrays are static when they appear in global scope. Otherwise, they need
> to be marked with const or static storage classes to make them static arrays."
> 
> In non-global scope, I can only compile if the array is marked with static or static const.
> 
> const alone will not compile for me:
> 
> enum Color { red, blue, green };
> 
> void main() {
>     const int value[Color.max + 1] = [ Color.blue:6, Color.green:2, Color.red:5
> ];
> }
> 
> test2.d(192): Error: Integer constant expression expected instead of Color.blue
> test2.d(192): Error: Integer constant expression expected instead of
> Color.green
> test2.d(192): Error: Integer constant expression expected instead of Color.red
> test2.d(192): Error: Integer constant expression expected instead of Color.blue
> test2.d(192): Error: Integer constant expression expected instead of
> Color.green
> test2.d(192): Error: Integer constant expression expected instead of Color.red

I'm not sure what was meant here by Walter.  I suspect that "Static array" should be changed to "fixed sized array" everywhere, but that's a huge change, that I'm not comfortable making.  I think the text is meant to say that in order to make an array a "static variable" (i.e. keeps its value across function calls) you have to apply the static attribute.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551



--- Comment #2 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2010-08-05 15:57:04 PDT ---
Thanks for the review, Steven.

I see what you mean by "doesn't have to be a complete program". But this should be stated somewhere. In many cases trying to compile these incomplete examples will not give out any sensible error message, primarily because of the unfriendly linker (which, as Andrei stated, likes to write error messages in it's own language - Klingon).

I'm sure there will be plenty of newbies trying out the examples and getting that WTF moment when they get the errors back. So either the examples have to be full, or the docs should have a visible statement where it states that these code fragments are only showcase examples, and can't be compiled in their current state. Would that be fair?

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551



--- Comment #3 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2010-08-05 16:02:38 PDT ---
And thanks for the fixes + the anchors. I was going to mention that some pages are missing a lot of anchors (which is why I wrapped everything with double quotes instead).

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551



--- Comment #4 from Steven Schveighoffer <schveiguy@yahoo.com> 2010-08-05 17:02:22 PDT ---
I'll defer to Walter on the prototype vs full implementation since the example is valid either way IMO.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551


Denis Derman <denis.spir@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |denis.spir@gmail.com


--- Comment #5 from Denis Derman <denis.spir@gmail.com> 2011-01-28 06:30:00 PST ---
(In reply to comment #1)

> > "Static Initialization of Static Arrays"
> > 
> > The documentation states:
> > "These arrays are static when they appear in global scope. Otherwise, they need
> > to be marked with const or static storage classes to make them static arrays."
> > 
> > In non-global scope, I can only compile if the array is marked with static or static const.
> > 
> > const alone will not compile for me:
> > 
> > enum Color { red, blue, green };
> > 
> > void main() {
> >     const int value[Color.max + 1] = [ Color.blue:6, Color.green:2, Color.red:5
> > ];
> > }
> > 
> > test2.d(192): Error: Integer constant expression expected instead of Color.blue
> > test2.d(192): Error: Integer constant expression expected instead of
> > Color.green
> > test2.d(192): Error: Integer constant expression expected instead of Color.red
> > test2.d(192): Error: Integer constant expression expected instead of Color.blue
> > test2.d(192): Error: Integer constant expression expected instead of
> > Color.green
> > test2.d(192): Error: Integer constant expression expected instead of Color.red
> 
> I'm not sure what was meant here by Walter.  I suspect that "Static array" should be changed to "fixed sized array" everywhere, but that's a huge change, that I'm not comfortable making.  I think the text is meant to say that in order to make an array a "static variable" (i.e. keeps its value across function calls) you have to apply the static attribute.

Actually, what is "static" (in the D sense of predefined, knwon at
compile-time), is the *size*, and only the size. So, the proper (again using
D's sense of "static") term could be "static-size array".

Note that in english "static" and "dynamic" 's first senses are "that cannot change" and "that can change". This is really not what those words mean in D and similar languages. "static" and "dynamic" are used in D to mean what in math is called "constant" (predefined) and "variable" (defined at application time). Lol!

Denis

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4551


Andrej Mitrovic <andrej.mitrovich@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED


--- Comment #6 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2012-04-05 19:36:21 PDT ---
These issues are resolved.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------