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 (http://dlang.org/phobos/std_container.html#.DList):

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.

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 relevant page (http://dlang.org/phobos/std_container.html#.DList):
[...]

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

-- 
Не дорог подарок, дорога любовь.

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.

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

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...