www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation of DList in std.container seems to be inaccurate

reply "Koz Ross" <koz.ross runbox.com> writes:
I just spent a good while debugging something which arose as a 
result of the documentation of the DList's removeAny function. 
More precisely, it seems that removeAny removes from the *back*, 
rather than the front, as the documentation would indicate. To 
quote the relevant page 


T removeAny();
alias stableRemoveAny = removeAny;
     Picks one value from the front of the container, removes it 
from the container, and returns it.

     Elements are not actually removed from the chain, but the 
DList's, first/last pointer is advanced.

     Precondition:
     !empty

     Returns:
     The element removed.

     Complexity:
     Ο(1).


To demonstrate this, I give the following code:

import std.container, std.stdio;

DList!size_t foo;
foo.insertBack(1);
foo.insertBack(10);
auto x = foo.removeAny();
writeln(x);

According to the documentation, 1 should be printed. However, 
instead, 10 gets printed. Am I completely insane, or is the 
documentation just inaccurate?

I'm using GDC 4.9.1 for this.
Nov 19 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Nov 19, 2014 at 08:18:55AM +0000, Koz Ross via Digitalmars-d wrote:

 I just spent a good while debugging something which arose as a result
 of the documentation of the DList's removeAny function. More
 precisely, it seems that removeAny removes from the *back*, rather
 than the front, as the documentation would indicate. To quote the



[...]

The documentation was wrong before, but the whole point of removeAny()
is that it removes *any* element from the container, and it's not
specified *which* one is removed. The fact that a particular element
(front or back or whatever) is what happens to be removed from a
specific container, is something that user code should not rely on. The
idea is that you just want *one* element from the container, and it
doesn't matter which, so the container is free to choose the easiest one
to remove. The fact that the documentation then refers specifically to
front or back is a bug; user code was not supposed to rely on this.

I'm pretty sure the PR that fixes this problem has been checked in, but
I'm not sure why dlang.org hasn't been updated yet? Or has it only been
updated in the phobos-prerelease section?


T

-- 
Не дорог подарок, дорога любовь.
Nov 19 2014
parent reply "Meta" <jared771 gmail.com> writes:
On Wednesday, 19 November 2014 at 15:45:34 UTC, H. S. Teoh via 
Digitalmars-d wrote:

 The documentation was wrong before, but the whole point of 
 removeAny()
 is that it removes *any* element from the container, and it's 
 not
 specified *which* one is removed. The fact that a particular 
 element
 (front or back or whatever) is what happens to be removed from a
 specific container, is something that user code should not rely 
 on. The
 idea is that you just want *one* element from the container, 
 and it
 doesn't matter which, so the container is free to choose the 
 easiest one
 to remove. The fact that the documentation then refers 
 specifically to
 front or back is a bug; user code was not supposed to rely on 
 this.

 I'm pretty sure the PR that fixes this problem has been checked 
 in, but
 I'm not sure why dlang.org hasn't been updated yet? Or has it 
 only been
 updated in the phobos-prerelease section?


 T


Phobos-Prerelease also says that it's removed from the front, so 
the documentation may not have been updated.
Nov 19 2014
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Nov 19, 2014 at 10:56:27PM +0000, Meta via Digitalmars-d wrote:

 On Wednesday, 19 November 2014 at 15:45:34 UTC, H. S. Teoh via Digitalmars-d
 wrote:

The documentation was wrong before, but the whole point of
removeAny() is that it removes *any* element from the container, and
it's not specified *which* one is removed. The fact that a particular
element (front or back or whatever) is what happens to be removed
from a specific container, is something that user code should not
rely on. The idea is that you just want *one* element from the
container, and it doesn't matter which, so the container is free to
choose the easiest one to remove. The fact that the documentation
then refers specifically to front or back is a bug; user code was not
supposed to rely on this.

I'm pretty sure the PR that fixes this problem has been checked in,
but I'm not sure why dlang.org hasn't been updated yet? Or has it
only been updated in the phobos-prerelease section?


T


 
 Phobos-Prerelease also says that it's removed from the front, so the
 documentation may not have been updated.


Gah... I just checked the source code, the docs have been fixed there.
Unfortunately, after std.container was recently split into multiple
submodules, the ddoc build scripts were not updated properly, so the
docs you see under phobos-prerelease are actually stale files. :-(

I'll submit a PR for this.


T

-- 
I've been around long enough to have seen an endless parade of magic new
techniques du jour, most of which purport to remove the necessity of
thought about your programming problem.  In the end they wind up
contributing one or two pieces to the collective wisdom, and fade away
in the rearview mirror. -- Walter Bright
Dec 06 2014
prev sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sat, Dec 06, 2014 at 07:58:08AM -0800, H. S. Teoh via Digitalmars-d wrote:

 On Wed, Nov 19, 2014 at 10:56:27PM +0000, Meta via Digitalmars-d wrote:

 On Wednesday, 19 November 2014 at 15:45:34 UTC, H. S. Teoh via Digitalmars-d
 wrote:

The documentation was wrong before, but the whole point of
removeAny() is that it removes *any* element from the container,
and it's not specified *which* one is removed. The fact that a
particular element (front or back or whatever) is what happens to
be removed from a specific container, is something that user code
should not rely on. The idea is that you just want *one* element
from the container, and it doesn't matter which, so the container
is free to choose the easiest one to remove. The fact that the
documentation then refers specifically to front or back is a bug;
user code was not supposed to rely on this.

I'm pretty sure the PR that fixes this problem has been checked in,
but I'm not sure why dlang.org hasn't been updated yet? Or has it
only been updated in the phobos-prerelease section?


T


 
 Phobos-Prerelease also says that it's removed from the front, so the
 documentation may not have been updated.


 
 Gah... I just checked the source code, the docs have been fixed there.
 Unfortunately, after std.container was recently split into multiple
 submodules, the ddoc build scripts were not updated properly, so the
 docs you see under phobos-prerelease are actually stale files. :-(
 
 I'll submit a PR for this.


[...]

https://github.com/D-Programming-Language/phobos/pull/2788


T

-- 
If you want to solve a problem, you need to address its root cause, not just
its symptoms. Otherwise it's like treating cancer with Tylenol...
Dec 06 2014