Questions about API Design, composability and multiple arguments

Hi All,

Hoping this is the right group to be asking about this, if not please do 
point in the right direction.

Here's a snipped example interface for a basic store:

interface Store {
     readonly attribute unsigned long length;

     T              get (in unsigned long index);
     void           add (in T t);
     void           merge(in Store store);
     sequence<T>    toArray();

     Store          filter (in TFilter filter);
     void           forEach (in TCallback callback);

};


(1) Adding multiple items
What's the best approach to allow adding multiple items?

- add(in T[] t)
would this allow a single T not in an array to be passed in?
can one define a function with WebIDL so that it accepts either a single 
item of type T or an array of T?

- add(in T... t)
is the variadic approach better?
also if at least one argument is required would the IDL have to be:
   add(in T t, in T... ts) ?

- addAll(??)
Would it be preferable to introduce an addAll function?
If so, then the above two approaches also apply here, which one?

Also you'll note the toArray() method, if the advice above is to the 
above is to take the variadic approach, then how should one address 
importing an array - and further would the appropriate type for such an 
argument be sequence<T> or T[]? `addArray (in ?? t)`


(2) Chaining by return
Should the method add(in T t) return Store, the current store to which 
the T has just been added so as to allow chaining as such:
    store.add(t1).add(t2).add(t3)

Likewise the same question can be asked about merge()? - however this 
adds in a twist because filter() will not modify the contents of the 
store and return a new Store (it acts like Store is immutable), whereas 
merge would modify the contents of the store and then return itself.

Likewise again with forEach?


(3) merge()
Where merge(in Store store) is a method which adds non duplicated 
members of the store passed in to the current store, would this be 
better named 'import' or something else?
Would it be wise to add a counterpart method which treated the store as 
immutable returning a new store (as filter does)?


(4) counterpart methods
Finally, just a quick one, is it worth considering adding counterpart 
methods for composability, as in given we have Store.add(T t) would it 
also be wise to include a method T.addTo(Store store) - and if so should 
it return the instance of T or the Store with t added?


Best & TIA,

Nathan

Received on Saturday, 30 October 2010 22:58:24 UTC