Corefxlab: Binary Write/Put/Poke/Set and Read/Peek/Get

[KrzysztofCwalina]

cc: @ahsonkhan, @stephentoub, @davidfowl, @weshaggard, @terrajobst, @joshfree, @AtsushiKan, @pakrym, @anurse, @GrabYourPitchforks, @ianhays, @bartonjs, @benaadams

Today, Binary class has methods named Read/Write, e.g.
c# span.WriteInt32(value); value = span.ReadInt32();

During the API review people commented that the names imply that there is some index being advanced when the methods are called, i.e. subsequent calls to Read would read subsequent values.

Here are some alternative names we would like to explore. Please vote for the proposals, or add your own:

[KrzysztofCwalina]

c# // the current API; has the problem that some people thing Write/Read advances a writer/reader span.WriteInt32(value); value = span.ReadInt32();

[KrzysztofCwalina]

c# // Z81 nostalgia API span.PokeInt32(value); value = span.PeekInt32();

[KrzysztofCwalina]

c# // is Set replacing the whole span? span.SetInt32(value); value = span.GetInt32();

[KrzysztofCwalina]

c# span.PutInt32(value); value = span.GetInt32();

[anurse]

Agreed with the name confusion on Write. I think I would lean towards Set (I'm not too worried about the confusion around replacing the whole span, it's got "32" right in the name so I'd assume it would fill the first 32 bits only) or Put. I'd love to have Poke but I think other than the nostalgia, it's not a very approachable name :)

[benaadams]

Set (or Put)

However, this should definitely exist 😉

namespace Microsoft.VisualBasic
{
    public static class SpanExtensions
    {
        public static void Poke<T>(this Span<byte> buffer, T value) => buffer.Set(value);
    }
}

[KrzysztofCwalina]

Well, we chose the boring old Read/Write :-)

[benaadams]

But you know it makes sense for the VB namespace... 😉

https://en.wikipedia.org/wiki/PEEK_and_POKE

These commands are particularly associated with the BASIC programming language

[KrzysztofCwalina]

good idea for my April 1st PR