Re: API Design

[tobias@...]

Quoting tobias@justdreams.de:

> 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:

Here is what I ended up implementing:

 b = Buffer( 1024 )        -- buffer with 124 bytes
 s = b:Segment()           -- Segment covering entire buffer
 s = b:Segment( 256 )      -- Segment starting @256 covering to end of buffer
 s = b:Segment( 256, 128 ) -- Segment starting @256 covering 128bytes  
of buffer
 s.buffer                  -- Buffer instance Segment refers to (immutable)
 s.size                    -- Length of Segment, same as #s but mutable
 s.start                   -- First byte of Segment in regards to  
Buffer; mutable
 s.to                      -- First byte that's NOT in Segment;  
muatble. That's
                              in line with string.sub() or Pythons slicing
 s[ 34 ]                   -- byte value of 34th byte in Segment; mutable

Thanks for your input.

-Tobias