Re: API Design

[Frank Kastenholz <fkastenholz@...>]

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

> On Sep 18, 2017, at 2:18 PM, tobias@justdreams.de wrote:
> 
> 
> Hi there,
> 
> I'm designing a library which has a Buffer module that allows to contain binary data.  Think of it as a string just with less features :-P ... except it is mutable.  Now I'm writing a companion module called Buffer.Segment that allows access to just a limited part of the buffer which is defined by an offset and a length.  I'd plan the API look like this:
> 
> b  = Buffer( 1024 )      -- buffer with 124 bytes
> s  = Segment( b )        -- creates a segment starting at the first byte of the buffer as long as the buffer itself
> s1 = Segment( 128, 256 ) -- Segment with 128 byte offset and 256 bytes length
> s2 = Segment( 439 )      -- this is the question, shall this be:
> 
>                    - a segment starting at byte 439 and have a length to the end of the buffer, or
>                    - a segment starting at first byte being 439 bytes long
> 
> I don't think there is a 'right' answer, but to all those people who work with this kind of stuff, what would feel more natural to you?
> Also, does Segment( offset, length ) makes more sense than Segment( length, offset ) ?
> 
> Thanks for the input,
> 
> - Tobias
> 
>