Weed utilities library documentation
------------------------------------

The Weed utilities library provides simplified functions to both Weed
hosts and Weed plugins.


int weed_plant_has_leaf (weed_plant_t *plant, const char *key) ::
    returns WEED_TRUE if plant has a leaf "key", even if it has no
    elements. Returns WEED_FALSE otherwise.


int weed_set_int_value (weed_plant_t *plant, const char *key, int value) :: create or amend value of WEED_SEED_INT leaf "key". If the
       leaf exists, and its type is not WEED_SEED_INT, returns
       WEED_ERROR_WRONG_SEED_TYPE and the value is not
       updated. Returns WEED_ERROR_MEMORY_ALLOCATION if there is
       unsuffient memory. Returns WEED_NO_ERROR otherwise.


int weed_set_double_value (weed_plant_t *plant, const char *key, double value) :: as above, but uses WEED_SEED_DOUBLE.

int weed_set_boolean_value (weed_plant_t *plant, const char *key, int value) :: as above, but uses WEED_SEED_BOOLEAN.

int weed_set_int64_value (weed_plant_t *plant, const char *key, int64_t value) :: as above, but uses WEED_SEED_INT64.

int weed_set_string_value (weed_plant_t *plant, const char *key, char
*value) :: as above, but uses WEED_SEED_STRING. The string is copied,
so the original should be freed after use.

int weed_set_plantptr_value (weed_plant_t *plant, const char *key,
weed_plant_t *value) :: as above, but uses WEED_SEED_PLANTPTR. The
actual plant is not copied, only a reference to it.

int weed_set_voidptr_value (weed_plant_t *plant, const char *key, void
*value) :: as above, but uses WEED_SEED_VOIDPTR. The memory pointed to
is not copied, only a reference to it.

int weed_get_int_value (weed_plant_t *plant, const char *key, int *error) :: Returns a single value (the first value if "key" is an
	array). If the leaf does not exist, the value of error is set to
	WEED_ERROR_NOSUCH_LEAF. If the number of elements is zero, the value
	of error is set to WEED_ERROR_NOSUCH_ELEMENT. If the leaf is not
	WEED_SEED_INT, the value of error is set to
	WEED_ERROR_WRONG_SEED_TYPE. Error is set to 
	WEED_ERROR_MEMORY_ALLOCATION if there is insufficient memory
	space. Otherwise error is set to WEED_NO_ERROR.

double weed_get_double_value (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_DOUBLE.

int weed_get_boolean_value (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_BOOLEAN.

int64_t weed_get_int64_value (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_INT64.

void *weed_get_voidptr_value (weed_plant_t *plant, const char *key,
int *error) :: as above, but uses WEED_SEED_VOIDPTR. The actual memory
is not copied, only a reference to it is returned.

weed_plant_t *weed_get_plantptr_value (weed_plant_t *plant, const char
*key, int *error) :: as above, but uses WEED_SEED_PLANTPTR. The actual
plant is not copied, only a reference to it is returned.

char *weed_get_string_value (weed_plant_t *plant, const char *key, int
*error) :: as above, but uses WEED_SEED_STRING. The returned values
are copied, and should be freed with weed_free() after use.

int *weed_get_int_array (weed_plant_t *plant, const char *key, int *error) :: Returns an array of WEED_SEED_INT. If the leaf does not
	exist, the value of error is set to WEED_ERROR_NOSUCH_LEAF. If the
	number of elements is zero, the value of error is set to
	WEED_ERROR_NOSUCH_ELEMENT. If the leaf is not WEED_SEED_INT, the value
	of error is set to WEED_ERROR_WRONG_SEED_TYPE. Error is set to
	WEED_ERROR_MEMORY_ALLOCATION if there is insufficient memory. Otherwise error is set to WEED_NO_ERROR.
	weed_leaf_num_elements(plant,key) should be called first to get the
	array size. The array should be freed with weed_free() after use.

double *weed_get_double_array (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_DOUBLE.

int *weed_get_boolean_array (weed_plant_t *plant, const char *key, int
*error) :: as above, but uses WEED_SEED_BOOLEAN.

int64_t *weed_get_int64_array (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_INT64.

void **weed_get_voidptr_array (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_VOIDPTR. The memory areas
are not copied, only references are returned.

weed_plant_t **weed_get_plantptr_array (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_PLANTPTR. The
actual plants are not copied, only references are returned.

char **weed_get_string_array (weed_plant_t *plant, const char *key, int *error) :: as above, but uses WEED_SEED_STRING. Strings are
copied, so after use, each element should be freed with weed_free(), and then the entire array
should be freed with weed_free().

int weed_set_int_array (weed_plant_t *plant, const char *key, int num_elems, int *values) :: create or amend value of WEED_SEED_INT leaf "key". If the
       leaf exists, and its type is not WEED_SEED_INT, returns
       WEED_ERROR_WRONG_SEED_TYPE and the value is not
       updated. Returns WEED_ERROR_MEMORY_ALLOCATION if there is
       insufficient memory for the operation. Returns
       WEED_NO_ERROR otherwise. Values should be an array with
       num_elems elements. Values are copied, so the original array
       should be freed after use.

int weed_set_double_array (weed_plant_t *plant, const char *key, int num_elems, double *values) :: as above, but uses WEED_SEED_DOUBLE.

int weed_set_boolean_array (weed_plant_t *plant, const char *key, int num_elems, int *values) :: as above, but uses WEED_SEED_BOOLEAN.

int weed_set_int64_array (weed_plant_t *plant, const char *key, int num_elems, int64_t *values) :: as above, but uses WEED_SEED_INT64.

int weed_set_voidptr_array (weed_plant_t *plant, const char *key, int num_elems, void **values) :: as above, but uses WEED_SEED_VOIDPTR.

int weed_set_plantptr_array (weed_plant_t *plant, const char *key, int
num_elems, weed_plant_t **values) :: as above, but uses WEED_SEED_PLANTPTR.

int weed_set_string_array (weed_plant_t *plant, const char *key, int num_elems, char **values) :: as above, but uses WEED_SEED_STRING. The
	   strings are copied, so the original values should be freed with
	   weed_free() after use.

int weed_leaf_copy (weed_plant_t *dest, char *keyt, weed_plant_t *src, char *keyf) :: copy leaf "keyf" in src plant to leaf "keyt" in
      dest plant. Returns WEED_ERROR_NOSUCH_LEAF if the source leaf does not
      exist. Returns WEED_ERROR_WRONG_SEED_TYPE if seed types of src and
      dest do not match. Returns WEED_ERROR_MEMORY_ALLOCATION if there is
      insufficient memory for the operation. Returns WEED_NO_ERROR
      otherwise. Can copy leaves even with any number (even zero) elements.

weed_plant_t *weed_plant_copy (weed_plant_t *src) :: returns a
	     copy-by-value of plant src. The new plant will have the same leaves as
	     the source plant. Returns NULL if src was NULL or if the operation ran
	     out of memory.

int weed_get_plant_type (weed_plant_t *plant) :: a convenience
    function which returns the value of the "type" leaf for a plant.

