---

Glossary

Capacity

Some containers have to reorganize the internal data structures when objects are added. The `capacity' of a container is the number of objects it can hold before such a reorganization is needed. Typically all or some of the following methods are available to inquire and control the capacity:

Capacity() const

Returns the current capacity. Note, that the capacity of a container is always larger than its size.

EnsureCapacity(CTBint i_cap)

If necessary, increases the capacity to at least i_cap elements.

IncreaseCapacity(CTBint i_cap)

Like EnsureCapacity(), but the capacity is at least increased by a factor, typically 2. This method is usually called in flexible containers when additional objects are stored. The increase by a factor ensures that at most log₂(size) reallocations have to be performed and that on average an object is only copied once.

TrimCapacity()

The capacity is reduced to the size of the container.

a Capacity() method allows to inquire the capacity and an EnsureCapacty() method allows to increase the capacity.

Clone method

Often it is necessary that an object has to be duplicated even though only a pointer to its base class is available. Since there is no direct language support in C++ for a virtual constructor one has to achieve this with a properly defined virtual function. By convention this method is called Clone(). It returns a pointer to a new'ed copy of the object and has the following signature and typical implementation:

   class base {
     public:
       virtual base* Clone() const  { return new base(*this) };
   };

   class foo : public base {
     public:
       virtual base* Clone() const  { return new foo(*this) };
   };

Note, that the return type is always a pointer to the base class. Even though the final C++ standard allows to use a different return type for an overwritten method, many compilers still don't like this. Note also, that the Clone method in a abstract base class is abstract. If there is no copy constructor available, a different constructor may be used as long the clone semantics is satisfied.

See also CTBclone.

Container

A container is an object which holds copies of other objects. Objects can be added, accessed and removed from the container. Different container types are optimized for various access and update methods.

Compare function

A Compare function is used for the lexical comparison of two objects. It returns an int value, which is 0 if both objects are equal, a positive number if the lhs (first) argument is larger than the rhs (second) argument, and a negative number if the lhs (first) argument is smaller than the rhs (second) argument:

return value	condition
0	lhs == rhs
> 0	lhs > rhs
< 0	lhs < rhs

Note, that a compare function only defines an order, not a metric. Only the sign or zeroness of the result is relevant, the absolute value is not.
This paradigm is used in compare function objects, like CTBcompareFunc and CTBcompareOper , and in Compare methods.

Using compare functions can improve performance in cases where often a test on equality of two objects is paired with a test on relative order, as in binary tree search algorithm (e.g. see implementation of CTBmap ).

Grab

A grab is an operation in which the resources of the one object, the victim, are transfered to another one. After a grab, the victim object holds no references to its former resources, the grabbing object will be responsible to control the life time of these resources.
This paradigm is used in grab constructors, and return objects, and Grab() methods.

Grab constructor

A grab constructor initializes the object by transferring all the resources of the source object to the constructed object. By convention it is declared like

  class foo {
    public:
             foo();                             // default constructor
             foo(const foo& rhs);               // copy constructor
             foo(foo& rhs, bool b_grab);        // grab constructor
     ...
  };
        
  foo::foo(foo& rhs, bool )   { ... }

The second argument b_grab is a dummy argument to distinguish the grab constructor from a copy constructor. Note also, that the source object rhs is passed as a non-const reference because the status of rhs will change.

See also CTBgrab.

Return object

See CTBretObj .

Size

`size' refers often to the number of objects stored in a container.Size should not be confused with capacity.

Virtual constructor

There are copy constructors in C++, which allow to duplicate an object, but they are of little use when one has for example just a pointer to an abstract base class of an object and needs a replica. One needs something like a `virtual constructor', and the solution is to use the clone concept.

Virtual destructor

One has to be careful when an object is deleted through a pointer to one of its base classes, like in

   class base { ... };
   class foo : public base { ...} ;

   base* p = new foo();
   ...
   delete p;

If no precautions are taken, only the base class destructor is executed, leading to all kinds of problems, like memory and other resource leaks. Declaring the destructor as virtual solves this problem, like in

   class base {
      ...
      virtual  ~base();
      ...
   };

If the destructor is declared virtual, automatically the destructor of the most derived class is executed independently of the type of the pointer used with the delete operator.

All non-trivial classes which are expected to be base classes should have a virtual destructor. A typical guide line is `if there is any virtual method, declare the destructor also as virtual'.

---