Adding INSERT into collection functionality.

Add was always insterting at the end of the collection.
With this change one can control where the item is
inserted and deal with the duplicates too.
Also one now can extract items from collection
using absolute and relative disposition.
Using more advanced hashing function.

1 files changed, 372 insertions, 16 deletions

diff --git a/common/collection/collection.h b/common/collection/collection.h
index 687f468d7..28622a505 100644
--- a/common/collection/collection.h
+++ b/common/collection/collection.h
@@ -48,6 +48,7 @@
                                                Useful when traversing
                                                collections */
 
+
 /* Any data we deal with can't be longer than this */
 /* FIXME - make it compile time option */
 #define COL_MAX_DATA    65535
@@ -151,11 +152,11 @@ struct collection_iterator;
  * empty.
  * When you put items into a bag you do not see the contents of the bag.
  * You just hold the bag. How many other bags inside this bag you do not know.
- * But you might know that you put a "valet" somewhere there.
- * You ask the bag you hold: "find my valet and give it to me".
- * get_item function will return you the item that is you "valet".
+ * But you might know that you put a "wallet" somewhere there.
+ * You ask the bag you hold: "find my wallet and give it to me".
+ * get_item function will return you the item that is your "wallet".
  * You can then change something or just get information about the item you
- * retrieved. But in most cases you do not the valet itself. You want to get
+ * retrieved. But in most cases you do not the wallet itself. You want to get
  * something from the vallet or put something into it. IMO money would be an
  * obvious choice. To do this you use update_xxx_property functions.
  * There might be a bag somewhere deep and you might want to add something to
@@ -163,13 +164,13 @@ struct collection_iterator;
  * want the item to be added to. If this sub collection argument is NULL top
  * level collection is assumed.
  * The search in the collections users a dotted notation to refer to an item (or
- * property). You can search for "valet" and it will find any first instance of
- * the "valet" in your luggage. But you might have two valets. One is yours and
- * another is your significant other's. So you might say find "my.valet".
- * It will find valet in your bad (collection) named "my". This collection can
+ * property). You can search for "wallet" and it will find any first instance of
+ * the "wallet" in your luggage. But you might have two wallets. One is yours and
+ * another is your significant other's. So you might say find "my.wallet".
+ * It will find wallet in your bad (collection) named "my". This collection can
  * be many levels deep inside other collections. You do not need to know the
  * full path to get to it. But if you have the full path you can use the fill
- * path like this "luggage.newbags.my.valet".
+ * path like this "luggage.newbags.my.wallet".
  * It is useful to be able to put bags into bags as well as get them out of each
  * other. When the collection is created the header keeps a reference count on
  * how many copies of the collection are known to the world. So one can put a
@@ -181,14 +182,27 @@ struct collection_iterator;
  * use.
  */
 
-/* Function that creates an named collection */
+/* Function that creates a named collection */
 int create_collection(struct collection_item **ci, const char *name,
                       unsigned cclass);
 
+/* Function that creates a named collection using a memory descriptor */
+/* FIXME - function is a placeholder. It is not implemented yet.
+ * will be added in future together with the definition of the
+ * descriptor structure.
+ * The purpose is to control the internal implementation of the collection
+ * a) Use hash table for faster searches if the collection is expected to be large.
+ * b) Define memory functions to use.
+ */
+/*
+int create_collection_ex(struct collection_item **ci, const char *name,
+                         unsigned cclass, struct cdescriptor *descrptor);
+*/
+
 /* Function that destroys a collection */
 void destroy_collection(struct collection_item *ci);
 
-/* Family of functions that add properties to an event */
+/* Family of functions that add properties to a collection */
 /* See details about subcollection argument above. */
 /* Family includes the following convinience functions: */
 /* Add a string property to collection. The length should include the
@@ -397,7 +411,7 @@ const void *get_item_data(struct collection_item *ci);
 
 /* If you want to modify the item that you got as a result of iterating through collection
  * or by calling get_item(). If you want to rename item provide a new name in the property
- * argument. If you want the data to remain unchanged use NULL as data parameter.
+ * argument. If you want the data to remain unchanged use 0 as length parameter.
  * If item is a reference or collection the call will return error.
  * Previous type and data of the item is destroyed.
  */
@@ -407,7 +421,14 @@ int modify_item(struct collection_item *item,
                 void *data,
                 int length);
 
-/* Convenience functions that wrap modify_tem(). */
+/* Rename the item */
+int modify_item_property(struct collection_item *item,
+                         const char *property);
+
+/* Convenience functions that wrap modify_item().
+ * They always assign new value.
+ * To rename the property just use modify_item_property();
+ */
 int modify_str_item(struct collection_item *item,
                     const char *property,
                     char *string,
@@ -499,9 +520,10 @@ int get_collection_class(struct collection_item *item, /* Collection */
 /* Get collection count */
 int get_collection_count(struct collection_item *item, /* Collection */
                          unsigned *count);             /* Number of elements in
-                                                          this collection.
-                                                          Each subcollection is
-                                                          counted as 1 element.
+                                                        * this collection.
+                                                        * Each subcollection is
+                                                        * counted as 1 element.
+                                                        * Header is also counted.
                                                         */
 
 /* Convenience function to check if the collection is of the specific class */
@@ -510,5 +532,339 @@ int is_of_class(struct collection_item *item,  /* Collection */
                 unsigned cclass);              /* Class of the collection */
 
 
+/*
+ * Series of collection functions that allow using collection as a stack or a FIFO
+ */
+
+
+/* Extract the item from the collection */
+/* The header will not be considered for extraction. */
+int extract_item(struct collection_item *ci,        /* Top collection */
+                 const char *subcollection,         /* Sub collection */
+                 int disposition,                   /* Which to extract */
+                 const char *refprop,               /* Property to relate to */
+                 int index,                         /* Index of the property to extract. See notes. */
+                 int type,                          /* Type filter */
+                 struct collection_item **ret_ref); /* Returns the reference back */
+
+/* Similar extraction function as above just considers only one level. */
+int extract_item_from_current(struct collection_item *ci,        /* Top collection */
+                              int disposition,                   /* Which to extract */
+                              const char *refprop,               /* Property to relate to */
+                              int index,                         /* Index of the property to extract. See notes. */
+                              int type,                          /* Type filter */
+                              struct collection_item **ret_ref); /* Returns the reference back */
+
+/* Insert item to the collection */
+/* WARNING: Only use this function to insert items
+ * that were extracted using extract_item().
+ * NEVER use it with items that were returned
+ * by get_item() or add_xxx_property_with_ref() or
+ * with insert_xxx_property_with_ref().
+ * The fundamental difference is that when you extracted item
+ * using extract_item() it stops to be managed by a collection.
+ * With such item you can:
+ * a) Insert this item into another (or same) collection
+ * b) Get item information using get_item_xxx() functions.
+ * c) Destroy item using delete_item().
+ * You are required to do either a) or c) with such item.
+ */
+int insert_item(struct collection_item *collection, /* Top collection */
+                const char *subcollection,          /* Sub collection */
+                struct collection_item *item,       /* Item to insert */
+                int disposition,                    /* What should be the position of the item */
+                const char *refprop,                /* Property to relate to */
+                int index,                          /* Index of the property to extract. See notes. */
+                unsigned flags);                    /* Flags that control naming issues */
+
+/* Insert the item into the top level collection (similar to the function above)
+ * but does not provide access to the sub collection.
+ */
+int insert_item_into_current(struct collection_item *collection,
+                             struct collection_item *item,
+                             int disposition,
+                             const char *refprop,
+                             int index,
+                             unsigned flags);
+
+
+
+/* Function to delete the item */
+void delete_item(struct collection_item *item);
+
+/* Possible dispositions for insert, extract and delete function(s).
+ * Not all of these dispositions are implemented day one.
+ * If disposition is not implemented the function
+ * will return error ENOSYS.
+ */
+#define COL_DSP_END             0 /* Add property to the end of the collection */
+                                  /* Extract or delete last property in collection */
+#define COL_DSP_FRONT           1 /* Add property to the top of the collection */
+                                  /* Extract or delete firat property in collection */
+#define COL_DSP_BEFORE          2 /* Add property before other named property */
+                                  /* Extract or delete property that is before given
+                                   * property. If the given property is first
+                                   * in the list ENOENT is returned.
+                                   */
+#define COL_DSP_AFTER           3 /* Add property immediately after other named property */
+                                  /* Delete or extract property immediately after given
+                                   * property. If the given property is last in the list
+                                   * ENOENT is returned.
+                                   */
+#define COL_DSP_INDEX           4 /* Add, extract or delete property using index.
+                                   * See notes below.
+                                   */
+/* NOTE ABOUT USING: COL_DSP_INDEX. */
+/* The COL_DSP_INDEX adds the item as N-th item after header in the list.
+ * Index is zero based.
+ * If there are less than N items in the list the item is added to the end.
+ * The index value of 0 means that the item will be added immediately
+ * after the header. Index of 1 will mean that it is added after first data item and so on.
+ *
+ * In case of extraction or deletion the N-th item of the collection
+ * will be extracted or deleted.
+ * Index is zero based.
+ * If there are less than N+1 items in the list the function will return ENOENT.
+ */
+
+/* The following three dispositions operate only with list of duplicate
+ * properties that are going one after another.
+ * In case of addition the property name is taken from the item
+ * and the value refprop is ignored.
+ * In case of extraction or deletion the property name is taken
+ * from the refprop.
+ */
+#define COL_DSP_FIRSTDUP        5 /* Add property as a first dup of the given property */
+                                  /* In case of extraction or deletion extracts or deletes
+                                   * given property.
+                                   */
+#define COL_DSP_LASTDUP         6 /* Add property as a last dup of the given property */
+                                  /* In case of extraction or deletion extracts or deletes
+                                   * last duplicate property in the uninterrupted sequence of
+                                   * properties with the same name.
+                                   */
+#define COL_DSP_NDUP            7 /* Add property as a N-th dup (0- based) of the given property. */
+                                  /* In case of extraction or deletion extracts or deletes
+                                   * N-th (0-based) duplicate of the given property.
+                                   * If index is greater than number of duplicate
+                                   * properties in sequence ENOENT is returned.
+                                   * See more details below.
+                                   */
+
+/* Other dispositions might be possible in future. */
+
+/* The COL_DSP_NDUP is used in case of the multi value property
+ * to add a new property with the same name into specific place
+ * in the list of properties with the same name.
+ * The index of 0 will mean to add the property before the first instance of the property with the same name.
+ * If the property does not exist ENOENT will be returned.
+ * If the index is greater than the last property with the same name the item will be added
+ * immediately after last property with the same name.
+ */
+
+/* Flags that can be used with insert functions */
+#define COL_INSERT_NOCHECK      0   /* This is the default mode - no dup checks on insert */
+#define COL_INSERT_DUPOVER      1   /* Check for dup name and overwrite - position ignored */
+#define COL_INSERT_DUPOVERT     2   /* Check for dup name and type and overwrite - position ignored */
+#define COL_INSERT_DUPERROR     3   /* Return error EEXIST if the entry with the same name exists */
+#define COL_INSERT_DUPERRORT    4   /* Return error EEXIST if the entry with the same name and type exists */
+#define COL_INSERT_DUPMOVE      5   /* Check for dups, overwrite, extracts and
+                                     * then move to the position requested */
+#define COL_INSERT_DUPMOVET     6   /* Check for dup name and type, overwrite, extracts
+                                     * and then move to the position requested */
+
+/* In future can be made more complex */
+
+/* NOTE ABOUT FLAGS: Use of the DUP checking flags is costly since it requires a forward look up of the whole
+ * collection before the item is inserted. Do not use it until it is absolutely necessary.
+ */
+
+
+
+/* The attributes in the collection are always added to the end.
+ * The family of the insert_xxx(functions) provides
+ * much more flexibility than add_xxx_property_xxx() functions.
+ */
+
+/* Insert property with reference */
+int insert_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                             const char *subcollection,         /* Sub collection */
+                             int disposition,                   /* Where to insert */
+                             const char *refprop,               /* Property to relate to */
+                             int index,                         /* Index of the property to add */
+                             unsigned flags,                    /* Flags that control naming issues */
+                             const char *property,              /* Name */
+                             int type,                          /* Data type */
+                             void *data,                        /* Pointer to the data */
+                             int length,                        /* Length of the data. For
+                                                                 * strings it includes the
+                                                                 * trailing 0
+                                                                 */
+                             struct collection_item **ret_ref); /* Returns the reference back */
+
+
+int insert_str_property(struct collection_item *ci,        /* A collection of items */
+                        const char *subcollection,         /* Sub collection */
+                        int disposition,                   /* Where to insert */
+                        const char *refprop,               /* Property to relate to */
+                        int index,                         /* Index of the property to add */
+                        unsigned flags,                    /* Flags that control naming issues */
+                        const char *property,              /* Name */
+                        char *string,                      /* String */
+                        int length);                       /* Length */
+
+int insert_binary_property(struct collection_item *ci,        /* A collection of items */
+                           const char *subcollection,         /* Sub collection */
+                           int disposition,                   /* Where to insert */
+                           const char *refprop,               /* Property to relate to */
+                           int index,                         /* Index of the property to add */
+                           unsigned flags,                    /* Flags that control naming issues */
+                           const char *property,              /* Name */
+                           void *binary_data,                 /* Binary data */
+                           int length);                       /* Length */
+
+
+int insert_int_property(struct collection_item *ci,        /* A collection of items */
+                        const char *subcollection,         /* Sub collection */
+                        int disposition,                   /* Where to insert */
+                        const char *refprop,               /* Property to relate to */
+                        int index,                         /* Index of the property to add */
+                        unsigned flags,                    /* Flags that control naming issues */
+                        const char *property,              /* Name */
+                        int number);                       /* Integer */
+
+
+int insert_unsinged_property(struct collection_item *ci,        /* A collection of items */
+                             const char *subcollection,         /* Sub collection */
+                             int disposition,                   /* Where to insert */
+                             const char *refprop,               /* Property to relate to */
+                             int index,                         /* Index of the property to add */
+                             unsigned flags,                    /* Flags that control naming issues */
+                             const char *property,              /* Name */
+                             unsigned number);                  /* Unsigned */
+
+
+int insert_long_property(struct collection_item *ci,        /* A collection of items */
+                         const char *subcollection,         /* Sub collection */
+                         int disposition,                   /* Where to insert */
+                         const char *refprop,               /* Property to relate to */
+                         int index,                         /* Index of the property to add */
+                         unsigned flags,                    /* Flags that control naming issues */
+                         const char *property,              /* Name */
+                         long number);                      /* Long */
+
+int insert_ulong_property(struct collection_item *ci,        /* A collection of items */
+                          const char *subcollection,         /* Sub collection */
+                          int disposition,                   /* Where to insert */
+                          const char *refprop,               /* Property to relate to */
+                          int index,                         /* Index of the property to add */
+                          unsigned flags,                    /* Flags that control naming issues */
+                          const char *property,              /* Name */
+                          unsigned long number);             /* Unsigned long */
+
+int insert_double_property(struct collection_item *ci,        /* A collection of items */
+                           const char *subcollection,         /* Sub collection */
+                           int disposition,                   /* Where to insert */
+                           const char *refprop,               /* Property to relate to */
+                           int index,                         /* Index of the property to add */
+                           unsigned flags,                    /* Flags that control naming issues */
+                           const char *property,              /* Name */
+                           double number);                    /* Double */
+
+int insert_bool_property(struct collection_item *ci,        /* A collection of items */
+                         const char *subcollection,         /* Sub collection */
+                         int disposition,                   /* Where to insert */
+                         const char *refprop,               /* Property to relate to */
+                         int index,                         /* Index of the property to add */
+                         unsigned flags,                    /* Flags that control naming issues */
+                         const char *property,              /* Name */
+                         unsigned char logical);            /* Bool */
+
+
+
+int insert_str_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                 const char *subcollection,         /* Sub collection */
+                                 int disposition,                   /* Where to insert */
+                                 const char *refprop,               /* Property to relate to */
+                                 int index,                         /* Index of the property to add */
+                                 unsigned flags,                    /* Flags that control naming issues */
+                                 const char *property,              /* Name */
+                                 char *string,                      /* String */
+                                 int length,                        /* Length */
+                                 struct collection_item **ret_ref); /* Returns the reference back */
+
+int insert_binary_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                    const char *subcollection,         /* Sub collection */
+                                    int disposition,                   /* Where to insert */
+                                    const char *refprop,               /* Property to relate to */
+                                    int index,                         /* Index of the property to add */
+                                    unsigned flags,                    /* Flags that control naming issues */
+                                    const char *property,              /* Name */
+                                    void *binary_data,                 /* Binary data */
+                                    int length,                        /* Length */
+                                    struct collection_item **ret_ref); /* Returns the reference back */
+
+
+int insert_int_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                 const char *subcollection,         /* Sub collection */
+                                 int disposition,                   /* Where to insert */
+                                 const char *refprop,               /* Property to relate to */
+                                 int index,                         /* Index of the property to add */
+                                 unsigned flags,                    /* Flags that control naming issues */
+                                 const char *property,              /* Name */
+                                 int number,                        /* Integer */
+                                 struct collection_item **ret_ref); /* Returns the reference back */
+
+
+int insert_unsinged_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                      const char *subcollection,         /* Sub collection */
+                                      int disposition,                   /* Where to insert */
+                                      const char *refprop,               /* Property to relate to */
+                                      int index,                         /* Index of the property to add */
+                                      unsigned flags,                    /* Flags that control naming issues */
+                                      const char *property,              /* Name */
+                                      unsigned number,                   /* Unsigned */
+                                      struct collection_item **ret_ref); /* Returns the reference back */
+
+int insert_long_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                  const char *subcollection,         /* Sub collection */
+                                  int disposition,                   /* Where to insert */
+                                  const char *refprop,               /* Property to relate to */
+                                  int index,                         /* Index of the property to add */
+                                  unsigned flags,                    /* Flags that control naming issues */
+                                  const char *property,              /* Name */
+                                  long number,                       /* Long */
+                                  struct collection_item **ret_ref); /* Returns the reference back */
+
+int insert_ulong_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                   const char *subcollection,         /* Sub collection */
+                                   int disposition,                   /* Where to insert */
+                                   const char *refprop,               /* Property to relate to */
+                                   int index,                         /* Index of the property to add */
+                                   unsigned flags,                    /* Flags that control naming issues */
+                                   const char *property,              /* Name */
+                                   unsigned long number,              /* Unsigned long */
+                                   struct collection_item **ret_ref); /* Returns the reference back */
+
+int insert_double_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                    const char *subcollection,         /* Sub collection */
+                                    int disposition,                   /* Where to insert */
+                                    const char *refprop,               /* Property to relate to */
+                                    int index,                         /* Index of the property to add */
+                                    unsigned flags,                    /* Flags that control naming issues */
+                                    const char *property,              /* Name */
+                                    double number,                     /* Double */
+                                    struct collection_item **ret_ref); /* Returns the reference back */
+
+int insert_bool_property_with_ref(struct collection_item *ci,        /* A collection of items */
+                                  const char *subcollection,         /* Sub collection */
+                                  int disposition,                   /* Where to insert */
+                                  const char *refprop,               /* Property to relate to */
+                                  int index,                         /* Index of the property to add */
+                                  unsigned flags,                    /* Flags that control naming issues */
+                                  const char *property,              /* Name */
+                                  unsigned char logical,             /* Bool */
+                                  struct collection_item **ret_ref); /* Returns the reference back */
+
 
 #endif