[geos-devel] c api feedback

[Charlie Savage]

For what its worth, now that I've gone through the c api for the SWIG 
bindings, here is some feedback:

1.  The methods GEOSCoordSeq_getSize and GEOSCoordSeq_getDimensions 
return their results by updating a pointer to a size_t parameter.  Thus 
like this:

GEOSCoordSeq_getSize(const GEOSCoordSeq s, size_t *size);

In contrast, these methods just return the result:

GEOSGeom_getDimensions returns value, not as a parameter
GEOSGeom_getNumcoordinates
GEOSGeom_getNumInteriorRings
GEOSGeom_getNumGeometries

Seems like an unneeded inconsistency.

2.  The coordinate sequence api is extremely awkward to use.  Its 
verbose and results in fairly unreadable code.  Like this:

     cs = Geos::CoordinateSequence.new(4,3)
     cs.set_x(0, 7)
     cs.set_y(0, 8)
     cs.set_z(0, 9)
     cs.set_x(1, 3)
     cs.set_y(1, 3)
     cs.set_z(1, 3)
     cs.set_x(2, 11)
     cs.set_y(2, 15.2)
     cs.set_z(2, 2)
     cs.set_x(3, 7)
     cs.set_y(3, 8)
     cs.set_z(3, 9)

This all seems fairly unecessary since coordinate sequences only support 
x/y/z.  Would be a lot nicer to do this:

     cs.add(7,8,9)
     cs.add(3,3,3)
     cs.add(11,15.2,2)
     cs.add(7,8,9)

Isn't that much clearer?  I believe the api is setup the way it is to 
allow more dimensions in the future.  Is this a case of YAGNI 
(http://en.wikipedia.org/wiki/YAGNI)?

Could we please expose a simplified for coordinate sequences in the c 
api?  Such as an "add" method, and while we are at it, shouldn't there 
also be a remove method?


3.  A lot of methods, like GEOSDisjoint, return a char.  The char is 0 
for false, 1 for true and 2 for an exception.  I took that to mean '0', 
'1', '2'.  In fact its not, its like this:

(char)1

Thus if you look at the char is actually '%' (or some such thing).  You 
of course need to get the int result back by a typecast

result = (int)GEOSDisjoint

Maybe this could be better documented?


4.  Buffer operation now takes quadrant segments.  I had no idea what 
that should be...hunting through the code it turns out to default to 8. 
  Do people use the quadrant parameter much?  Seems like an unneeded bit 
of complexity.  At a minimum, can the default value be exposed as a 
constant?  That way the SWIG bindings can set a default value for the 
buffer operation so users can just do geom.buffer(10) and can specify 
the second parameter only if needed.


5.  Two operations that used to be exposed via SWIG are no longer:

within_distance
equal_exact


6.  Not very important, but the shape factory is not exposed via the c 
api.  Not sure if anyone uses it - its used in example.cpp.

7. The envelopes is not exposed.  I find that one quite useful when 
dealing with bounding boxes - easier than having to work with a polygon 
that represents a bounding box.

Anyway, hope these comments are helpful.


Thanks,

Charlie
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3237 bytes
Desc: S/MIME Cryptographic Signature
Url : http://lists.osgeo.org/pipermail/geos-devel/attachments/20060712/e4baa432/smime.bin