Ex35: what does `element_size` stand for?

C
#1

When doing exercise 35, in the testset darray_algos.c we have a support function called create_words:

DArray *create_words()
{
    DArray *result = DArray_create(0, 5);

The first param (the one with 0) is the element_size. In my code this runs into an error because I do not accept an element size of zero. This test case would suggest that element size of zero is acceptable.

So I checked the ultimate code in liblcthw on github. It turns out that element_size is permitted to be zero and if so, the function DArray_clear will not clear anything. It seems like element_size doubles as an indication whether the library is allowed to free the underlying elements.

This is where I miss specification. Including this testcase, it is difficult to deduce that the element_size determines whether DArray_clear really does a free on elements.

My question is:

  1. Is this correct? Does element_size stand for the element size and for whether the library is allowed to clear?
  2. Should this (in real life) be extensively documented or is it general practice to do it this way?

Kind regards, Guus.

#2

I may have overestimated the amount of documentation necessary. My questions still stand, but I wanted to show how I documented it in code:

#include <lcthw/darray.h>
#include <assert.h>

/**
 * create an array of elements with optional element size.
 *
 * @param element_size size_t size of the element or zero if element is not to be free-ed.
 * @param initial_max size_t the initial allocation of memory for the array.
 * @return DArray * a pointer to DArray or NULL on error.
 *
 */
DArray *DArray_create(size_t element_size, size_t initial_max)
{
    DArray *array = NULL;
    check(initial_max > 0, "You must set an initial max > 0");

    // allocate memory for the array
    array = malloc(sizeof(DArray));
    check_mem(array);

Hopefully that should be enough for the library user.

Kind regards, Guus.

#3

Yes, that works, but honestly I think that should a flag of sometime rather than overloading that parameter.