Types in a public c++ API

Question

I'm writing a library and wonder what's the best practise for datatypes used in a public API.

Given the funtion

void foo (int bar)

which expects an index to some internal array/container. What type should that be? Because an index can never be negative I could use unsigned int or size_t. Or should I stick with a plain int and assert / throw if some invalid value is provided?

In general: Should I choose a type based on the valid data range (e.g. to avoid negative checks) or not?

EDIT: another example, suppose my library provides a function for printing a file. The user can choose the range of pages to be printed:

void print (int page_from, int page_to)

Answer 1

The best advice here would probably be to go with the existing practice (i.e. what C++ standard libraries do). Broadly speaking, this means at least using an unsigned type here; if you're actually using that type directly as an array/pointer index (and your abstraction is transparent in that regard), then size_t might be called for.

If foo is a member function of some container-like class, then you may also consider typedefing something like size_type on it, and using that.

Answer 2

I vote for using unsigned. Even better, use stdint.h and use something like uint32_t.

Answer 3

If the array/container you are talking about is just a generic abstract application-independent array, then the most appropriate type would be size_t. You can, of course, provide a typedef name for the type in your interface. Again, this is only appropriate when you are working with abstract arrays, like in a generic container library, or a generic sort function etc.

One you get into an application specific area, size_t is no longer the appropriate type. In your application specific area that index would normally have some application-specific semantics not immediately related to arrays. For example, it can be an "employee id" of some sort, or "cell number" or "color index" or something else. In such cases you would normally already have a pre-chosen integer type to represent the corresponding quantity. (And the choice will not normally have anything to do with arrays.) This is exactly the type you should use in your interface.

As for signedness/unsignedness of the type... I for one firmly believe that unsigned quantities should be represented by unsigned types, i.e. a normal array index should be unsigned.