// in sdl:
interface a; // some object class definition
interface my_obj {
public:
attribute set<a> aset;
attribute set<a> abag;
attribute sequence<long> iseq;
};
// signature of C++ binding for set/bag types
// (The public part of the class declarations for
// string and text attributes.)
template <class elt_t>
class set
{
public:
void add(const REF(elt_t));
void del(const REF(elt_t) &arg);
REF(elt_t) delete_one();
REF(elt_t) get_elt(int i) const;
int get_size() const;
int member(const REF(elt_t) &arg);
};
// signature of C++ binding for sequence types
template <class t>
class sequence {
public:
int append_elt(const t & new_elt);
int append_elt();
void delete_elt(unsigned int i);
const t & get_elt(unsigned int i) const;
const t & operator[] (unsigned int i) const;
t & write_elt(unsigned int i);
int get_size() const;
};
The SDL set and bag types provide a simple mechanism for maintaining a collection of references to Shore objects. SDL set and bag types may only be declared with object types (types declared as SDL interfaces) as the element type; the set or bag is implemented by reference. That is, the set attribute stores a set of object references and not copies of the objects. Attributes of SDL objects declared as type set<elt_t> can be accessed within SDL/C++ programs as if they were instances of a C++ template class instantiation with the method signature shown above. The only difference between set<t> and bag<t> is that an instance of set<t> will never contain more than one reference to a particular object of type t; an attribute of type bag<t> may contain any number of references to the same object. That is, sets will never contain duplicate references, while bags may contain duplicates.
The SDL sequence type can be used to provide a variable length array abstraction within an SDL object. If an attribute is declared as sequence<elt_t>, values can be appended to the end of the sequence and elements within the sequence can be accessed using a simple integer index as their location within the sequence. Unlike sets and bags, sequences store elements by value, not by references; therefore, the type parameter of a sequence type should not be an object type.
In what follows, we assume bindings for the following SDL definitions have been generated:
interface a { public: attribute long i;};
interface b { public: attribute long j;};
interface my_obj {
public:
attribute set<a> a_set;
attribute bag<b> b_bag;
attribute sequence<long> i_seq;
};
We also assume the following C++/SDL variable declarations:
REF(a) a_ref; REF(b) b_ref; REF(my_obj) s_ref;
The add member function inserts a reference of the correct type into the given set.
s_ref.update()->a_set.add(a_ref);
adds the reference a_ref to the a_set attribute of the object
that the variable s_ref refers to.
sref.update()->a_set.del(a_ref);
sref.update()->b_set.del(b_ref);
deletes any reference to a_ref
or the first value matching b_ref (for bags);
if no matching ref is found within the set/bag, the operation
has no effect.
aref = sref.update()->a_set.delete_one();
deletes one element of a set, and returns a ref to the element
deleted; the element chosen for deletion is based on efficiency
considerations.
The
get_size
function returns the number of elements in the set or bag, and
the
get_elt
function will return a reference to the
i
th
element of the set,
numbered from 0 to n-1, where n-1 is the value returned by
get_size
;
if the parameter is out of range for the set, a null value will
be returned.
A simple idiom for iterating though the elements of a set is
is to increment a parameter to
get_elt
until a null reference is returned, as shown below.
int i;
for (aref = sref->a_set.get_elt(i=0);
aref != NULL;
aref = sref->a_set.get_elt(++i))
{
// do something with object aref
// points to.
}
Sequence attributes have operations similar to sets and bags, but they store values, not references. Object(interface) types may not be used as the element type in a sequence declaration. Sequence attributes are initially empty. A sequence may be extended one element at a time using the append_elt function. Two overloaded variants are provided. If the parameterless variant is called, the new element is uninitialized. If a parameter of the sequence element type is provided, the value of the parament is used to initialize the new sequence element.
Elements of a sequence can be access randomly using an integer index. The function get_elt will return a const C++ reference to the i th element of the sequence, that is, it allows read only access to the element. The member function operator[] is semantically identical to get_elt The member function write_elt returns a non-const C++ reference to the i th element; this form may be used to update an element of a sequence in place. Elements may be deleted from within a sequence using the delete_elt call, which will remove the i th element from the sequence. Note that this will result in renumbering of following elements in the sequence. If one of the element accessing functions tries to access an element beyond the range of the sequence, the first element in the sequence is returned.