Add IO::Delimited

[RX14]

From docs:

An IO that wraps another IO, and only reads up to the beginning of a specified delimiter.

This is useful for exposing part of an underlying stream to a client.

Also adds some convenience methods to Slice that are (or were) utilised in implementing IO::Delimited.

The algorithm for IO::Delimitedis a little complex, but I believe it's readable with the docs and comments I've added. It's also reasonably performant: benchmarks. It seems to be able to do about 1gbps/core, which should be enough for most usages.

[jhass]

Leftover comment :)

[RX14]

Removed!

[asterite]

I don't think silently truncating is good. If there's not enough room it should raise.

Are you using this "feature" in your code?

[RX14]

The point of the API is that it copies the size of the smaller slice, and returns the amount of bytes it copies. I think this API is sane, but i'm not sure, i'm willing to be convinced either way.

[RX14]

And yes, i'm using it here.

[RX14]

From IRC:

 <RX14> i don't want it to throw
 <jhass> but given all the slice stuff raises on bounds related things
 <jhass> it probably should remain a callside responsibility for now
 <RX14> no it raises when you try and ask it to do something stupid explicitly
 <RX14> that doesn't set a precedent for copying to raise if the user hasn't truncated the slices right

[RX14]

I fixed this: It raises when src will not fit into dest, but not when src does not completely fill dest.

[RX14]

Just fixed the style violation, anything else needed before merging?

[asterite]

@RX14 Looks good now.

One last thing: maybe delimiter instead of read_delimiter? I think it's better if we use shorter names.

[RX14]

@asterite well i kinda left it like that in case we ever wanted to add a write version, and the read_size made it into IO::Sized so I would feel compelled to change that if I changed this.

[asterite]

You mean, you'd write until you find a delimiter being written? Well, in any case read_delimiter maybe makes it more explicit than it's for reading, and one can choose not to use the named argument anyway...

[RX14]

@asterite those were my thoughts exactly

[asterite]

@RX14 Thank you!