The information about collections is organized in the following manner:

• Collections Overview
• Requirements for Applications Using Collections
• Introductory Collections Example
• Choosing a Collection Type
• Collection Characteristics and Behaviors
• Templated and Nontemplated Collections
• Creating Collections
• Destroying Collections
• Inserting Collection Elements
• Removing Collection Elements with remove()
• Testing Collection Membership with contains()
• Finding the Count of an Element with count()
• Finding the Size of a Collection with cardinality()
• Using Cursors for Navigation
• Accessing Collection Elements with a Cursor or Numerical Index
• Traversing Collections with Default Cursors
• Copying, Combining, and Comparing Collections
• Dictionaries
• Writing Destructors for Dictionaries
• Example: Using Dictionaries

In order to implement collection functionality, the ObjectStore collection facility provides

• A library of collection classes
• Facilities that allow traversal, manipulation, and retrieval of the elements within collections

Because collections are pointers to objects - rather than the objects themselves - an object can be contained in many different collections. Furthermore, collections can be used in transient or persistent memory, depending on the needs of your application.

Collection Query and Manipulation Features

The ObjectStore collection facility gives you a great deal of control over the behavior and representation of the collections you create. Other collection facilities allow you to iterate over the elements in a collection, and to query collections for elements meeting simple or sophisticated sorting criteria.

This allows you, for example, to create either ordered or unordered collections, and collections that either do or do not allow duplicates. You can also choose from among a group of system-supplied collection representations, such as hash tables and packed lists. You can even specify how a collection's representation is to change in response to changes in the collection's size.

Collections are commonly used to model many-valued attributes, and they can also be used as class extents (which hold all instances of a particular class). Collections of one type - dictionaries - associate a key with each element or group of elements, and so can be used to model binary associations or mappings. ObjectStore dictionaries are described in detail in Dictionaries.

Requirements for Applications Using Collections

• All applications that use collections must include the collections header files and initialize the collections facility.
• They must also generate schema using the collections/queries library schemas and link in the collections/queries libraries.
• Applications using dictionaries must also mark each type of dictionary in a schema source file.

If your application uses ObjectStore dictionaries, your program must include <ostore/coll/dict_pt.hh> and must also include <ostore/coll/dict_pt.cc> in any source file that instantiates an os_Dictionary, following the other header files. See ObjectStore Header Files in Chapter 2, Working with Source Files, of ObjectStore Building C++ Interface Applications.

Initializing the Collection Facility

objectstore::initialize();
os_collection::initialize();

Using Persistent Collections

Using Persistent Dictionaries

      OS_MARK_DICTIONARY( key-type,  element-type)

Thread Locking

      static void set_thread_locking(os_boolean) ;

Introductory Collections Example

Note, though, that because the functionality is so rich and varied, the collections facilities add overhead to your code and database; if your application does not require collections, a simple linked list you can write yourself might be a more suitable choice.

Using the Example: Linked List of Notes as a base, the following example illustrates how to use collections.

Header file: note.hh

      #include <iostream.h>
      #include <string.h>
      #include <ostore/ostore.hh>
      #include <ostore/coll.hh>
      /* A simple class which records a note entered by the user. */
      class note {
            public:
                  /* Public Member functions */
                  note(const char*, int);
                  ~note();
                  void display(ostream& = cout);
                  static os_typespec* get_os_typespec();
                  /* Public Data members */
                  char* user_text;
                  int   priority;
      };

      /* ++ Note Program - main file */
      #include "note.hh"
      extern "C" void exit(int);
      extern "C" int atoi(char*);
      /* Head of linked-list of notes */
      os_list *notes = 0;
      const int note_text_size = 100;
      main(int argc, char** argv) {
            if(argc!=2) {
                  cout << "Usage: note <database>" << endl;
                  exit(1);
            } /* end if */
            objectstore::initialize();
            os_collection::initialize();
            char buff[note_text_size];
            char buff2[note_text_size];
            int  note_priority;
            os_database *db = os_database::open(argv[1], 0, 0644);
            OS_BEGIN_TXN(t1,0,os_transaction::update) {
                  os_database_root *root_head = db->find_root("notes");
                  if(!root_head) 
                        root_head = db->create_root("notes");
                  notes = (os_list *)root_head->get_value();
                  if(!notes) {
                        notes = &os_list::create(db);
                        root_head->set_value(notes);
                  } /* end if */
                  os_cursor c(*notes);
                  /* Display existing notes */
                  for(note* n=(note *)c.first(); n; n=(note *)c.next())
                        n->display();
                  /* Prompt user for a new note */
                  cout << "Enter a new note: "<< flush;
                  cin.getline(buff, sizeof(buff));
                  /* Prompt user for a note priority */
                  cout << "Enter a note priority: "<< flush;
                  cin.getline(buff2, sizeof(buff2));
                  note_priority = atoi(buff2);
                  notes->insert(new(db, note::get_os_typespec())
                        note(buff, note_priority) );
            }
            OS_END_TXN(t1)
            db->close();
      }

Note that all the collection types described below (with the exception of os_Dictionary) have both a templated (parameterized) and a nontemplated (nonparameterized) version. For ease of differentiation, the templated versions use uppercase letters (for example, os_Set) whereas the nontemplated versions use lowercase (os_set). Nontemplated classes are always typed as void* pointers.

For information on

• Differences between templated (parameterized) and nontemplated (nonparameterized) collection classes, see Templated and Nontemplated Collections.
• Characteristics of ObjectStore collection classes - such as their representations, sizes, and default behaviors - see Collection Characteristics and Behaviors.
• A hierarchical representation of the relationships between the ObjectStore collection types, see the Class Hierarchy Diagram.
• How to create collection classes, see Creating Collections.

Besides lacking order, something that distinguishes sets from some other types of collections is that they do not allow multiple occurrences of the same element. This means that inserting a value that is already an element of a set either leaves the set unchanged or causes the signaling of a run-time exception (depending on the behavior you have specified for the set). In either case, sets disallow duplicates.

os_Bag and os_bag

os_List and os_list

os_Collection and os_collection

The os_Collection class permits you to change these and other behaviors mentioned above for an os_Collection. This means that an instance of os_Collection could, at one point in its lifetime, have set-like behavior, and at another point have bag-like or list-like behavior.

os_Array and os_array

os_Dictionary and os_rDictionary

Dictionaries are somewhat different from other ObjectStore collection classes in their use of keys. See Dictionaries for additional information on how dictionaries differ from other kinds of ObjectStore collections.

Using a Decision Tree to Select a Collection Type

Here is a simple decision tree to help you choose a collection type to suit particular behavioral requirements

.

Collection Characteristics and Behaviors

Collections Can Be Transient or Persistent

Parameterized and Nonparameterized Collections

Templated classes use uppercase letters in their class names (os_Set), whereas nontemplated classes use lowercase letters in their class names (os_set).

Class Hierarchy Diagram

Collection Behaviors

Note that os_Dictionary differs substantially from other collections classes in its behaviors. Dictionary behaviors are related to the key of an element rather than to an element itself. See Dictionaries for information on how ObjectStore dictionaries differ from other ObjectStore collection classes. See also Creating Dictionaries.

Expected Collection Size

Performing pick() on an Empty Set

Collection Representations

Collections created by create()

Representations for embedded collections

Note that expected_size determines the collection's initial representation. So, for example, if you set the expected_size for an os_Set to 21, os_dyn_hash is used for an os_Set's collection's entire lifetime. (This can, however, be customized; see Customizing Collection Representation in Chapter 4, Advanced Collections, of the ObjectStore Advanced C++ API User Guide).

Representations used for os_Dictionary are discussed separately in Dictionary Representation.

Templated and Nontemplated Collections

Using Collections with the Element Type Parameter

      os_Set<part*> &a_part_set = os_Set<part*>::create(db1) ;

Example: os_Set

      #include <ostore/ostore.hh>
      #include <ostore/coll.hh>
      class part {
            public:
                  int part_number;
                  os_Set<part*> &children;
                  employee *responsible_engineer;
                  part (int n) : 
                        children(os_Set<part*>::create(db1)){
                              part_number = n;
                              responsible_engineer = 0;
                        }
      };

You can choose to use the following nonparameterized collection classes.

Notice that the names of the parameterized classes have an uppercase letter following the os_, while the nonparameterized classes have a lowercase letter following the os_. Notice, as well, that there is no nonparameterized version of os_Dictionary.

Difference between parameterized and nonparameterized interfaces

Most of the examples in this manual use the parameterized interface, but if you are not using parameterization, just drop any construct of the form

      < element-type-name>

Example: os_set()

      class employee ;
      extern os_database *db1 ;
      class part {
            public:
                  int part_number ;
                  os_set &children ;
                  employee *responsible_engineer ;
                  part (int n) : 
                        children(os_set::create(db1)){
                              part_number = n;
                              responsible_engineer = 0 ;
                  }
      };

Nonparameterized collections are typed void*

Creating Collections

General Guidelines

The create method is a wrapper for constructors. For example:

      static os_Collection<E> & os_Collection<E*>::create(
                  os_database *db,
                  os_unsigned_int32 behavior = 0,
                  os_int32 expected_size = 0
      )

Do not use new to create collections.

Generally, it is preferable to use the create() function for each type of collection, as it results in better performance and better locality of reference because of its underlying optimization for mutation.

Each collection class has a destroy() function that deletes a specified collection. See Destroying Collections for more information. You can also call delete() to destroy a collection created with ::create().

Use a constructor only for stack-based collections or collections embedded directly within another class. However, avoid embedding collections directly. Instead, embed collections as pointers or references, and call the create() function in a constructor initialization list.

create() functions

All other arguments are optional, because they are declared with default values.

Constructor functions

Customizing collections

To find out how to

• Modify the size of the set, see Specifying Expected Size in Chapter 4 of the ObjectStore Advanced C++ API User Guide.
• Modify the behavior of the set, see Customizing Collection Behavior in Chapter 4 of the ObjectStore Advanced C++ API User Guide.
• Modify a set's representation, see Customizing Collection Representation in Chapter 4 of the ObjectStore Advanced C++ API User Guide.

You can create dictionaries with os_Dictionary::create() or an os_Dictionary constructor. Use the constructor only for stack-based arrays, or arrays embedded directly within another object. If you want to use a reference-based dictionary, use the os_rDictionary functions.

os_Dictionary::
create()

The os_Dictionary::create() overloadings require not only the element type parameter but the key type parameter as well. See Using Collections with the Element Type Parameter for information about the element type parameter, and "Key type parameter", below, for information about the key type parameter.

os_Dictionary::
os_Dictionary()

In general, it is preferable to use os_Dictionary::create(), as it results in higher performance and better locality of reference because of its underlying optimization for mutation.

Key type parameter

Integer keys

For integer keys, specify one of the following as key type:

• os_int32 (a signed 32-bit integer)
• os_unsigned_int32 (an unsigned 32-bit integer)
• os_int16 (a signed 16-bit integer)
• os_unsigned_int16 (an unsigned 16-bit integer) Class keys

void* keys

Use the type void* for pointer keys other than char* keys.

char* keys

For char[] keys, use the parameterized type os_char_array<S>, where the actual parameter is an integer literal indicating the size of the array in bytes.

If a dictionary's key type is char*, the dictionary makes its own copies of the character array upon insert. If the dictionary does not allow duplicate keys, you can significantly improve performance by using the type os_char_star_nocopy as the key type. With this key type the dictionary copies the pointer to the array and not the array itself. You can freely pass chars to this type.

Note that you should not use os_char_star_nocopy with dictionaries that allow duplicate keys.

char[], char*, and os_char_star_nocopy all use strcmp for comparison.

Destroying Collections

      static void os_Collection::destroy(os_Collection<E>&) ;
      static void os_Set::destroy(os_Set<E>&) ;
      static void os_Bag::destroy(os_Bag<E>&) ;
      static void os_List::destroy(os_List<E>&) ;
      static void os_Array::destroy(os_Array<E>&) ;
      static void os_Dictionary::destroy(os_Dictionary<K, E>&) ;

All the collection class destroy() functions are described in Chapter 2, Collection, Query, and Index Classes, of the ObjectStore Collections C++ API Reference.

Inserting Collection Elements

      void insert(const E) ;

Inserting Dictionary Elements

      void insert(const K &key, const E element) ;
      void insert(const K *key_ptr, const E element) ;

Caution

Duplicate Insertions

      os_database *db1 ;
      message *a_msg ;
      os_Set<message*> &temp_set = 
            os_Set<message*>::create(db1) ;
      . . .
      temp_set.insert(a_msg) ;
      temp_set.insert(a_msg) ;  /* set is unchanged */

For collections with allow_duplicates behavior, each insertion increases the collection's size by one and increases by one the count (or number of occurrences) of the inserted element in the collection. You can retrieve the count of a given element with count(). Iteration with an unrestricted cursor visits each occurrence of each element.

Null Insertions

Ordered Collections

Duplicate Keys

Changing a Collection's Behavior

Changing a Collection's Representation Policy

Removing Collection Elements with remove()

      os_int32 remove(E) ;

      os_database *db1 ;
      message *a_msg; . . .
      os_Set<message*> &temp_set =
            os_Set<message*>::create(db1) ;
      . . .
      temp_set.remove(a_msg) ;
      temp_set.remove(a_msg) ;  /* set is unchanged */

Removing Dictionary Elements

      void remove(const K &key, const E element) ;
      void remove(const K *key_ptr, const E element) ;

With dictionaries, you can also remove a specified number of entries with a specified key with these functions:

      E remove_value(const K &key, os_unsigned_int32 n = 1) ;
      E remove_value(const K *key_ptr, os_unsigned_int32 n = 1) ;

Caution regarding duplicate insertions

Testing Collection Membership with contains()

      os_int32 contains(E) const ;

Dictionaries

      os_boolean contains(
            const K const &key_ref, 
            const E element
      ) const ;
      os_boolean contains(
            const K *key_ptr, 
            const E element
      ) const ;

Finding the Count of an Element with count()

      os_int32 count(E e) ;

Dictionaries

os_unsigned_int32 count_values(const K const &key_ref) const ;
os_boolean contains(const K *key_ptr) const ;

Finding the Size of a Collection with cardinality()

      os_unsigned_int32 cardinality() const ;

Checking for an Empty Collection with empty()

      os_int32 empty() ;

Using Cursors for Navigation

• The os_index_path class is described in Using Paths in Navigation in Chapter 4 of the ObjectStore Advanced C++ API User Guide. See also os_index_path in the ObjectStore Collections C++ API Reference.
• The os_coll_range class is described in Using Ranges in Navigation in Chapter 4 of the ObjectStore Advanced C++ API User Guide. See also os_coll_range in the ObjectStore Collections C++ API Reference.

Cursors

When you create a vanilla cursor with no index path or collection range, you specify its associated collection, and the cursor is positioned at the collection's first element. With members of os_Cursor, you can reposition the cursor, as well as retrieve the element at which the cursor is currently positioned. See Traversing Collections with Default Cursors.

Some members of the collection classes take cursor arguments. These functions support insertion, removal, and replacement of elements. See Accessing Collection Elements with a Cursor or Numerical Index.

Accessing Collection Elements with a Cursor or Numerical Index

      void os_Collection::insert_after(const E, const os_Cursor<E>&)
      void os_Collection::insert_after(const E, os_unsigned_int32)
      void os_Collection::insert_before(const E, 

            const os_Cursor<E>&)
      void os_Collection::insert_before(const E, os_unsigned_int32)
      void os_Collection::remove_at(const os_Cursor<E>&)
      void os_Collection::remove_at(os_unsigned_int32)
      E os_Collection::replace_at(const E, const os_Cursor<E>&)
      E os_Collection::replace_at(const E, os_unsigned_int32)
      E os_Collection::retrieve(const os_Cursor<E>&) const
      E os_Collection::retrieve(os_unsigned_int32) const

Manipulating first and last elements in a collection

      void os_Collection::insert_first(const E)
      void os_Collection::insert_last(const E)
      os_int32 os_Collection::remove_first(const E&)
      E os_Collection::remove_first()
      os_int32 os_Collection::remove_last(const E&)
      E os_Collection::remove_last()

If you perform any of these functions on an unordered collection created with the supertypes interface, the exception err_coll_not_supported is signaled. These operations will cause a compile-time error if performed on an unordered collection created with the subtypes interface. (Compile-time detection is possible because the unordered subtypes define the ordered operations as private.)

Traversing Collections with Default Cursors

To traverse a collection, you create a cursor, an instance of the parameterized class os_Cursor, associated with the collection you want to traverse. The cursor records the state of an iteration by pointing to the element currently being visited. Each time through the loop, you advance the cursor to the next element and retrieve that element. Here is an example:

Example: iterating through a collection with os_Cursor

      os_database *db1 ;
      . . .
      os_Collection<person*> &people
            = os_Collection<person*>::create(db1) ; 
       . . . /* insertions into people */
      os_Collection<person*> &teenagers
            = os_Collection<person*>::create(db1);
      person* p;
      os_Cursor<person*> c(people);
      for (p = c.first(); c.more() ; p = c.next())
            if (p->age >=13 && p->age <= 19)
                  teenagers.insert(p);

Creating Default Cursors

      os_Cursor(const os_Collection<E> &) ;

Note that traversal of a collection with duplicates visits each element once for each time it occurs in the collection. For example, an element that occurs three times in a collection will be visited three times during a traversal of the collection.

os_Cursor's parameter (person* in the example) indicates the type of elements in the collection being traversed. So the cursor's parameter must be the element type (see Using Collections with the Element Type Parameter) of the collection passed as the constructor argument.

os_Cursor::first()

      p = c.first()

os_Cursor::next()

      p = c.next()

os_Cursor::more()

      c.more()

After next() is applied to the collection's last element, the cursor becomes null, and more() then returns false, terminating the loop.

Alternative to using more()

      os_database *db1 ;
      . . .
      os_Collection<person*> &people
            = os_Collection<person*>::create(db1) ; 
       . . .  /* inserts to people */
      os_Collection<person*> &teenagers
            = os_Collection<person*>::create(db1) ;
      person* p ;
      os_Cursor<person*> c(people) ;
      for ( p = c.first() ; p ; p = c.next() )
            if ( p->age >=13 && p->age <= 19 )
                  teenagers.insert(p) ;

      void rebind(const os_Collection<E>&) ;
      void rebind(const os_Collection<E>&, _Rank_fcn) ;

This last overloading is for rebinding cursors whose order is specified by a rank function. See Path-Based Traversal in Chapter 4, Advanced Collections, of the ObjectStore Advanced C++ API User Guide.

Copying, Combining, and Comparing Collections

Collection comparison operators

• operator =() replaces the contents of LHS with the contents of RHS.
• operator |=() adds the contents of RHS to LHS.
• operator -=() removes the contents of RHS from LHS.
• operator &=() replaces the contents of LHS with the intersection of LHS and RHS.
• operator <() (like proper subset)
• operator >() (like proper superset)
• operator <=() (like subset)
• operator >=() (like superset)
• operator ==() (checks if elements are the same)
• operator !=() (checks if any elements are different)

So, for example, you can use the union equals operator, |=, as a convenient way of performing inserts:

      os_Collection<message*> &a_set
            = os_Collection<message*>::create(db1) ;
      message *a_msg ;
       . . . 
      a_set |= a_msg ;

      a_set -= a_msg ; 

      big_list |= little_list ;

      the_copy = the_original;

In general, the update operators (=, |=, -=, &=) bundle together a sequence of inserts or removes of elements of one or more operands in the order in which those elements appear in the operands, the default iteration order for the operands. This describes only the behavior of the operators. The implementations might be different.

For example, to add all of a part's children to a given set, you might do

      os_database *db1 ;
      . . . 
      os_List<part*> &a_list = os_List<part*>::create(db1) ; 
      part *a_part ;
       . . . 
      a_list |= a_part->children ;

      part *p ;
      os_Cursor<part*> c(a_part->children) ;
      for ( p = c.first() ; p ; p = c.next() )
            a_list.insert(p) ;

Required include files

Marking Persistent Dictionaries

      OS_MARK_DICTIONARY( key-type,  element-type)

Example: schema file

      /* schema.cc */
      #include <ostore/ostore.hh>
      #include <ostore/coll.hh>
      #include <ostore/coll/dict_pt.hh>
      #include <ostore/manschem.hh>
      #include "dnary.hh"
      OS_MARK_DICTIONARY(void*,Course*) ;
      OS_MARK_DICTIONARY(int,Employee**) ;
      OS_MARK_DICTIONARY(int,Course*) ;
      OS_MARK_SCHEMA_TYPE(Course) ;
      OS_MARK_SCHEMA_TYPE(Employee) ;
      OS_MARK_SCHEMA_TYPE(Department) ;

The OS_MARK_DICTIONARY() macro is described in ObjectStore Collections C++ API Reference.

Marking Transient Dictionaries

However, using OS_TRANSIENT_DICTIONARY() more than once with the same key type will result in a complication error. For example, the following will not compile correctly:

      OS_TRANSIENT_DICTIONARY(int,void*);
      OS _TRANSIENT_DICTIONARY(int,foo*);

      OS_TRANSIENT_DICTIONARY(int,void*);
      OS _TRANSIENT_DICTIONARY_NOKEY(int,foo*);

Dictionary Behavior

• Its entries have no intrinsic order.
• Duplicate elements are allowed.
• Null pointers cannot be inserted.
• No guarantees are made concerning whether an element inserted or removed during a traversal of its elements will be visited later in that same traversal.

• Performing pick() on an empty dictionary raises err_coll_empty.
• Duplicate keys are allowed; that is, two or more elements can have the same key.
• Range lookups are not supported; that is, key order is not maintained.

Dictionary Representation

In addition to the key type and element type parameters, the class os_rDictionary also has a reference type parameter, whose actuals are ObjectStore reference types. Specify either os_reference or os_reference_version.

The os_rDictionary class is described in the ObjectStore Collections C++ API Reference.

Visiting the Elements with Specified Keys

      os_Cursor<E> (
            const os_dictionary & coll, 
            const os_coll_range &range,
            os_int32 options = os_cursor::unsafe
      ) ;

Picking the Element with a Specified Key

      E pick(const K const &key_ref) const ;
      E pick(const K *key_ptr) const ;

Retrieving ranges of elements

      E pick(const os_coll_range&) const ;

      a_dictionary.pick( os_coll_range(GE, 100) )

As with the other pick() overloadings, if there is more than one such element, an arbitrary one is picked and returned. If there is no such element and the collection has pick_from_empty_returns_null behavior, 0 is returned. If there is no such element and the dictionary does not have pick_from_empty_returns_null behavior, err_coll_empty is signaled.

Retrieving elements when the key type is a class

The key types char*, char[ ], and os_char_star_nocopy are each treated as a class whose rank and hash functions are defined in terms of strcmp(). For example, for char*:

      a_dictionary.pick("Smith") 

Writing Destructors for Dictionaries

When a key is removed, the destructor for the object of type K is run. Because the slot can then be reused, it is necessary for the destructor for the object of type K to null out any pointers to memory that get freed in the destructor.

Here is an example where type K is class myString:

class myString
{
      private:
            char* theString;
            int  len;
}
RMString::RMString(char* theChars)
{
      if (theChars == 0)
            len = 0;
      else
            len = strlen(theChars);
      theString = new(os_segment::of(this),
      os_typespec::get_   char(),len + 1)
                  char[len+1];
      if (theChars == 0)
            theString[0] = `\0';
      else
            strcpy(theString, theChars);
}
RMString::~RMString()
{
      delete[] theString;
/******************************************************
      The following line solves the multiple delete problem
********************************************************/
      theString = 0;
}

Invalid argument to operator delete

<err-0025-0608>Delete failed. Cannot locate a persistent object at address 0x5780114 (err_invalid_deletion)

Example: Using Dictionaries

Each Student object contains two dictionaries that serve to associate a course with the grade the student got in the course. One dictionary supports lookup of the grade given the course, and the other supports lookup of the courses with a given grade.

Note that the dnary.cc example includes <ostore/coll/dict_pt.cc> instead of dict_pt.hh, and is needed since it contains the bodies of the functions declared in dict_pt.hh. You do not need to also include dict_pt.hh because it is included in dict_pt.cc. Finally, there is the file schema.cc, a schema source file.

Below is the file dnary.hh, which contains the class definitions. After that is the file dnary.cc, which contains the member function implementations.

Header file: dnary.hh

/* dnary.hh */
#include <ostore/ostore.hh>
#include <ostore/coll.hh>
#include <ostore/coll/dict_pt.hh>
#include <iostream.h>
#include <stdlib.h>
class Student ;
class Grade ;
class Course ;
class Student {
      public:
            int get_id() const ; 
            const os_Collection<Course*> &get_courses() const ; 
            int add_course( Course*, Grade* = 0 ) ;
            void remove_course(Course*) ;
            Grade *get_grade_for_course(const Course*) const ;
            void set_grade_for_course(Course*, Grade*) ;
            os_Collection<Course*> &get_courses_with_grade(
                        const Grade* ) const ;
            float get_gpa() const ;
            static os_typespec *get_os_typespec() ;
            Student(int id, os_segment*);
            ~Student() ;
      private:
            int id ;
            os_Collection<Course*> & courses ;
            os_Dictionary<const void*, Grade* & course_grade ;
            os_Dictionary<void*, Course* & grade_course ;
} ;
class Grade {
      public: 
            const char *get_name() const ;
            float get_value() const ;
            static os_typespec *get_os_typespec() ;
            Grade(const char *name, float value, os_segment*) ;
            ~Grade() ;
      private:
            char *name ;
            float value ;
} ;
class Course {
      public:
            int get_id() const ;
            void set_id(int) ;
            static os_typespec *get_os_typespec() ;
      private:
            int id ;
} ;

/* dnary.cc */
#include <ostore/coll/dict_pt.cc>
typedef os_Dictionary<void*,Course*> grade_course_dnary ;
typedef os_Dictionary<void*,Grade*> course_grade_dnary ;
/* Student member function implementations */
int Student::get_id() const {
      return id ;
}
const os_Collection<Course*> &Student::get_courses() const {
      return courses ;
}
int Student::add_course( Course *c, Grade *g ) {
      if ( courses.contains(c) ) 
            return 0 ;
      courses.insert(c) ;
      if (g) {
            grade_course.insert(g, c) ;
            course_grade.insert(c, g) ;
      } /* end if */
      return 1 ;
}
void Student::remove_course(Course *c) {
      courses.remove(c) ;
      grade_course.remove( course_grade.pick(c), c ) ;
      course_grade.remove_value(c) ;
}
Grade *Student::get_grade_for_course(const Course *c) const {
      return course_grade.pick(c) ;
}
void Student::set_grade_for_course(Course *c, Grade *g) {
      grade_course.remove(course_grade.pick(c), c) ;
      course_grade.remove_value(c) ;
      grade_course.insert(g, c) ;
      course_grade.insert(c, g) ;
}
os_Collection<Course*> &
            Student::get_courses_with_grade(const Grade *g) const {
      os_Collection<Course*> &the_courses =
                  os_Collection<Course*>::create(
                  os_database::get_transient_database() ) ;
      os_cursor cur(grade_course, os_coll_range(
                  os_collection::EQ, g)) ;
      for ( Course *c = (Course*) cur.first() ; c ; c = (Course*) cur.next() )
            the_courses.insert(c) ;
      return the_courses ;
}
float Student::get_gpa() const {
      float sum = 0.0 ;
      os_cursor c(course_grade) ;
      for ( Grade *g = (Grade*) c.first(); g; g = (Grade*) c.next() )
                  sum = sum + g->get_value() ;
      return sum / course_grade.size() ;
}
Student::Student(int i, os_segment *seg) :
            courses(os_Collection<Course*>::create(seg)),
            course_grade(
                  os_Dictionary<const void*, Grade*>::create(seg,
                  10,os_collection::pick_from_empty_returns_null) ),
            grade_course(os_Dictionary<void*, Course*>::create(seg)) {
      id = i;
}
Student::~Student() {
      os_Collection<Course*> *courses_ptr = &courses ;
      os_Dictionary<const void*, Grade*> *course_grade_ptr =
                  &course_grade ;
      os_Dictionary<void*, Course*> *grade_course_ptr =
                  &grade_course ;
      delete courses_ptr ;
      delete course_grade_ptr ;
      delete grade_course_ptr ;
}
/* Grade member function implementations */
const char *Grade::get_name() const {
      return name ;
}
float Grade::get_value() const {
      return value ;
}
Grade::Grade(const char *n, float v, os_segment *seg) {
      name = new( seg, os_typespec::get_char(), strlen(n)+1 )
      char[strlen(n)+1] ;
      strcpy(name, n) ;
      value = v ;
}
Grade::~Grade() {
      delete name ;
}
/* Course member function implementations */
int Course::get_id() const {
      return id ;
}
void Course::set_id(int i) {
      id = i ;
}

/* schema.cc */
#include <ostore/ostore.hh>
#include <ostore/coll.hh>
#include <ostore/coll/dict_pt.hh>
#include <ostore/manschem.hh>
#include "dnary.hh"
void dummy () {
      OS_MARK_DICTIONARY(void*,Course*) ;
      OS_MARK_DICTIONARY(void*,Grade*) ;
      OS_MARK_SCHEMA_TYPE(Course) ;
      OS_MARK_SCHEMA_TYPE(Student) ;
      OS_MARK_SCHEMA_TYPE(Grade) ;
}

The data member Student::course_grade contains a reference to a dictionary that maps each course to the grade the student got for that course. This dictionary supports lookup of the grade given the course.

The data member Person::grade_course contains a reference to a dictionary that maps each grade to the courses for which the student got that grade. This dictionary supports lookup of the courses given the grade.

The function Student::add_course() first checks to see if the specified course has already been added. If it has, 0 (indicating failure) is returned. If it has not, the function inserts the specified course into the collection referred to by Student::courses. Then, if a grade is specified, entries are inserted into the dictionaries referred to by Student::course_grade and Student::grade_course. Finally, 1 (indicating success) is returned.

The function Student::remove_course() removes the specified course from Student::courses. If the course is not an element of courses, the call to remove() has no effect.

Then, using pick() on course_grade, remove_course() determines the grade for the given course. The grade and the course are then passed to os_Dictionary::remove() to remove from Student::grade_course the entry whose value is the given course. The function add_course() ensures that there is at most one.

If the course is not an element of the dictionary, pick() returns 0, and the call to remove() has no effect. Note that pick() returns 0 in this case instead of raising an exception because the dictionary (course_grade) was created with pick_from_empty_returns_null behavior.

Finally, using os_Dictionary::remove_value(), remove_course() removes from Student::Course_grade the entry whose key is the given course. Again, add_course() ensures there is at most one. If the dictionary has no entry whose key is that course, the call to remove_value() has no effect.

Student::get_grade_for_course() uses os_Dictionary::pick() to retrieve from Student::course_grade the element whose key is the given course.

Student::set_grade_for_course() first takes precautions in case the specified course already has been assigned a grade. It removes from Student::course_grade and Student::grade_course any entries with the given course. It does this as follows.

First, the function performs remove() on grade_course, passing in the grade for the given course (determined by performing pick() on course_grade), and also passing in the given course itself. If no grade has been set for the course, pick() returns 0, and the call to remove() has no effect. Then the function uses remove_value() to remove from course_grade the entry, if there is one, whose key is the given course.

Next, Student::set_grade_for_course() inserts into grade_course an entry whose key is the specified grade and whose value is the specified course. Finally, it inserts into course_grade an entry whose key is the specified course and whose value is the specified grade.

The function Student::get_courses_with_grade() returns a reference to a collection of the courses for which the student got the specified grade. It creates a collection on the transient heap, and then uses a restricted cursor to visit each element of grade_course whose key is the specified grade. As each qualifying element is visited, it is inserted into the newly created collection. Finally, a reference to the collection is returned.

The function Student::get_gpa() returns the student's grade point average. It visits each element of the dictionary course_grade, summing the result of performing get_value() on each element along the way. When the traversal is complete, the sum is divided by the dictionary's size to get the average, which is returned.

The Student constructor allocates an os_Collection and two instances of os_Dictionary in the specified segment. Note that the dictionary course_grade is created with pick_from_empty_returns_null behavior.

Updated: 03/31/98 17:00:02