provide container
statementSyntax:
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.
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
byvalue
is specified, it holds the instances themselves.
keytype
type keymember
expression
->
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.
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.