Re: API Design

[Frank Kastenholz <fkastenholz@...>]

On 9/18/17 6:34 PM, tobias@justdreams.de wrote:
> Quoting Frank Kastenholz <fkastenholz@verizon.net>:
>
> > Hi
> >
> > Xxxx(start, Len)
> > Or
> > Xxxx(start, end)
> >
> > Are what I personally like
> >
> > Or subscripts ala buffer[start,end] :-)
> >
> > More important than that are, imho, some higher level issues like
> > Consistency --- do it the same everywhere (as opposed to memcpy vs
> > strcpy; one is source, dest and the other is dest,src.... grrrr)
> >
> > Also keep it intuitive ... e.g., most people will the 1st arg is
> > always the start, so don't have the normal mode be xxxx(start,len)
> > and then have a 1-argument variant of xxxx(len) with the buffer start
> > being an implied 1st argument.
> >
> > And .. having implied additional optional arguments is something I've
> > discouraged in the past.  Typing the additional arguments is no problem
> > It stresses the "do you really want xxx for argument n?" In the
> > programmers mind .... as well as the "we really mean xxxx!" In the
> > mind of the next programmer to read the code
> >
> > Frank
>
> That raises an interesting question.  Currently I have a couple of
> ways to create a Buffer( not the segment ), and they are inconsistent:
>
> b  = Buffer( 1024 ) -- empty Buffer with 1024 bytes
> s  = 'This is some example content'
> b1 = Buffer( s )    -- buffer filled with s, #b1 == #s
> b2 = Buffer( b1 )   -- buffer filled with content of b1; #b1 == #b2
>                     -- this is a true clone, not a reference
> sg = b1:Segment( 1, 5) -- Segment[1:5]; #sg == 5
> b3 = Buffer( sg )   -- buffer with content of sg, #b3 == #sg
>                     -- true clone of content
I do not see a problem with these -- they all do the same thing (create
a new buffer) and use something else to initialize it. it is sort of
the difference between using floats or integers for your "b=Buffer(1024)"
call.
> b4 = Buffer(14, b1) -- buffer with first 14 bytes from b1
Normally I'd say that since you can do this the same as your b3
example, it doesn't deserve a special case or form of API.
On the other hand, I can imagine your buffers might get very
big -- so you could optimize the segmenting and subsetting of
the buffer, saving some copies, etc, that might not otherwise
be needed.

As a meta-(meta-point) I allow myself to break my own "rules"
if I've given the matter a lot of thought and there is a
really really good reason/benefit to do so.

On the other hand, I may just be trying to rationalize my own
irrational behavior.


Frank