[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: API Design
- From: Frank Kastenholz <fkastenholz@...>
- Date: Mon, 18 Sep 2017 20:31:53 -0400
On 9/18/17 6:34 PM, firstname.lastname@example.org wrote:
Quoting Frank Kastenholz <email@example.com>:
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
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)"
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
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