src/libfatptr/libfatptr.h

/* #include <stdlib.h> /* size_t */

#if !defined FatPtr_size_t
#	define FatPtr_size_t size_t
#endif
#if !defined FatPtr_scalar_t
#	define FatPtr_scalar_t int
#endif
#define FatPtr_vector_t FatPtr_scalar_t *

struct FatPtr{
	FatPtr_size_t a; /* allocation in sizeof char */
	FatPtr_size_t s; /* actual size in sizeof *v */
	FatPtr_vector_t v; /* vector */
};

/* FatPtr_append
 * - FatPtr *p: object to which to append
 * - FatPtr_scalar_t c: scalar to be appended
 * Returns NULL if the operation failed (due to malloc(3)) or if p was NULL.
 * Otherwise returns p.
 * Appends c to p. */
struct FatPtr *FatPtr_append(struct FatPtr *p, FatPtr_scalar_t c);

/* FatPtr_construct
 * - FatPtr *p: object to be constructed
 * Returns p.
 * Initializes p and grows its maximum length to a reasonable amount of units.
 */
struct FatPtr *FatPtr_construct(struct FatPtr *p);

/* FatPtr_destruct
 * - FatPtr *p: object to destruct
 * Returns NULL.
 * Destroys p without leaking memory. */
struct FatPtr *FatPtr_destruct(struct FatPtr *p);

/* FatPtr_grow
 * - FatPtr *p: object to grow
 * - size_t units: units (in sizeof char) by which to grow p
 * Returns p.
 * Grows p's maximum length by units (in sizeof char). */
struct FatPtr *FatPtr_grow(struct FatPtr *p, size_t units);

/* FatPtr_index
 * - FatPtr *p: object to index
 * - size_t index: index of the scalar to get
 * Returns a pointer to the FatPtr_scalar_t at the given index within the
 * vector, or NULL if p was NULL. */
FatPtr_vector_t FatPtr_index(struct FatPtr *p, size_t index);

/* FatPtr_initialize
 * - FatPtr *p: object to initialize
 * Returns p.
 * Initializes p to zero values. */
struct FatPtr *FatPtr_initialize(struct FatPtr *p);

/* FatPtr_prepend
 * - FatPtr *p: object to which to prepend
 * - FatPtr_vector_t s: vector to prepend
 * - size_t units: amount of units from the vector to prepend
 * Prepends units of s to the vector in p. Returns NULL if a memory allocation
 * failed and p otherwise. */
struct FatPtr *FatPtr_prepend(struct FatPtr *p, FatPtr_vector_t s, size_t units);

/* FatPtr_shiftleft
 * - FatPtr *p: object to shift
 * - size_t units: units (in sizeof *v) by which to shift p
 * Returns p.
 * Shifts members of p left by units, leaving the last units members intact. */
struct FatPtr *FatPtr_shiftleft(struct FatPtr *p, size_t units);

/* FatPtr_shiftright
 * - FatPtr *p: object to shift
 * - size_t units: units (in sizeof *v) by which to shift p
 * Returns p.
 * Shifts members of p right by units, leaving the first units members intact.
 */
struct FatPtr *FatPtr_shiftright(struct FatPtr *p, size_t units);

/* FatPtr_trimend
 * - FatPtr *p: object to trim
 * - size_t units: units (in sizeof *v) by which to shift p
 * Returns p.
 * Removes the last units members of p from p. */
struct FatPtr *FatPtr_trimend(struct FatPtr *p, size_t units);

/* FatPtr_trimfront
 * - FatPtr *p: object to trim
 * - size_t units: units (in sizeof *v) by which to shift p
 * Returns p.
 * Removes the first units members of p from p. */
struct FatPtr *FatPtr_trimfront(struct FatPtr *p, size_t units);