Genlib's provide container statement

Syntax:

provide container collected-class in collecting-class [ byvalue ] [ keytype type keymember expression ] [ using container [ extra parameters ] ];

- or -

provide container collected-class in collecting-class [ byvalue ] singular [ using_pointer ];

Note: genlib also has a provide interface statement which is used internally by components. That version of provide is discussed in the component construction documentation and will be ignored here.

This statement is used to indicate that one class (the collecting class) holds pointers to or instances of another class (the collected class). For example, Molecule (the collecting class) may wish to keep track of all Residues (the collected class) in the Molecule. The provide container statement ensures that specific interface functions are provided to keep the tracking up-to-date and to make use of the tracking. The first form of the provide container statement is typically used for a "parent" class holding many references/instances of a "child" class (e.g. a Molecule tracking its Residues) whereas the second form is typically used for a child class that wants to be able to refer back to its parent class.

Optional Clauses

First form (aggregate collection)

If the using clause is specified, an implementation of the interface functions using the specified container will be generated; otherwise the implementation must be provided "by hand" in a members statement. The collecting class can choose from a variety of different containers (lists, hash tables, sets, etc.) to implement the tracking or can provide a custom container via the genlib container statement. The Container Class Description in the genlib documentation provides details of the available containers, how to specify custom containers, and the function of a container's "extra" field, which can be overridden with provide container's extra clause.

The byvalue and keytype/keymember clauses affect aspects of the interface specification as well as any automatically generated implementation. The details of these optional clauses are:

byvalue
Normally, the collecting class container holds pointers to the collected class instances. If byvalue is specified, it holds the instances themselves.
keytype type keymember expression
Indicates that the collecting class container is a map-style container, i.e. the container is given a key and returns a value, as opposed to being iterated through in a linear fashion. Type is the type returned by the container, whereas expression is any expression that when applied to a collected class pointer (e.g. collected_pointer->expression) will yield the proper key into the container. Expression is typically simply a no-argument member function of the collected class, but more complicated expressions are possible.

Second form (singular collection)

In this form, the byvalue keyword is non-functional; the collecting class always contains a reference to the collected class. If the using_pointer keyword is provided, then an implementation (using a pointer, of course) will be generated.