API theme discussion

[bemcdonnell]

We’re reaching a point where the API could use some style checks. We have functions that scoop out larger sets of data and functions that pluck single values. The current api is absolutely functional, however, as it begins to grow, we will benefit from a unified vision.

@michaeltryby has been encouraging that we adopt a style that serves more data with a single call. For example, if we call swmm_getLinkResult() we have to pass the output value pointer AND and parameter key. Alternately, we could return an array with ALL the values and use the parameter key to get the value we care about from the array.

[michaeltryby]

The time has come for the API to evolve. It turns out it's straight forward to allocate memory and return multiple values. This is demonstrated in the SWMM and EPANET output APIs to great effect. It allows us to create a compact and functional API that is more convenient for the programmer to use.