Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members  

TSubstance Class Reference

Substance handling classes: substance object. More...

#include <substance.h>

Collaboration diagram for TSubstance:

Collaboration graph
[legend]
List of all members.

Public Methods

virtual ~TSubstance (void)
virtual TSubstance & operator= (const TSubstance &Subst2)
TSubstance * Clone (void) const
TSubstanceTypeType (void) const
virtual const TOSValAmount (void) const
virtual TOSValAmount (void)
virtual const TOSVal Size (void) const
virtual TOSVal Update (const TOSVal &available_space)
bool load (TDataPackageList *in, const string &sIdentifier, bool bUnique=true)
bool save (TDataPackageList *out, const string &sIdentifier, bool bUnique=true) const

Private Methods

 TSubstance (TSubstanceType *type, const TOSVal &iAmount=1)
 TSubstance (void)
 TSubstance (const TSubstance &Subst2)

Private Attributes

TLink< TSubstanceTypefType
TOSVal fAmount

Friends

TSubstance * TSubstanceType::Create (const TOSVal &iAmount)

Detailed Description

Substance handling classes: substance object.

Author:
Alberto Barsella <Alberto.Barsella@univ-lille1.fr>
Version:
Id:
substance.h,v 1.10 2002/06/03 11:48:24 mkrohn5 Exp
See also:
TSubstanceType,TSubstanceSet,TSubstanceHold
Substance object class. Instances of this class represent a given amount of a specific substance. This class can be used as a base class to provide really special substance (e.g. where update is dependent on the specific instance).

This class DOES NOT provide a constructor. Creation of instances should pass through TSubstanceType::Create. Copy constructor is not available as well: derivation-safe duplication is obtained via a Clone method.

Purpose

The TSubstanceXXXX classes are used to implement and manipulate substances, such as minerals, colonists, fuel, resources, etc. The aim is to provide a general structure, sufficient to handle the simplest cases (like minerals), which can be expanded via derivation to handle more complex substances (such as growing colonists, for example).

Creation of new substances can be performed at runtime for substances whose properties are already coded. Creation of new substance classes (with different properies, e.g. the growing colonists) will require modification of the code and recompilation.

Class organization

There are four classes:

  1. TSubstanceType: instances of this class represent different substances with the same (basic) properties. For example, germanium and ironium are two istances of this class. In the case of growing colonists, two steps are needed: first, a derived class of TSubstanceType is created, providing the needed time-evolution functions, then instances of this new class will represent specific growing colonists.

  2. TSubstance: instances of this class (which can be used as a base class) are used to represent a specified amount of a single substance. Basically they have a type (read TSubstanceType*) and an amount field.

  3. TSubstanceSet: is a set of substances. It's used to represent item costs and it's used in production calculations.

  4. TSubstanceHold: is the same as TSubstanceSet, but with limits imposed on the maximum space available to store substances. They are used for cargo holds.

Substance properties: cargo classes/space

Every substance type (i.e. every instance of TSubstanceType or its derived classes) is characterized by some properties which specify the behaviour of the substance. Examples are the mass for every unit of substance and the size for every unit. A special property is the cargo class: it specifies which substances are considered identical in the calculation of used space. For example: fuel is stored in fuel tanks, while germanium/ironium/boranium are stored in cargo space. Minerals cannot stay into a fuel tank and fuel cannot stay in cargo space. This is implemented by giving a "fuel" cargo class to fuel and a "generic cargo" cargo class to all minerals. This allows TSubstanceHold to properly handle limited space, using a different maximum for every cargo class.

This approach is better shown by looking at how cargo space is specified in a TSubstanceHold (Hold for short). Basically, a Hold is the same as a TSubstanceSet, with one additional restriction: the total size of substances contained in the set which share the same cargo class must be negative. This is obtained by creating substances which have a negative size, 100 units of this substance will take up -100 space of the cargo class of the substance. The presence of this "special substance" allows the addition to 100 size of positive-sized substances before the Hold is considered full.

For example, in the case of minerals, we create three istances of TSubstanceType, to represent ironium, boranium and germanium. They all have the same cargo class and the size property is "1 unit of substance takes 1 unit of space". We then add another substance, called "Mineral Cargo Space", which has the same cargo class of the three minerals, but which size property is "1 unit of substance takes -1 unit of space". Holds are then "expanded" by adding to them a specified amount of the "Mineral Cargo Space" substance. If we want to have a separate "cargo" for fuel (i.e. a tank) we just define a "Fuel" substance of size 1, giving it a new cargo class, together with a "Fuel Tank" substance which has the same cargo class and -1 negative size.

This approach should give all the necessary flexibility for subnstance with different sizes, "living space" for carrying colonists separate from minerals, etc. etc.

Problems

I'm not sure that creating whole new substances by deriving from TSubstance will be handled correctly by TSubstanceHold. Actually, I'm quite sure that it WON'T. I'll work on it when we need it :). (new types - derived from TSubstanceType - which use TSubstance work correctly).


Constructor & Destructor Documentation

virtual TSubstance::~TSubstance void    [virtual]
 

Destructor, virtual to allow derivation.


Member Function Documentation

virtual TOSVal& TSubstance::Amount void    [virtual]
 

Write-accessor to the substance amount.

Returns:
a reference to the value representing the number of substance units.

virtual const TOSVal& TSubstance::Amount void    const [virtual]
 

Read-accessor to the substance amount.

Returns:
a constant value representing the number of substance units.

TSubstance* TSubstance::Clone void    const
 

Duplicate the substance. As with TSubstanceType.Create, a new instance is allocated and initialized.

Returns:
allocates and returns a new TSubstance object. THE CALLER IS IN CHARGE OF DEALLOCATION.

bool TSubstance::load TDataPackageList   in,
const string &    sIdentifier,
bool    bUnique = true
 

With the method Load you can load a TSubstance object from the data packages in the list. For more information look in the documentation of TLinkable.

Parameters:
in  the list of data packages
sIdentifier  the string this item pack is saved under
bUnique  bool value whether the indentifiers have to be unique
Returns:
true means that everything was loaded correctly, otherwise this method will return false.
See also:
TLinkable

virtual TSubstance& TSubstance::operator= const TSubstance &    Subst2 [virtual]
 

Assignment operator. This is not derivation-safe so I'll kill it.

bool TSubstance::save TDataPackageList   out,
const string &    sIdentifier,
bool    bUnique = true
const
 

With the method Save you can save a TSubstance object from the data packages in the list. For more information look in the documentation of TLinkable.

Parameters:
in  the list of data packages
sIdentifier  the string this item pack is to be saved under
bUnique  bool value whether the indentifiers have to be unique
Returns:
true means that everything was saved correctly, otherwise this method will return false.
See also:
TLinkable

virtual const TOSVal TSubstance::Size void    const [virtual]
 

Determine the total size taken by the substance object.

Returns:
the amount of cargo space taken by this substance. It can be a negative number for "space"-type substances.

TSubstanceType* TSubstance::Type void    const
 

Read-accessor to the Type of the TSubstance object. This is not a virtual function, since Type is Type!

Returns:
pointer to the TSubstanceType object of this substance.

virtual TOSVal TSubstance::Update const TOSVal   available_space [virtual]
 

Time evolution function. By default it calls Type()->Update(). Overloading may be desirable in case of weird operations which are very object-dependent. (will we ever need this?).


The documentation for this class was generated from the following file:
Generated on Thu Jun 20 18:13:36 2002 for Stellar Legacy by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001