*** empty log message ***

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@909 72102866-910b-0410-8b05-ffd578937521

Source/array.c

@@ -0,0 +1,904 @@
+/* A (pretty good) implementation of a sparse array.
+ * Copyright (C) 1994, 1995, 1996  Free Software Foundation, Inc.
+ * 
+ * Author: Albin L. Jones <Albin.L.Jones@Dartmouth.EDU>
+ * Created: Thu Mar  2 02:28:50 EST 1994
+ * Updated: Sat Feb 10 16:16:12 EST 1996
+ * Serial: 96.02.10.02
+ * 
+ * This file is part of the GNU Objective C Class Library.
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ * 
+ */ 
+
+/**** Included Headers *******************************************************/
+
+#include <objects/allocs.h>
+#include <objects/callbacks.h>
+#include <objects/abort.h>
+#include <objects/array.h>
+#include <objects/hash.h>
+
+/**** Function Implementations ***********************************************/
+
+/** Background functions **/
+
+size_t
+_objects_array_fold_index (size_t index, size_t slot_count)
+{
+  return (slot_count ? (index % slot_count) : 0);
+}
+
+size_t
+_objects_array_internal_index (objects_array_t * array, size_t index)
+{
+  return _objects_array_fold_index (index, array->slot_count);
+}
+
+objects_array_slot_t *
+_objects_array_slot_for_index (objects_array_t * array, size_t index)
+{
+  return (array->slots + _objects_array_internal_index (array, index));
+}
+
+objects_array_bucket_t *
+_objects_array_bucket_for_index (objects_array_t * array, size_t index)
+{
+  objects_array_slot_t *slot;
+  objects_array_bucket_t *bucket;
+
+  /* First, we translate the index into a bucket index to find our
+   * candidate for the bucket. */
+  slot = _objects_array_slot_for_index (array, index);
+  bucket = *slot;
+
+  /* But we need to check to see whether this is really the bucket we
+   * wanted. */
+  if (bucket != NULL && bucket->index == index)
+    /* Bucket `index' exists, and we've got it, so... */
+    return bucket;
+  else
+    /* Either no bucket or some other bucket is where bucket `index'
+     * would be, if it existed.  So... */
+    return NULL;
+}
+
+objects_array_bucket_t *
+_objects_array_new_bucket (objects_array_t * array, size_t index, void *element)
+{
+  objects_array_bucket_t *bucket;
+
+  bucket = (objects_array_bucket_t *) objects_malloc (objects_array_allocs (array),
+					   sizeof (objects_array_bucket_t));
+  if (bucket != NULL)
+    {
+      objects_retain (objects_array_element_callbacks (array), element, array);
+      bucket->index = index;
+      bucket->element = element;
+    }
+  return bucket;
+}
+
+void
+_objects_array_free_bucket (objects_array_t * array, objects_array_bucket_t * bucket)
+{
+  if (bucket != NULL)
+    {
+      objects_release (objects_array_element_callbacks (array), bucket->element, array);
+      objects_free (objects_array_allocs (array), bucket);
+    }
+  return;
+}
+
+objects_array_slot_t *
+_objects_array_new_slots (objects_array_t * array, size_t slot_count)
+{
+  return (objects_array_slot_t *) objects_calloc (objects_array_allocs (array),
+						  slot_count,
+					     sizeof (objects_array_slot_t));
+}
+
+void
+_objects_array_free_slots (objects_array_t * array, objects_array_slot_t * slots)
+{
+  if (slots != NULL)
+    objects_free (objects_array_allocs (array), slots);
+  return;
+}
+
+void
+_objects_array_empty_slot (objects_array_t * array, objects_array_slot_t * slot)
+{
+  if (*slot != NULL)
+    {
+      /* Get rid of the bucket. */
+      _objects_array_free_bucket (array, *slot);
+
+      /* Mark the slot as empty. */
+      *slot = NULL;
+
+      /* Keep the element count accurate */
+      --(array->element_count);
+    }
+
+  /* And return. */
+  return;
+}
+
+void
+_objects_array_insert_bucket (objects_array_t * array, objects_array_bucket_t * bucket)
+{
+  objects_array_slot_t *slot;
+
+  slot = _objects_array_slot_for_index (array, bucket->index);
+
+  /* We're adding a bucket, so the current set of sorted slots is now
+   * invalidated. */
+  if (array->sorted_slots != NULL)
+    {
+      _objects_array_free_slots (array, array->sorted_slots);
+      array->sorted_slots = NULL;
+    }
+
+  if ((*slot) == NULL)
+    {
+      /* There's nothing there, so we can put `bucket' there. */
+      *slot = bucket;
+
+      /* Increment the array's bucket counter. */
+      ++(array->element_count);
+      return;
+    }
+  if ((*slot)->index == bucket->index)
+    {
+      /* There's a bucket there, and it has the same index as `bucket'.
+       * So we get rid of the old one, and put the new one in its
+       * place. */
+      _objects_array_free_bucket (array, *slot);
+      *slot = bucket;
+      return;
+    }
+  else
+    {
+      /* Now we get to fiddle around with things to make the world a
+       * better place... */
+
+      size_t new_slot_count;
+      objects_array_slot_t *new_slots;	/* This guy holds the buckets while we
+					 * muck about with them. */
+      size_t d;			/* Just a counter */
+
+      /* FIXME: I *really* wish I had a way of generating
+       * statistically better initial values for this variable.  So
+       * I'll run a few tests and see...  And is there a better
+       * algorithm, e.g., a better collection of sizes in the sense
+       * that the likelyhood of fitting everything in earlier is
+       * high?  Well, enough mumbling. */
+      /* At any rate, we're guaranteed to need at least this many. */
+      new_slot_count = array->element_count + 1;
+
+      do
+	{
+	  /* First we make a new pile of slots for the buckets. */
+	  new_slots = _objects_array_new_slots (array, new_slot_count);
+
+	  if (new_slots == NULL)
+	    objects_abort ();
+
+	  /* Then we put the new bucket in the pile. */
+	  new_slots[_objects_array_fold_index (bucket->index,
+					       new_slot_count)] = bucket;
+
+	  /* Now loop and try to place the others.  Upon collision
+	   * with a previously inserted bucket, try again with more
+	   * `new_slots'. */
+	  for (d = 0; d < array->slot_count; ++d)
+	    {
+	      if (array->slots[d] != NULL)
+		{
+		  size_t i;
+
+		  i = _objects_array_fold_index (array->slots[d]->index,
+						 new_slot_count);
+
+		  if (new_slots[i] == NULL)
+		    {
+		      new_slots[i] = array->slots[d];
+		    }
+		  else
+		    {
+		      /* A collision.  Clean up and try again. */
+
+		      /* Free the current set of new buckets. */
+		      _objects_array_free_slots (array, new_slots);
+
+		      /* Bump up the number of new buckets. */
+		      ++new_slot_count;
+
+		      /* Break out of the `for' loop. */
+		      break;
+		    }
+		}
+	    }
+	}
+      while (d < array->slot_count);
+
+      if (array->slots != NULL)
+	_objects_array_free_slots (array, array->slots);
+
+      array->slots = new_slots;
+      array->slot_count = new_slot_count;
+      ++(array->element_count);
+
+      return;
+    }
+}
+
+int
+_objects_array_compare_slots (const objects_array_slot_t * slot1,
+			      const objects_array_slot_t * slot2)
+{
+  if (slot1 == slot2)
+    return 0;
+  if (*slot1 == NULL)
+    return 1;
+  if (*slot2 == NULL)
+    return -1;
+
+  if ((*slot1)->index < (*slot2)->index)
+    return -1;
+  else if ((*slot1)->index > (*slot2)->index)
+    return 1;
+  else
+    return 0;
+}
+
+typedef int (*qsort_compare_func_t) (const void *, const void *);
+
+void
+_objects_array_make_sorted_slots (objects_array_t * array)
+{
+  objects_array_slot_t *new_slots;
+
+  /* If there're already some sorted slots, then they're valid, and
+   * we're done. */
+  if (array->sorted_slots != NULL)
+    return;
+
+  /* Make some new slots. */
+  new_slots = _objects_array_new_slots (array, array->slot_count);
+
+  /* Copy the pointers to buckets into the new slots. */
+  memcpy (new_slots, array->slots, (array->slot_count
+				    * sizeof (objects_array_slot_t)));
+
+  /* Sort the new slots. */
+  qsort (new_slots, array->slot_count, sizeof (objects_array_slot_t),
+	 (qsort_compare_func_t) _objects_array_compare_slots);
+
+  /* Put the newly sorted slots in the `sorted_slots' element of the
+   * array structure. */
+  array->sorted_slots = new_slots;
+
+  return;
+}
+
+objects_array_bucket_t *
+_objects_array_enumerator_next_bucket (objects_array_enumerator_t * enumerator)
+{
+  if (enumerator->is_sorted)
+    {
+      if (enumerator->is_ascending)
+	{
+	  if (enumerator->array->sorted_slots == NULL)
+	    return NULL;
+
+	  if (enumerator->index < enumerator->array->element_count)
+	    {
+	      objects_array_bucket_t *bucket;
+
+	      bucket = enumerator->array->sorted_slots[enumerator->index];
+	      ++(enumerator->index);
+	      return bucket;
+	    }
+	  else
+	    return NULL;
+	}
+      else
+	{
+	  if (enumerator->array->sorted_slots == NULL)
+	    return NULL;
+
+	  if (enumerator->index > 0)
+	    {
+	      objects_array_bucket_t *bucket;
+
+	      --(enumerator->index);
+	      bucket = enumerator->array->sorted_slots[enumerator->index];
+	      return bucket;
+	    }
+	  else
+	    return NULL;
+	}
+    }
+  else
+    {
+      objects_array_bucket_t *bucket;
+
+      if (enumerator->array->slots == NULL)
+	return NULL;
+
+      for (bucket = NULL;
+	   (enumerator->index < enumerator->array->slot_count
+	    && bucket == NULL);
+	   ++(enumerator->index))
+	{
+	  bucket = enumerator->array->slots[enumerator->index];
+	}
+
+      return bucket;
+    }
+}
+
+/** Statistics **/
+
+size_t
+objects_array_count (objects_array_t * array)
+{
+  return array->element_count;
+}
+
+size_t
+objects_array_capacity (objects_array_t * array)
+{
+  return array->slot_count;
+}
+
+int
+objects_array_check (objects_array_t * array)
+{
+  return 0;
+}
+
+int
+objects_array_is_empty (objects_array_t * array)
+{
+  return objects_array_count (array) != 0;
+}
+
+/** Emptying **/
+
+void
+objects_array_empty (objects_array_t * array)
+{
+  size_t c;
+
+  /* Just empty each slot out, one by one. */
+  for (c = 0; c < array->slot_count; ++c)
+    _objects_array_empty_slot (array, array->slots + c);
+
+  return;
+}
+
+/** Creating **/
+
+objects_array_t *
+objects_array_alloc_with_allocs (objects_allocs_t allocs)
+{
+  objects_array_t *array;
+
+  /* Get a new array. */
+  array = _objects_array_alloc_with_allocs (allocs);
+
+  return array;
+}
+
+objects_array_t *
+objects_array_alloc (void)
+{
+  return objects_array_alloc_with_allocs (objects_allocs_standard ());
+}
+
+objects_array_t *
+objects_array_with_allocs (objects_allocs_t allocs)
+{
+  return objects_array_init (objects_array_alloc_with_allocs (allocs));
+}
+
+objects_array_t *
+objects_array_with_allocs_with_callbacks (objects_allocs_t allocs,
+					  objects_callbacks_t callbacks)
+{
+  return objects_array_init_with_callbacks (objects_array_alloc_with_allocs (allocs),
+					    callbacks);
+}
+
+objects_array_t *
+objects_array_with_callbacks (objects_callbacks_t callbacks)
+{
+  return objects_array_init_with_callbacks (objects_array_alloc (), callbacks);
+}
+
+objects_array_t *
+objects_array_of_char_p (void)
+{
+  return objects_array_with_callbacks (objects_callbacks_for_char_p);
+}
+
+objects_array_t *
+objects_array_of_void_p (void)
+{
+  return objects_array_with_callbacks (objects_callbacks_for_void_p);
+}
+
+objects_array_t *
+objects_array_of_owned_void_p (void)
+{
+  return objects_array_with_callbacks (objects_callbacks_for_owned_void_p);
+}
+
+objects_array_t *
+objects_array_of_int (void)
+{
+  return objects_array_with_callbacks (objects_callbacks_for_int);
+}
+
+objects_array_t *
+objects_array_of_id (void)
+{
+  return objects_array_with_callbacks (objects_callbacks_for_id);
+}
+
+/** Initializing **/
+
+objects_array_t *
+objects_array_init_with_callbacks (objects_array_t * array, objects_callbacks_t callbacks)
+{
+  if (array != NULL)
+    {
+      /* The default capacity is 15. */
+      size_t capacity = 15;
+
+      /* Record the element callbacks. */
+      array->callbacks = objects_callbacks_standardize (callbacks);
+
+      /* Initialize ARRAY's information. */
+      array->element_count = 0;
+      array->slot_count = capacity + 1;
+
+      /* Make some new slots. */
+      array->slots = _objects_array_new_slots (array, capacity + 1);
+
+      /* Get the sorted slots ready for later use. */
+      array->sorted_slots = NULL;
+    }
+
+  return array;
+}
+
+objects_array_t *
+objects_array_init (objects_array_t * array)
+{
+  return objects_array_init_with_callbacks (array,
+					    objects_callbacks_standard());
+}
+
+objects_array_t *
+objects_array_init_from_array (objects_array_t * array, objects_array_t * old_array)
+{
+  objects_array_enumerator_t enumerator;
+  size_t index;
+  void *element;
+
+  /* Initialize ARRAY in the usual way. */
+  objects_array_init_with_callbacks (array,
+			       objects_array_element_callbacks (old_array));
+
+  /* Get an enumerator for OLD_ARRAY. */
+  enumerator = objects_array_enumerator (old_array);
+
+  /* Step through OLD_ARRAY's elements, putting them at the proper
+   * index in ARRAY. */
+  while (objects_array_enumerator_next_index_and_element (&enumerator,
+							  &index, &element))
+    {
+      objects_array_at_index_put_element (array, index, element);
+    }
+
+  return array;
+}
+
+/** Destroying **/
+
+void
+objects_array_dealloc (objects_array_t * array)
+{
+  if (array != NULL)
+    {
+      /* Empty out ARRAY. */
+      objects_array_empty (array);
+
+      /* Free up its slots. */
+      _objects_array_free_slots (array, array->slots);
+
+      /* FIXME: What about ARRAY's sorted slots? */
+
+      /* Free up ARRAY itself. */
+      _objects_array_dealloc (array);
+    }
+
+  return;
+}
+
+/** Searching **/
+
+void *
+objects_array_element_at_index (objects_array_t * array, size_t index)
+{
+  objects_array_bucket_t *bucket = _objects_array_bucket_for_index (array, index);
+
+  if (bucket != NULL)
+    return bucket->element;
+  else
+    /* If `bucket' is NULL, then the requested index is unused. */
+    /* There's no bucket, so... */
+    return objects_array_not_an_element_marker (array);
+}
+
+size_t
+objects_array_index_of_element (objects_array_t * array, void *element)
+{
+  size_t i;
+
+  for (i = 0; i < array->slot_count; ++i)
+    {
+      objects_array_bucket_t *bucket = array->slots[i];
+
+      if (bucket != NULL)
+	if (objects_is_equal (objects_array_element_callbacks (array),
+			      bucket->element,
+			      element,
+			      array))
+	  return bucket->index;
+    }
+
+  return i;
+}
+
+int
+objects_array_contains_element (objects_array_t * array, void *element)
+{
+  /* Note that this search is quite inefficient. */
+  return objects_array_index_of_element (array, element) < (array->slot_count);
+}
+
+void **
+objects_array_all_elements (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+  void **elements;
+  size_t count, i;
+
+  count = objects_array_count (array);
+
+  /* Set aside space to hold the elements. */
+  elements = (void **) objects_calloc (objects_array_allocs (array),
+				       count + 1,
+				       sizeof (void *));
+
+  enumerator = objects_array_enumerator (array);
+
+  for (i = 0; i < count; ++i)
+    objects_array_enumerator_next_element (&enumerator, elements + i);
+
+  elements[i] = objects_array_not_an_element_marker (array);
+
+  /* We're done, so heave it back. */
+  return elements;
+}
+
+void **
+objects_array_all_elements_ascending (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+  void **elements;
+  size_t count, i;
+
+  count = objects_array_count (array);
+
+  /* Set aside space to hold the elements. */
+  elements = (void **) objects_calloc (objects_array_allocs (array),
+				       count + 1,
+				       sizeof (void *));
+
+  enumerator = objects_array_ascending_enumerator (array);
+
+  for (i = 0; i < count; ++i)
+    objects_array_enumerator_next_element (&enumerator, elements + i);
+
+  elements[i] = objects_array_not_an_element_marker (array);
+
+  /* We're done, so heave it back. */
+  return elements;
+}
+
+void **
+objects_array_all_elements_descending (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+  void **elements;
+  size_t count, i;
+
+  count = objects_array_count (array);
+
+  /* Set aside space to hold the elements. */
+  elements = (void **) objects_calloc (objects_array_allocs (array),
+				       count + 1,
+				       sizeof (void *));
+
+  enumerator = objects_array_descending_enumerator (array);
+
+  for (i = 0; i < count; ++i)
+    objects_array_enumerator_next_element (&enumerator, elements + i);
+
+  elements[i] = objects_array_not_an_element_marker (array);
+
+  /* We're done, so heave it back. */
+  return elements;
+}
+
+/** Removing **/
+
+void
+objects_array_remove_element_at_index (objects_array_t * array, size_t index)
+{
+  objects_array_bucket_t *bucket;
+
+  /* Get the bucket that might be there. */
+  bucket = _objects_array_bucket_for_index (array, index);
+
+  /* If there's a bucket at the index, then we empty its slot out. */
+  if (bucket != NULL)
+    _objects_array_empty_slot (array, _objects_array_slot_for_index (array, index));
+
+  /* Finally, we return. */
+  return;
+}
+
+void
+objects_array_remove_element_known_present (objects_array_t * array,
+					    void *element)
+{
+  objects_array_remove_element_at_index (array,
+				      objects_array_index_of_element (array,
+								  element));
+  return;
+}
+
+void
+objects_array_remove_element (objects_array_t * array, void *element)
+{
+  if (objects_array_contains_element (array, element))
+    objects_array_remove_element_known_present (array, element);
+
+  return;
+}
+
+/** Adding **/
+
+void *
+objects_array_at_index_put_element (objects_array_t * array,
+				    size_t index,
+				    void *element)
+{
+  objects_array_bucket_t *bucket;
+
+  /* Clean out anything that's already there. */
+  objects_array_remove_element_at_index (array, index);
+
+  /* Make a bucket for our information. */
+  bucket = _objects_array_new_bucket (array, index, element);
+
+  /* Put our bucket in the array. */
+  _objects_array_insert_bucket (array, bucket);
+
+  return element;
+}
+
+/** Enumerating **/
+
+objects_array_enumerator_t
+objects_array_ascending_enumerator (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+
+  enumerator.array = array;
+  enumerator.is_sorted = 1;
+  enumerator.is_ascending = 1;
+  enumerator.index = 0;
+
+  _objects_array_make_sorted_slots (array);
+
+  return enumerator;
+}
+
+objects_array_enumerator_t
+objects_array_descending_enumerator (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+
+  enumerator.array = array;
+  enumerator.is_sorted = 1;
+  enumerator.is_ascending = 0;
+  /* The `+ 1' is so that we have `0' as a known ending condition.
+   * See `_objects_array_enumerator_next_bucket()'. */
+  enumerator.index = array->element_count + 1;
+
+  _objects_array_make_sorted_slots (array);
+
+  return enumerator;
+}
+
+objects_array_enumerator_t
+objects_array_enumerator (objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+
+  enumerator.array = array;
+  enumerator.is_sorted = 0;
+  enumerator.is_ascending = 0;
+  enumerator.index = 0;
+
+  return enumerator;
+}
+
+int
+objects_array_enumerator_next_index_and_element (objects_array_enumerator_t * enumerator,
+						 size_t * index,
+						 void **element)
+{
+  objects_array_bucket_t *bucket;
+
+  bucket = _objects_array_enumerator_next_bucket (enumerator);
+
+  if (bucket != NULL)
+    {
+      if (element != NULL)
+	*element = bucket->element;
+      if (index != NULL)
+	*index = bucket->index;
+      return 1;
+    }
+  else
+    {
+      if (element != NULL)
+	*element = objects_array_not_an_element_marker (enumerator->array);
+      if (index != NULL)
+	*index = 0;
+      return 0;
+    }
+}
+
+int
+objects_array_enumerator_next_element (objects_array_enumerator_t * enumerator,
+				       void **element)
+{
+  return objects_array_enumerator_next_index_and_element (enumerator,
+							  NULL,
+							  element);
+}
+
+int
+objects_array_enumerator_next_index (objects_array_enumerator_t * enumerator,
+				     size_t * index)
+{
+  return objects_array_enumerator_next_index_and_element (enumerator,
+							  index,
+							  NULL);
+}
+
+/** Comparing **/
+
+int
+objects_array_is_equal_to_array (objects_array_t * array1, objects_array_t * array2)
+{
+  size_t a, b;
+  void *m, *n;
+  objects_array_enumerator_t e, f;
+
+  a = objects_array_count (array1);
+  b = objects_array_count (array2);
+
+  if (a < b)
+    return (b - a);
+  if (a > b)
+    return (a - b);
+
+  /* Get ascending enumerators for each of the two arrays. */
+  e = objects_array_ascending_enumerator (array1);
+  e = objects_array_ascending_enumerator (array1);
+
+  while (objects_array_enumerator_next_index_and_element (&e, &a, &m)
+	 && objects_array_enumerator_next_index_and_element (&f, &b, &n))
+    {
+      int c, d;
+
+      if (a < b)
+	return (b - a);
+      if (a > b)
+	return (a - b);
+
+      c = objects_compare (objects_array_element_callbacks (array1), m, n, array1);
+      if (c != 0)
+	return c;
+
+      d = objects_compare (objects_array_element_callbacks (array2), n, m, array2);
+      if (d != 0)
+	return d;
+    }
+
+  return 0;
+}
+
+/** Mapping **/
+
+objects_array_t *
+objects_array_map_elements (objects_array_t * array,
+			    void *(*fcn) (void *, void *),
+			    void *user_data)
+{
+  /* FIXME: Code this. */
+  return array;
+}
+
+/** Miscellaneous **/
+
+objects_hash_t *
+objects_hash_init_from_array (objects_hash_t * hash, objects_array_t * array)
+{
+  objects_array_enumerator_t enumerator;
+  void *element;
+
+  /* NOTE: If ARRAY contains multiple elements of the same equivalence
+   * class, it is indeterminate which will end up in HASH.  This
+   * shouldn't matter, though. */
+  enumerator = objects_array_enumerator (array);
+
+  /* Just walk through ARRAY's elements and add them to HASH. */
+  while (objects_array_enumerator_next_element (&enumerator, &element))
+    objects_hash_add_element (hash, element);
+
+  return hash;
+}
+
+// objects_chash_t *
+// objects_chash_init_from_array (objects_chash_t * chash, objects_array_t * array)
+// {
+//   objects_array_enumerator_t enumerator;
+//   void *element;
+// 
+//   /* NOTE: If ARRAY contains multiple elements of the same equivalence
+//    * class, it is indeterminate which will end up in CHASH.  This
+//    * shouldn't matter, though. */
+//   enumerator = objects_array_enumerator (array);
+// 
+//   /* Just walk through ARRAY's elements and add them to CHASH. */
+//   while (objects_array_enumerator_next_element (&enumerator, &element))
+//     objects_chash_add_element (chash, element);
+// 
+//   return chash;
+// }
+