The BTK AtomIterable Concept

Description:

An object that models the AtomIterable Concept allows iteration over a range of Atom objects, and allows the user to query the size of that range.

This concept specifies only that an object should be able to iterate over a range of atom objects, not necessarily that it should contain those objects. In particular, while all AtomicStructure objects are AtomIterable, not all AtomIterable objects are AtomicStructures.

Notation:

X -- A type that models the AtomIterable Concept
x -- An object of type x

Associated Types:

Size Type	X::size_type	An unsigned integral type
Atom Iterator Type	X::atom_iterator	A type conforming to the AtomIterator Concept
Const Atom Iterator Type	X::const_atom_iterator	A type conforming to the AtomIterator Concept, that may only be used to examine (not modify) atoms.
Reverse Atom Iterator Type	X::reverse_atom_iterator	An STL ReverseIterator whose base iterator type is an atom_iterator
Const Reverse Atom Iterator Type	X::const_reverse_atom_iterator	An STL ReverseIterator whose base iterator type is a const_atom_iterator

Definitions:

None.

Valid Expressions:

Expression	Type Reqirements	Precondition	Semantics	Postcondition	Complexity
size_type x.num_atoms() const			Returns the size of the atom range.
atom_iterator x.structure_begin()	x is mutable		Returns an iterator pointing to the first atom in the range.	x.atom_begin() is either dereferenceable, or past-the-end. It is past the end iff x.atom_size() == 0	O(1)
atom_iterator x.structure_end()	x is mutable		Returns an iterator pointing one past the last atom in the range.		O(1)
const_atom_iterator x.structure_begin() const			Returns an iterator pointing to the first atom in the range.	x.atom_begin() is either dereferenceable, or past-the-end. It is past the end iff x.atom_size() == 0	O(1)
const_atom_iterator x.structure_end() const			Returns an iterator pointing one past the last atom in the range.		O(1)
reverse_atom_iterator x.structure_rbegin()	x is mutable		Equivalent to reverse_atom_iterator(x.structure_end())	x.atom_rbegin() is either dereferenceable, or past-the-end. It is past the end iff x.atom_size() == 0	O(1)
reverse_atom_iterator x.structure_rend()	x is mutable		Equivalent to reverse_atom_iterator(x.structure_begin())		O(1)
const_reverse_atom_iterator x.structure_rbegin() const			Equivalent to const_reverse_atom_iterator(x.structure_end())	x.atom_rbegin() is either dereferenceable, or past-the-end. It is past the end iff x.atom_size() == 0	O(1)
const_reverse_atom_iterator x.structure_rend() const			Equivalent to const_reverse_atom_iterator(x.structure_begin())		O(1)

Invariants:

• [x.atom_begin(),x.atom_end()) is a valid range.
• [x.atom_rbegin(),x.atom_rend()) is a valid range.
• The distance from x.atom_begin() to x.atom_end() is the same as the the distance from x.atom_rbegin() to x.atom_rend(), which is the same as x.atom_size().

Models:

• BTK::MOLECULES::AtomicStructure
• BTK::MOLECULES::Chain
• BTK::MOLECULES::Molecule
• BTK::MOLECULES::Polymer
• Any BTK::MOLECULES::System of AtomIterable objects.

Notes:

• Just as for STL containers, there is no complexity requirement for x.num_atoms(). Use with care.

---