From 7df71001ef1a9ea271ae3c409a367d6c2dd628b7 Mon Sep 17 00:00:00 2001 From: Katharina Fey Date: Tue, 4 Jun 2019 23:51:12 +0200 Subject: Changing library name and project structure --- bowl.h | 378 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 bowl.h (limited to 'bowl.h') diff --git a/bowl.h b/bowl.h new file mode 100644 index 0000000..88811c4 --- /dev/null +++ b/bowl.h @@ -0,0 +1,378 @@ +/* + * Please use the API to create and destroy objects as only this way + * memory-safety and memory leaks can be guaranteed. + * + * With the API you can easily create structures like the following: + * + * root [list] + * child1 [list] + * key [literal] - "Username" + * value [literal] - "spacekookie" + * child2 [list] + * key [literal] - "Age" + * value [numerical] - 23 + * child3 + * subchild [list] + * ... + * + * Freeing the root node will free all children + */ + +#ifndef _BOWL_H_ +#define _BOWL_H_ + +#include +#include + +/* A helpful macro that can take care of \0 termated strings! */ +#define REAL_STRLEN(str) (strlen(str) + 1) + +/* Also make sure we're _always_ interpreted as a C file */ +#ifdef __cplusplus +extern "C" { +#endif + + +/* Type that determines what data is stored inside a tree-node */ +typedef enum bowl_t { + UNSET, LITERAL, NUMERIC, LONG_NUMERIC, BOOLEAN, LIST, PAIR, POINTER +} bowl_t; + + +struct bowl { + bowl_t type; + short encset; + size_t size, used; + short copy; + union { + char *literal; + bool boolean; + struct bowl *(*list); + void *pointer; +#ifdef __LONG_LONG_SUPPORT__ + long long numeral; +#else + long numeral; +#endif + + } payload; +}; + + +/** Define some generic error codes first that we can propagate **/ +typedef enum dt_err { + + /* General purpose error codes */ + FAILURE = -1, + SUCCESS = 0, + + INVALID_PARAMS, // A function didn't get the required parameters + MALLOC_FAILED, // A memory allocation failed + INVALID_PAYLOAD, // The payload of a node is invalid + DATA_NOT_RELATED, // Tried to split non-related trees + NODE_NOT_FOUND, // The sought after node was not found + NODE_NOT_ORIGINAL, // Tried to free a node which was a shallow copy + QUERY_TOO_DEEP, + +} dt_err; + + +/** + * Malloc a new bowl object + * + * @param data Reference pointer to bowl element + * @return + */ +dt_err bowl_malloc(struct bowl *(*data)); + + +/** + * Reset the type of a node and free child data + * + * @param data + * @return + */ +dt_err bowl_resettype(struct bowl *data); + + +/** + * Set the data element to a literal and save it's length + * + * @param data Reference to a bowl object + * @param literal String to store + * @return + */ +dt_err bowl_addliteral(struct bowl *data, const char *literal); + + +/** + * Set the data element to a numeral + * + * @param data Reference to a bowl object + * @param numeral Number to store + * @return + */ +dt_err bowl_addnumeral(struct bowl *data, long numeral); + + +/** + * Set the data element to a boolean. Do you really + * need this? Consider using @bowl_add_numeral instead. + * + * @param data Reference to a bowl object + * @param b boolean value (true, false) + * @return + */ +dt_err bowl_addboolean(struct bowl *data, bool b); + + +/** + * Add two new elements as a PAIR node under an existing node + * + * @param data bowl node to become the sub-root + * @param key Reference pointer to the key node + * @param value Reference pointer to the value node + * @return + */ +dt_err bowl_addpair(struct bowl *data, struct bowl *(*key), struct bowl *(*value)); + + +/** + * Add a new data element to the resursive data store + * + * @param data Root reference + * @param new_data Reference pointer to a new bowl node + * @return + */ +dt_err bowl_addlist(struct bowl *data, struct bowl *(*new_data)); + + +/** + * This function enables you to store your own structures in a node. It however + * also requires you to do some of your own memory management. + * + * WARNING: Can leak memory if pointer is previously set! + * + * To make sure that this function CAN NOT leak memory you should run + * "bowl_resettype" on the root element to remove the pointer. + * + * Also make sure that no other part of your application will use the + * pointer at a later date! + * + * @param data Root reference + * @param ptr A pointer to store in this node + * @return + */ +dt_err bowl_addpointer(struct bowl *data, void *ptr); + + +/** + * This function takes two nodes as arguments. The nodes MUST be + * related or an error will be thrown. Both nodes will still + * be accessable after this operation but no longer be related to + * each other. + * + * The second node will be removed from the tree of the root node. + * + * + * + * @param data Root reference + * @param sp Subtree node related to root to split off + * @return + */ +dt_err bowl_split_trees(struct bowl *data, struct bowl *sp); + + +/** + * This function is very simmilar to dt_err "bowl_addlist" + * with the difference that it doesn't allocate new memory but instead + * works with existing nodes. + * + * You need to provide a ROOT node which is of type list. It will + * procede to add the second (merge) node into the child-list of the + * root data node - essentially making them related. + * + * This allows for very efficient tree merging. + * + * @param data Root reference + * @param merge Second root reference to merge + * @return + */ +dt_err bowl_merge_trees(struct bowl *data, struct bowl *merge); + + +/** + * You can use this function to search the structure of a root node to find the + * parent of the node you provide as "data". It will leave the search pointer + * blanked if the node can't be found in the structure. + * + * @param root Root reference to search + * @param data The node we are searching for + * @param parent The node parent we are interested in + * @return + */ +dt_err bowl_parent(struct bowl *root, struct bowl *data, struct bowl **parent); + + +/** + * Recursive tree search function that will return the first occurence match + * to a provided payload (with an exact type). If you have data duplication + * in your tree this _might_ return some false positives. + * + * @param data Root reference to search + * @param found Empty pointer to put found node into + * @param payload What should be found + * @param type What type of data should be found + * @return + */ +dt_err bowl_search_payload(struct bowl *data, struct bowl *(*found), void *payload, bowl_t type); + + +/** + * Much like #{bowl_search_payload} but limiting it's search to keys in a list structure of certain depth. + * This means that in a key-value store structure only top-level items can be searched or the entire + * depth of the tree (or any vaue in between) + * + * @param data + * @param found + * @param payload + * @param type + * @return + */ +dt_err bowl_search_keypayload(struct bowl *data, struct bowl *(*found), void *payload, bowl_t type, int depth); + + +/** + * Performs a deep copy of a data node hirarchy. Does not copy externally + * pointed structures. Does garuantee safety of hirarchy. + * + * @param data + * @param copy + * @return + */ +dt_err bowl_copy_deep(struct bowl *data, struct bowl *(*copy)); + + +/** + * Performs a copy operation on a single node. Copies the payload on a pointer + * level which means that strings and numbers will be duplicated whereas external + * pointers and lists will only be references to the original content. + * + * Freeing the copy has no effect on the original payloads stored in other + * nodes. + * + * @param data + * @param copy + * @return + */ +dt_err bowl_copy(struct bowl *data, struct bowl *(*copy)); + + +/** + * A retrieve function to get data back from a node that doesn't require + * you to manually access parts of the struct. + * + * Needs to be provided with a reference to a pointer that can then be + * written to. You can make the reference type specific if you know + * what kind of data you're expecting. Please however note that compiler + * errors might occur if you provide a wrong pointer type. + * + * @param data Node reference to access + * @param val Reference pointer to write into + * @return + */ +dt_err bowl_get(struct bowl *data, void *(*val)); + + +/** + * Return the type of a node as plain text + * + * @param data + * @return + */ +const char *bowl_dtype(struct bowl *data); + + +/** + * Prints the data bowl object and all of its children + * + * @param data + */ +void bowl_print(struct bowl *data); + + +/** + * Will free the data reference and all of it's children. It will however NOT + * touch pointers to objects that weren't allocated by libdyntree! + * + * @param data + * @return + */ +dt_err bowl_free_shallow(struct bowl *data); + + +/** + * Like #{bowl_free_shallow} but will also remove structs that + * weren't allocated by libdyntree. Will throw warnings when trying + * to free payloads from shallow copy nodes + * + * @param data + * @return + */ +dt_err bowl_free(struct bowl *data); + + +/************************** + * + * Error handling functions + * + **************************/ + +const char *bowl_err_getmsg(dt_err *e); + +/*************************** + * + * Encoding/ Decoding support hooks + * + ***************************/ + +/** + * This function sets the wanted encoding setting on a + * root node (and assumes for children). Without setting flags via + * this function first the encode will fail. + * + * @param data Root reference + * @param setting Look at DYNTREE_JSON flags for options + * @return + */ +dt_err bowl_encode_set(struct bowl *data, short setting); + +/** + * A simple list node walker that encodes a dyn_tree node hirarchy + * into a json string. Requires the encoding setting to be set on the + * root node in order to successfully encode. + * + * Can throw errors and initialise NULL return string. + * + * @param data + * @param json_data + * @return + */ +dt_err bowl_encode_json(struct bowl *data, char *json_data); + + +/** + * Decodes a json string into a dyn_tree node hirarchy while providing + * memory safety and error checking. Will gracefully return errors + * if the provided json string is invalid or contains errors. + * + * @param data New root reference + * @param json_data Input json string + * @return + */ +dt_err bowl_decode_json(struct bowl *(*data), const char *json_data, size_t len); + +#ifdef __cplusplus +} +#endif +#endif //_DYNTREE_H_ -- cgit v1.2.3