[pdal] questions about iterator and buffer semantics

[Mateusz Loskot]

On 4 July 2013 10:47, Chris Foster <chris.foster at roames.com.au> wrote:
> On 4 July 2013 18:44, Mateusz Loskot <mateusz at loskot.net> wrote:
>>> We do need some version getDimensionXXX() which signifies the absence of the
>>> dimension in some other way than throwing.  Whether that's by returning
>>> boost::optional, or by returning a pointer doesn't matter too much in the
>>> grand scheme of things, I'm just picky when it comes to API design ;-)
>>
>> The getDimension could be simply overloaded:
>>
>> #include <new>
>> #if (__cplusplus >= 201103L)
>>     #define PDAL_NO_THROW nothrow
>> #else
>>     #define PDAL_NO_THROW throw()
>> #endif
>>
>> void getDimension() { throw ""; }
>> bool getDimension(std::nothrow_t const&) PDAL_NO_THROW { return false; }
>
> Careful - the second getDimension can still throw (it is currently necessary
> to call operator new behind the scenes for the dimension inheritance stuff).

I assumed the second implementation will guarantee the semantic
indicated by the signature.

>> Then, uesr can explicitly state which one she prefers:
>>
>> try {
>>    getDimension();
>> } catch (...) {}
>>
>> if (!getDimension(std::nothrow))
>>    ...
>
> IMO this is cute, but too cute ;-)  These functions have different return
> types (different semantics on failure to find the dimension!), so it's
> entirely appropriate to have different names.

It's just a a minimal example to illustrate the idea, it surely is not complete.
For example, both versions can return pointer, this makes interface
consistent and easier to use i.e. at compile-time, than separate name
as it only differes by parameter.

> I think this is a case where it's best to keep things simple, because the
> simplest thing will work fine and be easy to understand when you come back to
> read the code. I've designed some really fancy APIs in the past, bristling
> with neat user defined types and clever overloads... looking back on them they
> are not APIs I would now like to use!

Simple is very relative.

T* get();
T* get(argument);

is not fancy, is very simple, if not simplest interface capturing
diversity that one can imagine.
Separate names just to capture some low-level elemennt is first step
to the fancy zoo :)

Nobody would like to call

std::sort_with_random_iterator()
std::sort_with_input_iterator()
std::sort_with_forward_iterator()

Certainly, the discussion about error_code is just an example in case
there are more
requirements regarding the function semantic. I'm not suggesting PDAL
should go for that,
but alternatives are worth to consider especially if they are apparent
and available, IMHO.

Best regards,
--
Mateusz  Loskot, http://mateusz.loskot.net