www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 4551] New: D2 Language Docs: http://www.digitalmars.com/d/2.0/arrays.html

reply d-bugmail puremagic.com writes:
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



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: -------
Aug 01 2010
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4551


Steven Schveighoffer <schveiguy yahoo.com> changed:

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



15:43:28 PDT ---
changeset http://www.dsource.org/projects/phobos/changeset/1810

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



 "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: -------
Aug 05 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4551




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: -------
Aug 05 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4551




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: -------
Aug 05 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4551




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: -------
Aug 05 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



---



 "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: -------
Jan 28 2011
prev sibling parent d-bugmail puremagic.com writes:
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



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: -------
Apr 05 2012