API design, want your opinion

[Jose]

Hi. Sorry if this is copy/pasted from somewhere else but I
want the more valuable opinions possible.
I want to get the best possible API, though it might seem
just a detail...

Of the 2 APIs bellow what do you guys think would be the
more consistent for saving/serializing dynamically allocated
arrays.

Code: [Select]


struct SomeSt
{ int a;
  int b;
  float c;
  ...
  BOOL Last; /* Last element ? Could be other data, 0 will
terminate the array */
} *MaArr; /* Dynamically allocated array */


/* Now the definition with the data one wants to save.
Usable any time after it's made, with calls to serialization
library API save functions. This code example saves the
elements a and c for each SomeSt element of MaArr */
SVDEF (DefinitionName, ST3(SomeSt, a, c, TRM(Last))); /* TRM
signals the terminator when a def is to be used with zero
terminated arrays. (This def can still be used to save
single elements too, in wich case TRM is ignored) */


.....
...
/* Possible APIs. ARR0 signals the dynamically allocated
array's size is to be calculated by checking for 0
termination */
/* API 1 */
Srlz(MaArr, ARR0(DefinitionName));

/* API 2.  */
svARR0 (MaArr, DefinitionName);


In API1 the Srlz function is the general API. To use it with
arrays we add ARR0 to specify the definition, otherwise
(using the definition alone) it would save only the 1st
element.
In API2 I still intend to use Srlz() as the general API for
non array stuff,  but since we have to specify ARRO anyway
for zero terminated arrays one could just make a macro
called svARR0 and spare some syntax.
API1 is more consistent. API2 has shorter syntax ....

Nitpicking I know, but want to know wich way fits you
better.

Cheers

[Jose]

"Is the point the ability to pass an array of arbitrary structs to your API and have it know how to serialize that array in a way specific to the struct?"

Absolutely!:) That's exactly the point. The structure used as the base type for the array is just an example of data.
The doubt is if I should make various macros for each special case or keep a general function, wich will of course need some extra indications.

BTW, I'm passed this doubt for some days now. I'll present the final API for discussion when I finish the library, if anyone finds it usefull that is:) (I think you will).

:pint: