C a function that returns an array

Question

If I need to write a function that returns an array: int*, which way is better?

1. int* f(..data..)

or: void f(..data..,int** arr)

and we call f like this: int* x; f(&x);. (maybe they are both the same but I am not sure. but if I need to return an ErrorCode(it's an enum) too, then in the first way f will get ErrorCode* and in the second way, f will return an ErrorCode).

Answer 1

Returning an array is just returning a variable amount of data.
That's a really old problem, and C programmers developed many answers for it:

1. Caller passes in buffer.
   1. The neccessary size is documented and not passed, too short buffers are Undefined Behavior: strcpy()
   2. The neccessary size is documented and passed, errors are signaled by the return value: strcpy_s()
   3. The buffer size is passed by pointer, and the called function reallocates with the documented allocator as needed: POSIX getline()
   4. The neccessary size is unknown, but can be queried by calling the function with buffer-length 0: snprintf()
   5. The neccessary size is unknown and cannot be queried, as much as fits in a buffer of passed size is returned. If neccessary, additional calls must be made to get the rest: fread()
   6. ⚠ The neccessary size is unknown, cannot be queried, and passing too small a buffer is Undefined Behavior. This is a design defect, therefore the function is deprecated / removed in newer versions, and just mentioned here for completeness: gets().
2. Caller passes a callback:
   1. The callback-function gets a context-parameter: qsort_s()
   2. The callback-function gets no context-parameter. Getting the context requires magic: qsort()
3. Caller passes an allocator: Not found in the C standard library. All allocator-aware C++ containers support that though.
4. Callee contract specifies the deallocator. Calling the wrong one is Undefined Behavior: fopen()->fclose() strdup()->free()
5. Callee returns an object which contains the deallocator: COM-Objects
6. Callee uses an internal shared buffer: asctime()

Be aware that either the returned array must contain a sentinel object or other marker, you have to return the length separately, or you have to return a struct containing a pointer to the data and the length.
Pass-by-reference (pointer to size or such) helps there.

In general, whenever the user has to guess the size or look it up in the manual, he will sometimes get it wrong. If he does not get it wrong, a later revision might invalidate his careful work, so it doesn't matter he was once right. Anyway, this way lies madness (UB).

For the rest, choose the most comfortable and efficient one you can.

Regarding an error code: Remember there's errno.

Answer 2

Usually it's more convenient and semantic to return the array

int* f(..data..)

If ever you need complexe error handling (e.g., returning errors values), you should return the error as an int, and the array by value.

Answer 3

There is no "better" here: you decide which approach fits the needs of the callers better.

Note that both functions are bound to give a user an array that they allocate internally, so deallocating the resultant array becomes a responsibility of the caller. In other words, somewhere inside f() you would have a malloc, and the user who receives the data must call free() on it.

You have another option here - let the caller pass the array into you, and return back a number that says how many items you put back into it:

size_t f(int *buffer, size_t max_length)

This approach lets the caller pass you a buffer in a static or in the automatic memory, thus improving flexibility.

Answer 4

the classic model is (assuming you need to return error code too)

int f(...., int **arr)

even though it doesnt flow so nicely as a function returning the array

Note this is why the lovely go language supports multiple return values.

Its also one of the reasons for exceptions - it gets the error indicators out of the function i/o space

Answer 5

The first one is better if there is no requirement to deal with an already existent pointer in the function. The second one is used when you already have a defined pointer that points to an already allocated container (for example a list) and inside the function the value of the pointer can be changed.

Answer 6

If you must call f like int* x; f(&x);, you do not have much of a choice. You must use the second syntax, i.e., void f(..data..,int** arr). This is because you are not using return value anyways in your code.

Answer 7

The approach depends on a specific task and perhaps on your personal taste or a coding convention adopted in your project.

In general, I'd like to pass pointers as "output" parameters instead of return'ing an array for a number of reasons.

1. You likely want to return a number of elements in the array together with the array itself. But if you do this:

   int f(const void* data, int** out_array);
   

   Then if you see the signature first time, you can't quite tell what the function returns, the number of elements, or an error code, so I prefer to do this:

   void f(const void* data, int** out_array, int* out_array_nelements);
   

   Or even better:

   void f(const void* data, int** out_array, size_t* out_array_nelements);
   

   The function signature must be self-explanatory, and the parameter names help to achieve that.

2. The output array needs to be stored somewhere. You need to allocate some memory for the array. If you return a pointer to the array without passing the same pointer as argument, then you can't allocate memory on the stack. I mean, you cannot do this:

   int f (const void *data) {
       int array[10];
       return array;  /* the array is likely deallocated when the function exits */
   }
   

   Instead, you have to do static int array[10] (which is not thread-safe) or int *array = malloc(...) which leads to memory leaks.

   So I suggest you to pass a pointer to the array which is already allocated before the function call, like this:

   void f(const void *data, int* out_array, size_t* out_nelements, size_t max_nelements);
   

   The benefit is you are free to choose where to allocate the array:

   On the stack:

   int array[10] = { 0 };
   size_t max_nelements = sizeof(array)/sizeof(array[0]);
   size_t nelements = 0;
   
   f(data, array, &nelements, max_nelements);
   

   Or in the heap:

   size_t nelements = 0;
   size_t max_nelements = 10;
   int *array = malloc(max_nelements * sizeof(int));
   f(data, array, &nelements, max_nelements);
   

   See, with this approach you are free to choose how to allocate the memory.