Built-in arrays as output ranges

[Andrei Alexandrescu]

Steve Teale wrote:
> Not a bug, but would it be reasonable to expand a little on the documentation for an output range, perhaps along the lines:
> 
> r.put(e) puts e in the range (in a range-dependent manner) and advances to the popFront position in the range. Successive calls to r.put add elements to the range. put may throw to signal failure.
> 
> When using a built-in array as an output range, to do anything useful it is necessary to take a reference to the original array before using put. The original array will be nibbled away by put operations (see std.array). For example:
> 
>     int[] a = [ 1,2,3 ];
>     int[] b = a;
>     a.put(-a[0]);
>     a.put(-a[0]);
>     writefln("([%s] [%s]", b, a);
>    // [ -1, -2, 3] [ 3 ]

Right. Speaking of which, I think it's sensible to always leave the test
for empty range in, even in release unsafe builds.

void put(T, E)(ref T[] range, E element) if (!isSomeString!(T[]))
{
     enforce(!range.empty, "Attempting to put in an empty array");
     *range.ptr = element;
     range.popFront();
}

enforce() will never be disabled.

As an aside, I just realized I haven't implemented put for strings yet,
and also that I'd promised a check in this weekend.


Andrei