[Avida-cvs] [avida-svn] r908 - in development: Avida.xcodeproj documentation
brysonda at myxo.css.msu.edu
brysonda at myxo.css.msu.edu
Tue Aug 29 20:35:22 PDT 2006
Author: brysonda
Date: 2006-08-29 23:35:21 -0400 (Tue, 29 Aug 2006)
New Revision: 908
Added:
development/documentation/code_standards.html
Modified:
development/Avida.xcodeproj/project.pbxproj
development/documentation/code_c++_intro.html
development/documentation/index.html
Log:
Update the conceptual c++ documentation.
Modified: development/Avida.xcodeproj/project.pbxproj
===================================================================
--- development/Avida.xcodeproj/project.pbxproj 2006-08-30 01:31:04 UTC (rev 907)
+++ development/Avida.xcodeproj/project.pbxproj 2006-08-30 03:35:21 UTC (rev 908)
@@ -508,6 +508,7 @@
7049F36F0A66AD7E00640512 /* default-transsmt.org */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = text; path = "default-transsmt.org"; sourceTree = "<group>"; };
704ADBC30A6EEFC300666970 /* DriverActions.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = DriverActions.h; sourceTree = "<group>"; };
704ADBC40A6EEFC300666970 /* DriverActions.cc */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = DriverActions.cc; sourceTree = "<group>"; };
+ 704D57210AA53F8600207FC1 /* code_standards.html */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = text.html.documentation; path = code_standards.html; sourceTree = "<group>"; };
705332480929764A006BD186 /* cSpecies.cc */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = sourcecode.cpp.cpp; path = cSpecies.cc; sourceTree = "<group>"; };
705332490929764A006BD186 /* cSpecies.h */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = sourcecode.c.h; path = cSpecies.h; sourceTree = "<group>"; };
7053324A0929764A006BD186 /* cSpeciesQueue.cc */ = {isa = PBXFileReference; fileEncoding = 30; lastKnownFileType = sourcecode.cpp.cpp; path = cSpeciesQueue.cc; sourceTree = "<group>"; };
@@ -1113,6 +1114,7 @@
70920C1A0A9CCE2C00757CDB /* Documentation */ = {
isa = PBXGroup;
children = (
+ 704D57210AA53F8600207FC1 /* code_standards.html */,
707CE7500AA334120022D19C /* analyze.html */,
707CE7490AA333060022D19C /* actions.html */,
707CE51D0A9E49A50022D19C /* config.html */,
Modified: development/documentation/code_c++_intro.html
===================================================================
--- development/documentation/code_c++_intro.html 2006-08-30 01:31:04 UTC (rev 907)
+++ development/documentation/code_c++_intro.html 2006-08-30 03:35:21 UTC (rev 908)
@@ -1,398 +1,435 @@
-<title>An Introduction to C++</title>
+<html>
+<head>
+ <title>Avida : A Conceptual Introduction to C++</title>
+</head>
+<body>
-<body text="#000000" bgcolor="#FFFFFF" link="#0000AA" vlink="#000044" alink="#0000FF">
+<div style="float: right">
+Revised 2006-08-29 DMB
+</div>
-<center>
-<h2>
-A Conceptual Introduction to C++</h2></center>
+<p><a href="index.html">Return to the Index</a></p>
+<hr />
+
+<div align="center">
+<h1>A Conceptual Introduction to C++</h1>
+</div>
+
+<p>
This file will cover in more detail some of the concepts needed to understand
-C++. My goal here is <i>not</i> to make you be able to sit down and write
+C++. The goal here is <em>not</em> to make you be able to sit down and write
your own program from scratch.
-<h3>
-Objects and Classes</h3>
-An <b>object</b> in C++ is a single, conceptual unit that contains <b>data</b>
-(information about the state of that object) and <b>methods</b> (functions
-associated with that class of objects) by which the object is modified
-or can interact with other objects. The data in an object can be either
-normal variables (<i>e.g.</i> characters, floating point numbers, or integers)
-or previously-defined objects. A category of objects is a <b>class</b>;
-an object is a single instance of a class.
-<p>For example, in Avida one of the most important classes is called
-<tt>cOrganism</tt>
+</p>
+
+
+<p> </p>
+<h2>Objects and Classes</h2>
+<p>
+An <strong>object</strong> in C++ is a single, conceptual unit that contains
+<strong>data</strong> (information about the state of that object) and
+<strong>methods</strong> (functions associated with that class of objects) by
+which the object is modified or can interact with other objects. The data in
+an object can be either normal variables (<em>e.g.</em> characters, floating
+point numbers, or integers) or previously-defined objects. A category of
+objects is a <strong>class</strong>; an object is a single instance of a class.
+</p>
+<p>
+For example, in Avida one of the most important classes is called <code>cOrganism</code>
-- it is the class that all organism objects belong to. Here is an abbreviated
version of the cOrganism class declaration (explained further below), color
coded to aide understanding.
-<center><table CELLPADDING=4 WIDTH="90%" >
+</p>
+<div align="center">
+<table width="90%">
<tr>
-<td WIDTH="50%"><font color="#886600"><b>Comments</b> are in BROWN</font>
-<br><font color="#008800">Names of <b>methods</b> are in GREEN</font></td>
-
-<td WIDTH="50%"><font color="#880000">Names of <b>classes</b> are in RED</font>
-<br><font color="#0000AA">Names of <b>objects</b> are in BLUE</font></td>
+ <td width="50%">
+ <span style="color: #886600"><strong>Comments</strong> are in BROWN</span>
+ <br /><span style="color: #008800">Names of <strong>methods</strong> are in GREEN</span>
+ </td>
+ <td width="50%">
+ <span style="color: #880000">Names of <strong>classes</strong> are in RED</span>
+ <br /><span style="color: #0000AA">Names of <strong>objects</strong> are in BLUE</span>
+ </td>
</tr>
-</table></center>
+</table>
+</div>
-<table CELLPADDING=8 >
-<tr>
-<td>
-<pre>class <font color="#880000">cOrganism</font> {
-private: <font color="#886600">// Data in this class cannot be directly accessed from outside.
+<pre style="margin-left: 10px">
+class <span style="color: #880000">cOrganism</span>
+{
+private: <span style="color: #886600">// Data in this class cannot be directly accessed from outside.</span>
+ const <span style="color: #880000">cGenome</span> <span style="color: #0000AA">m_genome</span>; <span style="color: #886600">// The initial genome that this organism was born with.</span>
+ <span style="color: #880000">cPhenotype</span> <span style="color: #0000AA">m_phenotype</span>; <span style="color: #886600">// Maintains the status of this organism's phenotypic traits.</span>
-</font> const <font color="#880000">cGenome</font><font color="#0000AA"> genome;</font> <font color="#886600">// The initial genome that this organism was born with.
-</font> <font color="#880000">cPhenotype</font><font color="#0000AA"> phenotype;</font> <font color="#886600">// Maintains the status of this organism's phenotypic traits.
+ <span style="color: #880000">cOrgInterface</span>* <span style="color: #0000AA">m_interface</span>; <span style="color: #886600">// Interface back to the population.</span>
-</font> <font color="#880000">cPopulationInterface</font><font color="#0000AA"> pop_interface;</font> <font color="#886600">// Interface back to the population.
+ <span style="color: #880000">cGenotype</span>* <span style="color: #0000AA">m_genotype;</span> <span style="color: #886600">// A pointer to the genotype that this organism belongs to.</span>
+ <span style="color: #880000">cHardwareBase</span>* <span style="color: #0000AA">m_hardware;</span> <span style="color: #886600">// The virtual machinery that this organism's genome is run on.</span>
-</font> <font color="#880000">cGenotype </font><font color="#000000">*</font> <font color="#0000AA">genotype;</font> <font color="#886600">// A pointer to the genotype that this organism belongs to.
-</font> <font color="#880000">cHardwareBase </font><font color="#000000">*</font> <font color="#0000AA">hardware;</font> <font color="#886600">// The virtual machinery that this organism's genome is run on.
+public: <span style="color: #886600"> // The methods are accessible to other classes.</span>
+ <span style="color: #008800">cOrganism</span>(<span style="color: #880000">cWorld</span>* <span style="color: #0000AA">world</span>, <span style="color: #880000">cAvidaContext</span>& <span style="color: #0000AA">ctx</span>, const <span style="color: #880000">cGenome</span>& <span style="color: #0000AA">in_genome</span>);
+ <span style="color: #008800">~cOrganism</span>();
-</font>public: <font color="#886600"> // The methods are accessible to other classes.
+ <span style="color: #886600">// This batch of methods involve interaction with the population to resolve.</span>
+ <span style="color: #880000">cOrganism</span>* <span style="color: #008800">GetNeighbor</span>() { return <span style="color: #0000AA">m_interface</span>-><span style="color: #008800">GetNeighbor</span>(); }
+ int <span style="color: #008800">GetNeighborhoodSize</span>() { return <span style="color: #0000AA">m_interface</span>-><span style="color: #008800">GetNumNeighbors</span>(); }
+ void <span style="color: #008800">Rotate</span>(int direction) { <span style="color: #0000AA">m_interface</span>-><span style="color: #008800">Rotate</span>(direction); }
+ int <span style="color: #008800">GetInput</span>() { return <span style="color: #0000AA">m_interface</span>-><span style="color: #008800">GetInput</span>(); }
+ void <span style="color: #008800">Die</span>() { <span style="color: #0000AA">m_interface</span>-><span style="color: #008800">Die</span>(); }
-</font> <font color="#886600">// This classes' constructor requires an initial genome, an interface to the population,
- // and the environment the organism is in. NOTE: These are defined elsewhere.
-</font> <font color="#008800">cOrganism(</font><font color="#000000">const</font> <font color="#880000">cGenome</font> <font color="#000000">&</font> <font color="#0000AA">in_genome</font><font color="#000000">,
-</font><font color="#008800"> </font><font color="#000000">const</font> <font color="#880000">cPopulationInterface</font> <font color="#000000">&</font> <font color="#0000AA">in_interface</font><font color="#000000">,
-</font><font color="#008800"> </font><font color="#000000">const</font> <font color="#880000">cEnvironment</font> <font color="#000000">&</font> <font color="#0000AA">in_environment</font><font color="#008800">)</font><font color="#000000">;
-</font><font color="#008800"> ~cOrganism()</font><font color="#000000">;
+ <span style="color: #886600">// Accessors -- these are used to gain access to private data.</span>
+ const <span style="color: #880000">cGenome</span>& <span style="color: #008800">GetGenome()</span> const { return <span style="color: #0000AA">m_genome</span>; }
+ <span style="color: #880000">cHardwareBase</span>& <span style="color: #008800">GetHardware()</span> { return *<span style="color: #0000AA">m_hardware</span>; }
+ <span style="color: #880000">cPhenotype</span>& <span style="color: #008800">GetPhenotype()</span> { return <span style="color: #0000AA">m_phenotype</span>; }
+ <span style="color: #880000">cGenotype</span>* <span style="color: #008800">GetGenotype()</span> { return <span style="color: #0000AA">m_genotype</span>; }
+};
+</pre>
-</font> <font color="#886600">// This batch of methods involve interaction with the population to resolve.
-</font> <font color="#880000">cOrganism</font> <font color="#000000">*</font><font color="#008800"> GetNeighbor() </font><font color="#000000">{</font> <font color="#000000">return</font> <font color="#0000AA">pop_interface</font><font color="#008800">.GetNeighbor()</font><font color="#000000">; }
-</font><font color="#008800"> </font><font color="#000000">int</font><font color="#008800"> GetNeighborhoodSize() </font><font color="#000000">{</font> <font color="#000000">return</font> <font color="#0000AA">pop_interface</font><font color="#008800">.GetNumNeighbors()</font><font color="#000000">; }
-</font><font color="#008800"> </font><font color="#000000">void</font><font color="#008800"> Rotate(</font><font color="#000000">int direction</font><font color="#008800">) </font><font color="#000000">{</font> <font color="#0000AA">pop_interface</font><font color="#008800">.Rotate(direction)</font><font color="#000000">; }
-</font><font color="#008800"> </font><font color="#000000">int</font><font color="#008800"> GetInput() </font><font color="#000000">{ return</font> <font color="#0000AA">pop_interface</font><font color="#008800">.GetInput()</font><font color="#000000">; }
-</font><font color="#008800"> </font><font color="#000000">void</font><font color="#008800"> Die() </font><font color="#000000">{</font> <font color="#0000AA">pop_interface</font><font color="#008800">.Die()</font><font color="#000000">; }
-</font> <font color="#886600">// Input & Output Testing -- see if any environment reactions are triggered.
-</font> <font color="#000000">void</font><font color="#008800"> DoInput</font><font color="#000000">(const</font> <font color="#000000">int</font><font color="#008800"> </font><font color="#000099">value</font><font color="#008800">, </font><font color="#880000">tBuffer<</font><font color="#000000">int</font><font color="#880000">></font> <font color="#000000">&</font><font color="#008800"> </font><font color="#000099">input_buf</font><font color="#008800">, </font><font color="#880000">tBuffer<</font><font color="#000000">int</font><font color="#880000">></font> <font color="#000000">&</font><font color="#008800"> </font><font color="#000099">output_buf</font><font color="#000000">);
-</font><font color="#008800"> </font><font color="#000000">void</font><font color="#008800"> DoOutput</font><font color="#000000">(const</font> <font color="#000000">int</font><font color="#008800"> </font><font color="#000099">value</font><font color="#008800">, </font><font color="#880000">tBuffer<</font><font color="#000000">int</font><font color="#880000">></font> <font color="#000000">&</font><font color="#008800"> </font><font color="#000099">input_buf</font><font color="#008800">, </font><font color="#880000">tBuffer<</font><font color="#000000">int</font><font color="#880000">></font> <font color="#000000">&</font><font color="#008800"> </font><font color="#000099">output_buf</font><font color="#000000">);
+<p> </p>
+<h2>Style and Syntax Guide</h2>
-</font> <font color="#886600">// Accessors -- these are used to gain access to private data.
-</font> const <font color="#880000">cGenome</font> & <font color="#008800">GetGenome()</font> const { return <font color="#0000AA">genome</font>; }
- <font color="#880000">cPhenotype</font> & <font color="#008800">GetPhenotype()</font> { return <font color="#0000AA">phenotype</font>; }
- <font color="#880000">cGenotype</font> * <font color="#008800">GetGenotype()</font> { return <font color="#0000AA">genotype</font>; }
- <font color="#880000">cHardwareBase</font> * <font color="#008800">GetHardware()</font> { return <font color="#0000AA">hardware</font>; }
-
- <font color="#886600">// Some special methods used during saving and loading.
-</font> <font color="#000000">void</font><font color="#008800"> SaveState</font><font color="#000000">(</font><font color="#880000">ofstream</font><font color="#008800"> & fp</font><font color="#000000">);
-</font><font color="#008800"> </font><font color="#000000">void</font><font color="#008800"> LoadState</font><font color="#000000">(</font><font color="#880000">ifstream</font><font color="#008800"> & fp</font><font color="#000000">);
-
-</font>};</pre>
-</td>
-</tr>
-</table>
-
-<h3>
-Style and Syntax Guide</h3>
+<p>
Don't worry too much about how the syntax works. The code presented above
is a definition of a class in C++. It is broken into two parts; one labeled
-"<tt>private:</tt>" for those portions of the definition that can only
-be interacted with from within the class, and another labeled "<tt>public:</tt>"
+<code>private:</code> for those portions of the definition that can only
+be interacted with from within the class, and another labeled <code>public:</code>
which defines the interface to the outside. In this case, we've made all
of the variables private and the methods public.
-<p>A variable is defined by a description of the type of variable (such
-a "<tt>cPhenotype</tt>") and then the name of this particular instance
+</p>
+<p>
+A variable is defined by a description of the type of variable (such
+a <code>cPhenotype</code>) and then the name of this particular instance
of the variable. In this case, since organisms only have one phenotype,
-we called it merely "<tt>phenotype</tt>".
-<p>Methods are slightly more complex. The declaration of a method starts
-with the type of data the method returns (such as "<tt>int</tt>" for integer),
-or else lists "<tt>void</tt>" if there is no return value. Then the method
-name is given, followed by a set of parenthesis (which are what indicates
-to C++ that you are declaring a method). Inside of those parentesis, can
-be
-<b>arguments</b>, which are variables that must be given to the method
-in order for it to operate correctly. The declaration can stop at this
-point (ending in a semi-colon) if the method <b>body</b> is defined elsewhere.
-The body of the method is the sourcecode that details how the method operates,
-and can be included immediately after the declaration (within braces) or
-be placed elsewhere in the code. Typically short method bodies are included
-in the class definition, while longer ones are placed outside of it. A
-method is performed on an object, by listing the object name, followed
-by a dot ('.'), and then the name of the method to be called with all necessary
-arguments included. This is explained further below.
-<p>The C++ language will accept variable names, class names, and method
-names of any alpha-numeric sequence as long as all names begin with a letter.
-The only other character allowed in a name is the underscore ('_').
-To make reading code easier, we have adopted certain conventions.
-<br>
-<table CELLSPACING=3 CELLPADDING=3 NOSAVE >
-<tr VALIGN=TOP NOSAVE>
-<td> </td>
+we called it merely <code>m_phenotype</code>. Not that because this
+variable is a <em>member</em> of <code>cOrganism</code> instances, it is
+prefixed with '<code>m_</code>'.
+</p>
-<td NOSAVE><font color="#0000AA">an_example_variable</font></td>
+<p>
+Methods are slightly more complex. The declaration of a method starts with the
+type of data the method returns (such as <code>int</code> for integer), or else
+lists <code>void</code> if there is no return value. Then the method name is
+given, followed by a set of parenthesis (which are what indicates to C++ that
+you are declaring a method). Inside of those parentesis, can be
+<strong>arguments</strong>, which are variables that must be given to the
+method in order for it to operate correctly. The declaration can stop at this
+point (ending in a semi-colon) if the method <strong>body</strong> is defined
+elsewhere. The body of the method is the sourcecode that details how the method
+operates, and can be included immediately after the declaration (within braces)
+or be placed elsewhere in the code. Typically short method bodies are included
+in the class definition, while longer ones are placed outside of it. A method is
+performed on an object, by listing the object name, followed by a dot ('.'), and
+then the name of the method to be called with all necessary arguments included.
+This is explained further below.
+</p>
+<p>
+The C++ language will accept variable names, class names, and method names of
+any alpha-numeric sequence as long as all names begin with a letter. The only
+other character allowed in a name is the underscore ('_'). To make reading code
+easier, we have adopted certain conventions.
+</p>
-<td>Variable names (including object names) are always all in lowercase
-letters, with individual words separated by underscores. Variables are
-either user-defined classes, numbers (integers, boolean values, floating
-point numbers, etc.) or characters (single symbols)</td>
-</tr>
+<dl>
+<dt><span style="color: #0000AA">an_example_variable</span></dt>
+<dd>
+ Variable names (including object names) are always all in lowercase
+ letters, with individual words separated by underscores. Variables are
+ either user-defined classes, numbers (integers, boolean values, floating
+ point numbers, etc.) or characters (single symbols)</dd>
+</dd>
+<dt><span style="color: #008800">ExampleMethod</span></dt>
+<dd>
+ Method names always have the first letter of each word capitalized, with the
+ remainder of the word in lowercase. The one exception to this is Constructors
+ and Destructors, which must have the same name as the class (see below).
+</dd>
+<dt><span style="color: #880000">cExampleClass</span></dt>
+<dd>
+ Classes use a similar format to methods, but always begin with a single,
+ lowercase 'c'. Some other specialized types also used this format, but with a
+ different initial letter. For example, an initial 't' indicates a template,
+ which is a special type of class.
+</dd>
+<dt>CONSTANT_VALUE</dt>
+<dd>
+ Any constant values (that is, numerical values that will never change
+ during the course of the run) are given in all upper-case letters, with
+ individual words separated by underscores.
+</dd>
+</dl>
-<tr VALIGN=TOP NOSAVE>
-<td> </td>
+<p>
+Different software projects will each use their own style conventions; these
+are the ones you'll end up working with in Avida. Some exceptions do exist.
+For example, the C++ language itself does not follow many style rules;
+built-in C++ names are all lowercase letters, regardless of what they
+represent. For more details, including spacing and other code formatting
+standards you must follow in Avida, see the
+<a href="code_standards.html">Coding Standards</a>.
-<td NOSAVE><font color="#008800">ExampleMethod</font></td>
-<td>Method names always have the first letter of each word capitalized,
-with the remainder of the word in lowercase. The one exception to this
-is Constructors and Destructors, which must have the same name as the class
-(see below).</td>
-</tr>
+<p> </p>
+<h2>Description of Data Elements</h2>
-<tr VALIGN=TOP NOSAVE>
-<td> </td>
-
-<td NOSAVE><font color="#880000">cExampleClass</font></td>
-
-<td>Classes use a similar format to methods, but always begin with a single,
-lowercase 'c'. Some other specialized types also used this format, but
-with a different initial letter. For example, an initial 't' indicates
-a template, which is a special type of class.</td>
-</tr>
-
-<tr VALIGN=TOP NOSAVE>
-<td> </td>
-
-<td NOSAVE>CONSTANT_VALUE</td>
-
-<td>Any constant values (that is, numerical values that will never change
-during the course of the run) are given in all upper-case letters, with
-individual words separated by underscores.</td>
-</tr>
-</table>
-
-<p>Different software projects will each use their own style conventions;
-these are the ones you'll end up working with in Avida. Some exceptions
-do exist. For example, the C++ language itself does not follow many style
-rules; built-in C++ names are all lowercase letters, regardless of what
-they represent.
-<h3>
-Description of Data Elements</h3>
-The section labeled <tt>private</tt> above lists those data that are unique
-to each organism; these are objects and pointers that exist <i>inside</i>
-of an organism object. First, <font color="#0000AA">genome</font> keeps
+<p>
+The section labeled <code>private</code> above lists those data that are unique
+to each organism; these are objects and pointers that exist <em>inside</em> of
+an organism object. First, <span style="color: #0000AA">m_genome</span> keeps
the initial state of the organism. Since we never want this genome to change
-over the organism's life, we place a <tt>const</tt> directive in front
-of it. The <tt>const</tt> command exists so that C++ knows to warn the
+over the organism's life, we place a <code>const</code> directive in front of
+it. The <code>const</code> command exists so that C++ knows to warn the
programmer if they accidentally try to change an object (or variable) that
is not supposed to be altered.
-<p>The internal <font color="#0000AA">phenotype</font> object is used to
-record the behaviors and abilities that the organism demonstrates during
-its life. This class has variables to track everything from the tasks performed
-to the gestation time of the organism and the number of offspring it has
-ever produced. The <font color="#0000AA">pop_interface</font> allows an
-organism to communicate with the population (object of class
-<tt><font color="#880000">cPopulation</font></tt>)
-that it is part of. This is used, for example, when an organism is ready
-to finish replicating and needs its offspring to be placed into the population.
-If an organism is being run on a test CPU rather than in a proper population
-object, then this population interface will cause the statistics about
-offspring to be recorded for later use instead of activating it.
-<p>Next, we have two <b>pointers</b>. A pointer is a value that represents
-("points to") a location in the physical memory of the computer. A pointer
-can be identified by the asterisk ('*') that follows the type name. The
-code "<tt>cGenotype * genotype</tt>" indicates that the variable
-<font color="#0000AA">genotype</font>
-points to a location in memory where an object of class <font color="#880000">cGenotype</font>
-is stored. In this case, all of the organisms that are of a single genotype
-all point to the <i>same</i> cGenotype object so that the genotypic information
+</p>
+<p>
+The internal <span style="color: #0000AA">m_phenotype</span> object is used to
+record the behaviors and abilities that the organism demonstrates during its
+life. This class has variables to track everything from the tasks performed to
+the gestation time of the organism and the number of offspring it has ever
+produced. The <span style="color: #0000AA">m_interface</span> allows an
+organism to communicate with the environment (either the
+<span style="color: #880000">cPopulation</span> or the
+<span style="color: #880000">cTestCPU</span>) that it is part of. This is used,
+for example, when an organism is ready to finish replicating and needs its
+offspring to be placed into the population. If an organism is being run on a
+test CPU rather than in a proper population object, then this interface will
+cause the statistics about offspring to be recorded for later use instead of
+activating it.
+</p>
+<p>
+Next, we have two <strong>pointers</strong>. A pointer is a value that
+represents ("points to") a location in the physical memory of the computer. A
+pointer can be identified by the asterisk ('*') that follows the type name. The
+code "<code>cGenotype* genotype</code>" indicates that the variable
+<span style="color: #0000AA">genotype</span> points to a location in memory
+where an object of class <span style="color: #880000">cGenotype</span> is
+stored. In this case, all of the organisms that are of a single genotype all
+point to the <em>same</em> cGenotype object so that the genotypic information
is accessible to all organisms that may need to make use of it.
-<p>The final data element is <font color="#0000AA">hardware</font>, a pointer
-to an object of type <font color="#880000">cHardwareBase</font>. This variable
-is a pointer for a different reason than the genotype. Where a single genotype
-is shared by many different organisms, each organism does possess its own
-hardware. But in implementing Avida, I allowed many different kinds of
-hardware to be available, where any of them can be at the other end of
-that hardware pointer. The cHardwareBase class is used as an interface
-to the actual hardware that is used. This is explained in more detail later
-in the section on "Inherited Classes". For the moment, the key idea is
-that a pointer can sometimes point to a general type of object, not just
-those of a very specific class.
-<h3>
-Description of Methods</h3>
+</p>
+<p>
+The final data element is <span style="color: #0000AA">m_hardware</span>, a
+pointer to an object of type <span style="color: #880000">cHardwareBase</span>.
+This variable is a pointer for a different reason than the genotype. Where a
+single genotype is shared by many different organisms, each organism does
+possess its own hardware. However, Avida supports more than one type of
+hardware, where any of them can be at the other end of that hardware pointer.
+The cHardwareBase class is used as an interface to the actual hardware that is
+used. This is explained in more detail later in the section on inherited
+classes. For the moment, the key idea is that a pointer can sometimes point to
+a general type of object, not just those of a very specific class.
+</p>
+
+
+<p> </p>
+<h2>Description of Methods</h2>
+
+<p>
Class descriptions (with limited exceptions) must contain two specific
-methods called the <b>constructor</b> and the <b>destructor</b>. The constructor
-always has the same name as the class (it's called <font color="#008800">cOrganism(...)</font>
-in this case), and is executed in order to create a new object of that
-class. The arguments for the constructor must include all of the information
-required to build on object of the desired class. For an organism, we need
-the genome of that organism, an interface to the population it will be
-in, and the environment it needs to operate under. The method is not defined
-here, only <b>declared</b>. A declared method must be defined elsewhere
-in the program. All methods must be, at least, declared in the class definition.
-Note that if there are many ways to create an object, multiple constructors
-are allowed as long as they take different inputs.
-<p>Whereas the constructor is called when an object is created, the destructor
+methods called the <strong>constructor</strong> and the
+<strong>destructor</strong>. The constructor always has the same name as the
+class (it's called <span style="color: #008800">cOrganism</span>(...) in this
+case), and is executed in order to create a new object of that class. The
+arguments for the constructor must include all of the information required to
+build on object of the desired class. For an organism, we need the world
+object within which the organism resides, the current execution context, and
+perhaps most importantly the genome of the organism. The method is not defined
+here, only <strong>declared</strong>. A declared method must be defined
+elsewhere in the program. All methods must be, at least, declared in the class
+definition. Note that if there are many ways to create an object, multiple
+constructors are allowed as long as they take different inputs.
+</p>
+<p>
+Whereas the constructor is called when an object is created, the destructor
is called when the object is destroyed, whereupon it must do any cleanup,
such as freeing allocated memory (see the section on memory management
below). The name of a destructor is always the same as the class name,
but with a tilde ('~') in front of it. Thus, the cOrganism's destructor
-is called <font color="#008800">~cOrganism()</font>. A destructor can never
-take any arguments, and there must be only one of them in a class definition.
-<p>The next group of five methods are all called when an organism needs
+is called <span style="color: #008800">~cOrganism</span>(). A destructor can
+never take any arguments, and there must be only one of them in a class
+definition.
+</p>
+<p>
+The next group of five methods are all called when an organism needs
to perform some behavior, which in all of these cases involves it interacting
with the population. For example, if you need to know at whom an organism
is facing, you can call the method
-<font color="#008800">GetNeighbor()</font>
+<span style="color: #008800">GetNeighbor</span>()
on it, and a pointer to the neighbor currently faced will be returned.
Likewise, if you need to kill an organism, you can call the method
-<font color="#008800">Die()</font><font color="#000000">
-on it, and it will be terminated. Since each of these require interaction
-on the population level, the population itself takes care of the bulk of
-the functionality.</font>
-<p>The next pair of methods,<font color="#008800">DoInput(...)</font> and
-<font color="#008800">DoOutput(...)</font>
-are used to monitor when the organism triggers a task. Whenever the organism
-requests a new input number or outputs a processed number, the DoInput
-or DoOutput method is called with the value being sent in/out, the current
-state of the input buffer (that is, all values that have been input thus
-far), and the current state of the output buffer (all of the values that
-the organism has output over its lifetime). The buffers are scanned for
-task completion, and any relevant reactions are triggered.
-<p>The "Accessors" are methods that provide access to otherwise private
-data. For example, the method <font color="#008800">GetGenome()</font>
-will literally pass the genome of the organism to the object that calls
-it. In particular, the hardware object associated with an organism
-will often call <font color="#008800">GetPhenotype()</font> in order
-to get the current state of the organism's phenotype and update it with
-something new the organism has done. Several things to take note
-of here. In the first two accessors, the name of the class being
-returned is followed by an ampersand ('&'). This means that the
-actual object is being passed back, and not just a copy of all the values
-contained in it. See the next section on pointers, references, and
-values for more information about this. Also, in the very first accessor,
-the keyword "<tt>const</tt>" is used twice. The first time is to
-say that the object being passed out of the method is constant (that is,
-the programmer should be warned if somewhere else in the code it is being
-changed) and the second time is to say that the actions of this method
-will never change anything about the object they are being run on (that
-is, the object is being left constant even when the method is run.)
-The net effect of this is that an object marked const can only have const
-methods run on it. The compiler will assume that a non-const method being
-run will make a change to the object, and is therefore an error.
-<p>Finally, we have the pair of methods
-<font color="#008800">SaveState(...)</font>
-and <font color="#008800">LoadState(...)</font> that are used when Avida
-runs are being saved to or resumed from file. The input "<tt>ofstream</tt>"
-stands for Output File Stream, and contains information about the file
-that data is being written to. Likewise, an "<tt>ifstream</tt>" object
-is an Input File Stream and used when a C++ program needs to read information
-from a file.
-<p><font color="#000000">This section has contained information about a
-particular C++ class found in Avida. The next sections will more
-generally explain some of the principles of the language. If you
-haven't already, now might be a good time to take a deep breath before
-you dive back in.</font>
-<h3>
-<font color="#000000">Pointers, References, and Values</font></h3>
-<font color="#000000">The three ways of passing information around in a
+<span style="color: #008800">Die</span>() on it, and it will be terminated.
+Since each of these require interaction on the population level, the population
+itself takes care of the bulk of the functionality.
+</p>
+<p>
+The 'Accessors' are methods that provide access to otherwise private
+data. For example, the method <span style="color: #008800">GetGenome</span>()
+will literally pass the genome of the organism to the object that calls it. In
+particular, the hardware object associated with an organism will often call
+<span style="color: #008800">GetPhenotype</span>() in order to get the current
+state of the organism's phenotype and update it with something new the organism
+has done. Several things to take note of here. In the first three accessors,
+the name of the class being returned is followed by an ampersand ('&').
+This means that the actual object is being passed back, and not just a copy of
+all the values contained in it. See the next section on pointers, references,
+and values for more information about this. Also, in the very first accessor,
+the keyword <code>const</code> is used twice. The first time is to say that
+the object being passed out of the method is constant (that is, the programmer
+should be warned if somewhere else in the code it is being changed) and the
+second time is to say that the actions of this method will never change
+anything about the object they are being run on (that is, the object is being
+left constant even when the method is run.) The net effect of this is that an
+object marked const can only have const methods run on it. The compiler will
+assume that a non-const method being run will make a change to the object, and
+is therefore an error.
+</p>
+<p>
+This section has contained information about a particular C++ class found
+in Avida. The next sections will more generally explain some of the
+principles of the language. If you haven't already, now might be a good
+time to take a deep breath before you dive back in.
+</p>
+
+
+<p> </p>
+<h2>Pointers, References, and Values</h2>
+
+<p>
+The three ways of passing information around in a
C++ program is through sending a pointer to the location of that information,
-sending a reference to it, or actually just sending the value of the information.
-For the moment, lets consider the return value of a method. Consider
-the three methods below:</font>
-<p><tt><font color="#000000"> </font><font color="#880000">cGenome
-</font><font color="#008800">GetGenomeValue()</font><font color="#000000">;</font></tt>
-<br><tt><font color="#000000"> </font><font color="#880000">cGenome</font><font color="#000000">
-* </font><font color="#008800">GetGenomePointer()</font><font color="#000000">;</font></tt>
-<br><tt><font color="#000000"> </font><font color="#880000">cGenome</font><font color="#000000">
-& </font><font color="#008800">GetGenomeReference()</font><font color="#000000">;</font></tt>
-<p>These three cases are all very different. In the first case ("<b>Pass-by-Value</b>"),
-the value of the genome in question is returned. That means that the genome
-being returned is analyzed, and the exact sequence of instruction in it
-are sent to the object calling this method. Once the requesting object
-gets this information, however, any changes made to it do <i>not</i> affect
-the original genome that was copied. The second case ("<b>Pass-by-Pointer</b>"),
-only a few bytes of information are returned that give the location in
-memory of this genome. The requesting object can then go and modify that
-memory if it chooses to, but it must first "resolve" the pointer to do
-so. Finally, the last case ("<b>Pass-by-Reference</b>") actually
-passes the whole object out. It is used in a very similar way to
-pass-by-value, but any changes made to the genome after it is passed out
-will affect the genome in the actual organism itself! Pass-by-reference
-does not add any new functionality over pass-by-pointer, but in practice
-it is often easier to use.
-<h3>
-Memory Management</h3>
+sending a reference to it, or actually just sending the value of the information.
+For the moment, lets consider the return value of a method. Consider
+the three methods below:
+</p>
+<pre>
+ <span style="color: #880000">cGenome</span> <span style="color: #008800">GetGenomeValue</span>();
+ <span style="color: #880000">cGenome</span>* <span style="color: #008800">GetGenomePointer</span>();
+ <span style="color: #880000">cGenome</span>& <span style="color: #008800">GetGenomeReference</span>();
+</pre>
+<p>
+These three cases are all very different. In the first case
+(<strong>Pass-by-Value</strong>), the value of the genome in question is
+returned. That means that the genome being returned is analyzed, and the exact
+sequence of instruction in it are sent to the object calling this method. Once
+the requesting object gets this information, however, any changes made to it do
+<em>not</em> affect the original genome that was copied. The second case
+(<strong>Pass-by-Pointer</strong>),only a few bytes of information are returned
+that give the location in memory of this genome. The requesting object can then
+go and modify that memory if it chooses to, but it must first 'resolve' the
+pointer to do so. Finally, the last case (<strong>Pass-by-Reference</strong>)
+actually passes the whole object out. It is used in a very similar way to
+pass-by-value, but any changes made to the genome after it is passed out will
+affect the genome in the actual organism itself! Pass-by-reference does not
+add any new functionality over pass-by-pointer, but in practice it is often
+easier to use.
+</p>
+
+
+<p> </p>
+<h2>Memory Management</h2>
+
+<p>
Memory management in C++ can be as simple or complicated as the programmer
wants it to be. If you never explicitly allocate a chunk of memory, than
you never need to worry about freeing it up when you're done using it.
However, there are many occasions where a program can be made faster or
-more flexible by dynamically allocating objects. The command <b><tt>new</tt></b>
-is used to allocate memory; for example if you wanted to allocate memory
-for a new genome containing 100 instructions, you could type:
-<p><tt> <font color="#880000">cGenome</font> * <font color="#0000AA">created_genome</font>
-= new <font color="#008800">cGenome(</font>100<font color="#008800">)</font><font color="#000000">;</font></tt>
-<p><font color="#000000">The variable "created_genome" that is defined
-as a pointer to a memory location containing a genome. This is assigned
-to a newly allocated genome in memory, which is the return value of the
-new command. The cGenome constructor (called with new) takes as an
-argument a single number that is the sequence length of the genome.</font>
-<p><font color="#000000">Unfortunately, C++ won't know when we're done
-using this genome. If we need to create many different genomes and
-we only use each of them once, our memory can rapidly fill up. So,
-we need to tell it. Thus, when we're done using it, we type:</font>
-<p><tt><font color="#000000"> free </font><font color="#0000AA">created_genome</font><font color="#000000">;</font></tt>
-<p><font color="#000000">And the memory pointed to by the created_genome
-variable will be freed up.</font>
-<p><font color="#000000">An excellent example of when allocation and freeing
-of memory is employed in avida is with the genotype. Every time a
-new genotype is created during evolution, avida needs to allocate a new
-object of class cGenotype. During the course of a run, millions of
-genotypes may be created, so we need to be sure to free genotypes whenever
-they will no longer be needed in the run.</font>
-<h3>
-<font color="#000000">Inherited Classes</font></h3>
-<font color="#000000">One of the beauties of C++ is that well written code
-is inherently very reusable. As part of that, there is the concept
-of the <b>inhereted class</b> (sometimes called a <b>derived class</b>).
-When a new class is built in C++, it is possible to build it off of an
-existing class, then referred to as its <b>base class</b>. The derived
-class will have access to all of the methods in the base class, and can<b>
-overload</b> them; that is, it can change how any of those methods operate.</font>
-<p><font color="#000000">For example, in the Avida scheduler, we use a
-class called </font><font color="#880000">cSchedule</font><font color="#000000">
-to determine which organism's virtual CPU executes the next instruction.
-Well, this cSchedule object is not all that clever. In fact, all
-that it does is run through the list or organisms that need to go, lets
-them each execute a single instruction, and then does it all over again.
-But sometimes we need to make some organisms execute instructions at a
-faster rate than others. For that reason, I derived several classes
-including </font><font color="#880000">cIntegratedSchedule</font><font color="#000000">,
-which takes in a merit value for each organism, and assigns CPU cycles
-proportional to that merit. Since this new class uses cSchedule as
-its base class, it can be dynamically plugged in during run time, after
-looking at what the user chooses in the genesis file.</font>
-<p><font color="#000000">If a method is not implemented in a base class
-(left to be implemented in the derived classes) it is called an <b>abstract</b>
-method. If a base class does not implement <i>any</i> of its methods
-and is only used in order to specify what methods need to be included in
-the derived classes, it is referred to as an <b>abstract base class</b>
-and is used simply as an interface protocol to the derived classes.
-An example in avida where this is used is the hardware. The class
-</font><font color="#880000">cHardwareBase</font><font color="#000000">
-is an abstract base class; the reason it is abstract is because in principle,
-any kind of underlying virtual hardware should be allowed. Currently,
-only one is implemented called </font><font color="#880000">cHardwareCPU</font><font color="#000000">
-(a virtual CPU), but I have lots of ideas to have, such as a neural network
-running the organisms.</font>
-<h3>
-Links:</h3>
+more flexible by dynamically allocating objects. The command
+<strong><code>new</code></strong> is used to allocate memory; for example if
+you wanted to allocate memory for a new genome containing 100 instructions,
+you could type:
+</p>
+<pre>
+ <span style="color: #880000">cGenome</span>* <span style="color: #0000AA">created_genome</span> = new <span style="color: #008800">cGenome</span>(100);
+</pre>
+<p>
+The variable created_genome is defined as a pointer to a memory location
+containing a genome. This is assigned the location of the newly allocated
+genome in memory, which is the return value of the <code>new</code> command.
+The cGenome constructor (called with new) takes as an argument a single number
+that is the sequence length of the genome.
+</p>
+<p>
+Unfortunately, C++ won't know when we're done using this genome. If we
+need to create many different genomes and we only use each of them once,
+our memory can rapidly fill up. So, we need tell the memory management
+that we are finished with the current object. Thus, when we're done using
+it, we type:
+</p>
+<pre>
+ delete <span style="color: #0000AA">created_genome</span>;
+</pre>
+<p>
+And the memory pointed to by the created_genome
+variable will be freed up.
+</p>
+<p>
+An excellent example of when allocation and freeing of memory is employed
+in Avida is with the genotype. Every time a new genotype is created during
+evolution, Avida needs to allocate a new object of class cGenotype. During
+the course of a run, millions of genotypes may be created, so we need to be
+sure to free genotypes whenever they will no longer be needed in the run.
+</p>
-<menu>
-<li>
-<a href="http://www.intap.net/~drw/cpp/">Online C++ Tutorial</a></li>
-<li>
-<a href="http://www.cplusplus.com/doc/tutorial/">Another Tutorial</a></li>
+<p> </p>
+<h2>Inherited Classes</h2>
-<li>
-<a href="http://www.quiver.freeserve.co.uk/OOP1.htm">Object Oriented Concepts
-Tutorial</a></li>
+<p>
+One of the beauties of C++ is that well written code
+is inherently very reusable. As part of that, there is the concept
+of the <strong>class inheritance</strong>. When a new class is built in C++,
+it is possible to build it off of an existing class, then referred to as
+a <strong>base class</strong>. The new <strong>derived</strong>
+class will have access to all of the methods in the base class, and can
+<strong>overload</strong> them; that is, it can change how any of those
+methods operate.
+</p>
+<p>
+For example, in the Avida scheduler, we use a class called
+<span style="color: #880000">cSchedule</span> to determine which organism's
+virtual CPU executes the next instruction. Well, this cSchedule object is not
+all that clever. In fact, all that it does is run through the list of
+organisms that need to go, lets them each execute a single instruction, and
+then does it all over again. But sometimes we need to make some organisms
+execute instructions at a faster rate than others. For that reason, there are
+several derived classes, including
+<span style="color: #880000">cIntegratedSchedule</span>, which takes in a merit
+value for each organism, and assigns CPU cycles proportional to that merit.
+Since this new class uses cSchedule as its base class, it can be dynamically
+plugged in during run time, after looking at what the user chooses in the
+configuration file.
+</p>
+<p>
+If a method is not implemented in a base class (left to be implemented in the
+derived classes) it is called an <strong>abstract</strong> method. If a base
+class does not implement <em>any</em> of its methods and is only used in order
+to specify what methods need to be included in the derived classes, it is
+referred to as an <strong>abstract base class</strong> (or sometimes an
+<strong>interface class</strong> or <strong>protocol</strong>) and is used
+simply as a method contract for derived classes. An example in Avida where this
+is used is the organism interface with the environemnt. The class
+<span style="color: #880000">cOrgInterface</span> is an abstract base class,
+with <span style="color: #880000">cPopulationInterface</span> and
+<span style="color: #880000">cTestCPUInterface</span> as derived classes. This
+organization allows for organism objects to interact with both the population
+and the test environment, without having to write separate code for each.
+</p>
-<li>
-<a href="http://www.research.att.com/~bs/glossary.html">A Glossary of C++
-Terms</a></li>
-</menu>
-<br><hr>
-Project hosted by:<br>
-<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=46761&type=2" width="125" height="37" border="0" alt="SourceForge.net"/></a>
-
\ No newline at end of file
+<p> </p>
+<h2>Other C++ Resources:</h2>
+
+<ul>
+<li><a href="http://www.intap.net/~drw/cpp/">Online C++ Tutorial</a></li>
+<li><a href="http://www.cplusplus.com/doc/tutorial/">Another Tutorial</a></li>
+<li><a href="http://www.quiver.freeserve.co.uk/OOP1.htm">Object Oriented Concepts Tutorial</a></li>
+<li><a href="http://www.research.att.com/~bs/glossary.html">A Glossary of C++ Terms</a></li>
+</ul>
+
+
+<hr />
+<p><a href="index.html">Return to the Index</a></p>
+
+</body>
+</html>
Added: development/documentation/code_standards.html
===================================================================
Modified: development/documentation/index.html
===================================================================
--- development/documentation/index.html 2006-08-30 01:31:04 UTC (rev 907)
+++ development/documentation/index.html 2006-08-30 03:35:21 UTC (rev 908)
@@ -42,7 +42,7 @@
<h2>Guides to Modifying the Avida Source Code</h2>
<p>
-<a href="code_c++_intro.html">Introduction to C++ Coding in Avida</a>
+<a href="code_c++_intro.html">A Conceptual Introduction to C++ in Avida</a>
<br /><a href="code_death_birth.html">Guide to the Death/Birth Cycle</a>
<br /><a href="code_init_file.html">Guide to Initialization Files</a>
<br /><a href="code_life_cycle.html">Guide to an Avidan Life Cycle</a>
More information about the Avida-cvs
mailing list