Commit 718e8586 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

reviewed documentation

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 1227
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 91f02e43
/*! \file README
/*! \file libaff/README
* \brief C++ containers for numbers (libaff)
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
* $Id: README,v 1.9 2002-12-20 18:04:13 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -23,6 +23,11 @@
*
* REVISIONS and CHANGES
* - 06/12/2002 V1.0 Thomas Forbriger (copied from libcontxx)
* - 20/12/2002 V1.1 (thof)
* - complete revision of this file
* - there are major gaps in
* -# \ref sec_design_multidimensional
* -# \ref page_using
*
* ============================================================================
*/
......@@ -34,7 +39,7 @@
Here you should find all components, the user needs to work with this
library.
When working with the binary version of the library, you have to use
aff::prebuilt in place of aff (see \ref sec_main_binary).
aff::prebuilt in place of aff (see \ref sec_design_binary).
*/
namespace aff {
} // namespace aff
......@@ -48,17 +53,14 @@ namespace aff {
\since December 2002
\date December 2002
\version V1.0
$Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
$Id: README,v 1.9 2002-12-20 18:04:13 forbrig Exp $
Contents of this page:
- \ref sec_main_aims
- \ref sec_main_modules
- \ref sec_main_modules_basic
- \ref sec_main_modules_extended
- \ref sec_main_interface
- \ref sec_main_namespace_aff
- \ref sec_main_headers
- \ref sec_main_constness
- \ref sec_main_peculiar
Additional information:
- \ref page_design
......@@ -135,74 +137,34 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
the smallest in a set, etc.).
-# aff::Subarray presented in aff/subarray.h to conveniently create
subarrays from aff::Array objects.
-# aff::Slice presented in aff/slice.h to conveniently create
-# aff::Slice presented in aff/slice.h to conveniently create
slices from aff::Array objects.
-# aff::dump and its associates, presented in aff/dump.h. They are used to
dump shape or contents of containers and are thus useful when
debugging your code.
/*OK*/
/*----------------------------------------------------------------------*/
\section sec_main_interface Interface to the library
\subsection sec_main_namespace_aff Namespace aff
The main modules like
- aff::Array
- aff::Iterator
- aff::Shaper
are presented in namespace aff. In the
\ref sec_design_binary "binary version" the same modules are
presented in namespace aff::prebuilt.
Use the directive
\code
using namespace aff;
\endcode
or
\code
using aff::Array;
\endcode
for convenient access.
In the \ref sec_design_binary "binary version" some of the modules
(aff::Array and aff::SharedHeap) are presented in namespace aff::prebuilt.
\sa \ref sec_design_namespaces
/*----------------------------------------------------------------------*/
\subsection sec_main_headers Header files
The main modules are presented in
- aff/array.h (the aff::Array class and its constituents)
- aff/binarray.h (the same for its precompiled
\ref sec_design_binary "binary version")
- aff/iterator.h (the aff::Iterator class)
- aff/shaper.h (the aff::Shaper class)
\sa \ref sec_nameing_files
\sa \ref sec_using_include
/*----------------------------------------------------------------------*/
\section sec_main_constness Constness of arrays
We distinguish between the constness of the array and the constness of the
elements. A definition
\code
const aff:Array<int> A(B);
\endcode
means that array \c A is a constant array initialized to array \c B. This
means, that the container is constant. Its shape and reference may not be
changed.
\section sec_main_peculiar Peculiarities
If you want to define constness of the contained values (e.g. when passing
an array to a function), you have to use
\code
aff:Array<const int> C(A);
\endcode
which defines that the contents of \c C may not be changed (i.e. they are of
type \c const \c int.
\par Const-correctness for array elements
In this library we follow provide functionality to write const-correct code
with regard to the array container and with regard to its element values.
See also "\ref sec_design_const".
\sa \ref sec_design_const
\par Multidimensional arrays
Every aff::Array of this class has aff::Strided::Mmax_dimen dimensions.
Construction and access for lower dimensionality is provided. In the case of
using less dimensions, the size of the unused dimensions is 1 by default and
its index is inherently set to the first index.
See also "\ref sec_design_multidimensional".
*/
......@@ -226,9 +188,10 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
automatically invoked. Reference semantics ensure a minimal overhead. in
terms of memory usage and execution time.
In the case of the copy operator thnigs are less clear: If we define the
In the case of the copy (assignment) operator things are less clear:
If we define the
copy operator to have reference semantics, it has the same behaviour as the
copy constructor. That is what we usually would explect. An expression like
copy constructor. That is what we usually would expect. An expression like
\code
A=B;
\endcode
......@@ -237,28 +200,42 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
\c A will refer to the same memory location as array \c B and will have the
same shape. Both are indistinguishable.
However, in many cases (most cases?) we will use the copy operator in the
senso of a mathematical equation. This may read like
However, in many cases (most cases?) we will use the copy (assignment)
operator in the
sense of a mathematical equation. This may read like
\code
A=B+C;
\endcode
although expressions like this are not yet supported by the library
features. In this case we do not mean the \c A should drop it reference.
features. In this case we do not mean that \c A should drop it reference.
\c A may refer to an array in memory which is also referred by other array
instances. And we want these values to be set to the result of the operation
\c B + \c C. In that case the copy operator should have deep copy semantics.
\todo
An answer how the semantics of the copy operator should be chosen is not yet
found. Find it!
\par Design decision
The classes aff::Array and aff::Series provide copy (assignment) operators
with shallow copy semantics.
This is sensible, because we are not offering mathematical array operations.
This operations may be delegated to a wrapper class in the future, which
then also may provide expression templates and an appropriate assignment
operator.
/*----------------------------------------------------------------------*/
\section sec_design_namespaces Namespaces
We group all code in two namespaces. Major modules which will be accessed by
the user are place in namepsace aff. Modules meant to be used internally are
place in aff::util.
the user are placed in namepsace aff. Modules meant to be used internally are
placed in aff::util.
Use directives like
\code
using namespace aff;
\endcode
or
\code
using aff::Array;
\endcode
for convenient access.
/*----------------------------------------------------------------------*/
......@@ -274,12 +251,11 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
extensively in array access functions).
To use the binary version you should include binarry.h in place of array.h
You will find all modules in aff::prebuilt that are in contxx in the
full-template version.
You will find modules aff::Array and aff::SharedHeap
in aff::prebuilt that are in aff in the full-template version.
\sa tests/binarraytest.cc
\sa binarray.h
\sa \ref sec_using_include
The inclusion of header files is controlled by a set of preprocessor macros.
\sa AFF_PREBUILT
......@@ -288,13 +264,13 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
\sa AFF_COMPILING_LIBRARY
\sa DOXYGEN_MUST_SKIP_THIS
\todo
Document the different precocessor macros we use.
\todo
Explain how to mix the template and the binary version in practice, when
using additional headers like iterator.h. The include-guards will prevent
them from being read twice - which is not what we want!
\note
Since we reduced to number of template parameters significantly in this
approach, many parts of code have already been factored out to separate files
that are compiled into the binary libaff.a. The approach of explicitly
instantiated class templates is not supported so far. It is, however, prepared
in the structure of header files and may be activated in the future.
\date 20/12/2002
/*----------------------------------------------------------------------*/
......@@ -307,6 +283,59 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
\section sec_design_const Notes on the const-correctness of arrays
\subsection sec_design_const_approach Approach used in this library
We distinguish between the constness of the array and the constness of the
elements. A definition
\code
aff::Array<int> A(12,12);
const aff::Array<int> B(A);
\endcode
means that array \c B is a constant array initialized to array \c A. This
means, that the container is constant. Its shape and reference may not be
changed.
If you want to define constness of the contained values (e.g. when passing
an array to a function), you have to use
\code
aff::Array<const int> C(A);
\endcode
which defines that the contents of \c C may not be changed (i.e. they are of
type \c const \c int.
They are still refering to the same data in memory.
If you modify data elements through \c A, this will be visible through \c C.
An array for elements of type \c T is derived from an array for elements of
type \c const \c T.
Functions that only need read access to arrays should be declared like
\code
void func(const aff::Array<const int>& array);
\endcode
and may be called like
\code
aff::Array<int> A(12,12);
func(A);
\endcode
The type conversion from \c aff::Array<int> to
\c const \c aff::Array<const \c int>& is trivial and has no runtime
overhead.
A container (aff::Array, etc.) with \c const qualifier offers no access
operators, that allow modification of the data.
Although the constness of the container object generally does not imply
constness of the contained data, we think that every user will expect the
classes to behave like this.
To ensure true constness of the data, you have to assign to a container for
element type \c const \c T. Remember that a \c const \c aff::Array always
may be assigned to a mutable aff::Array, which in turn allows modification
of the data!
\sa aff::SharedHeap< const T >
\sa aff::Array< const T >
\sa aff::Series< const T >
\subsection sec_design_const_general General considerations
Arrays using the shared heap representation have reference semantics.
Different instances will access the same data in memory. Copying an array
instance just copies a reference to the data. This mechanism is not obvious
......@@ -330,7 +359,7 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
data from being changed through an instance that is declared const. However,
the compiler will always allow to create a non-const copy of a const array
instance. In the sense of const-ness of C++ data, this does not violate the
const-ness of the source of the copy. the shape of the original array may
const-ness of the source of the copy. The shape of the original array may
not be changed. Only the shape of the copy may be changed. But the data of
the original array may now be changed through the copied instance, since our
array classes implicitly have reference semantic. Thus we have to
......@@ -340,11 +369,9 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
In this library we will not provide a const and a non-const version of the
array classes. With templated code it is more convenient to use an array
with element type \c const \c T as the const version of an array with
element type \c T. To allow copying of an instance with element type \c T to
an instance of type \c const \c T, we have to provide explicit conversion
operators. A special class aff::util::Qualified allows automatic
specialization of array classes and representations to use the correct
element type conversion in the class conversion operators.
element type \c T. To allow conversion of an instance with element type \c T
to an instance of type \c const \c T, we use the version for elements of
type \c const \c T as a base classe.
- The need of const-correctness is discussed in "Chapter 1 Introduction,
C++ Conventions, Implementation of Vector and Matrix Classes" of
......@@ -357,8 +384,6 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
have reference semantics at
"http://www.geophysik.uni-frankfurt.de/~forbrig/txt/cxx/tutorial/consthandle.doc/doc/html/index.html".
\sa aff::SharedHeap
*/
/*======================================================================*/
......@@ -367,56 +392,29 @@ $Id: README,v 1.8 2002-12-20 16:39:40 forbrig Exp $
Contents of this page:
- \ref sec_using_constructor
- \ref sec_using_include
- \ref sec_using_examples
\section sec_using_constructor Constructing arrays
Arrays are most easy constructed by means of a Shaper.
If you want e.g. define an array \c A of ints with Fortran layout, three
dimensions and the index ranges [-2:2], [1:4], and [6:10] you have to code
Arrays are most easy constructed by means of the aff::Shaper.
If you want e.g. define an array \c A of element type int with Fortran
layout, three dimensions and the index ranges [-2:2], [1:4], and [6:10] you
have to code
\code
contxx::Array<int, 3> A(contxx::shaper::Fortran<3>(-2,2)(4)(6,10));
using namespace aff;
Array<int> A(Shaper(-2,2)(4)(6,10));
\endcode
Shapers are presented in namespace contxx::shaper.
\sa \ref Shaper
\sa \ref sec_main_modules_shaper
\sa contxx::shaper
\sa contxx::shaper::Fortran
\sa tests/arraytest.cc
\sa \ref sec_general_dimension
The shaper is presented in aff/shaper.h.
\todo
rework this section
\section sec_using_include Including header files
The main set of \ref sec_main_modules "array modules" is included by
contxx/array.h. This include the full templatized version of the library. We
you want to take advantage of the
\ref sec_main_binary "precompiled binary library" you have to include
contxx/binarray.h.
This will set CONTXX_PREBUILT which places all definitions in
contxx::prebuilt rather than just namespace contxx.
Files like contxx/shaper/fortran.h or contxx/iterator.h are not included
automatically by array.h or binarray.h.
You have to include them separately.
If you are using the precompiled library, you must include them \b after
binarray.h so that they will place their declarations in contxx::prebuilt
and take the declarations for other parts of the library from that namespace
too.
\par Mixing the pure template library and the binary version
Mixing the pure template library and the binary version might not work with
this version of the library. Once you included either array.h or binarray.h
the include guards will prevent the precompiler from reading the files
again.
This problem may be solved in a future version with a more elaborate include
guard mechanism that takes account for CONTXX_PREBUILT.
\todo
Rework this section
\section sec_using_examples Example code
The test programs may serve as examples for using this library:
- tests/arraytest.cc
- tests/shapetest.cc
- tests/reprtest.cc
- tests/simplearraytest.cc
\todo
Tell about usefull header files.
We need more text and examples.
*/
......@@ -444,7 +442,6 @@ Tell about usefull header files.
*/
/*OK*/
/*======================================================================*/
/*! \page page_naming Naming conventions
......@@ -486,8 +483,8 @@ Tell about usefull header files.
that is factored out to be compilable into a binary library for explicit
instantiation.
The main directory aff contains headers that are usually included by the
user. A subdirectory aff/lib contains additional headers that are mostly
The main directory %aff contains headers that are usually included by the
user. A subdirectory %aff/lib contains additional headers that are mostly
used internally.
*/
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README.changelog,v 1.15 2002-12-20 16:39:40 forbrig Exp $
* $Id: README.changelog,v 1.16 2002-12-20 18:04:13 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -20,7 +20,7 @@
/*! \page page_changelog ChangeLog (AFF)
$Id: README.changelog,v 1.15 2002-12-20 16:39:40 forbrig Exp $
$Id: README.changelog,v 1.16 2002-12-20 18:04:13 forbrig Exp $
\sa \ref page_project_status
......@@ -39,6 +39,10 @@
- introduced aff::Iterator class template
- reworked lib/README
- moved SHeap to namespace util
- reviewed README entirely
- Remove unresolvable doxygen links in documentation parts of the code.
Notice: There remain doxygen warning. Doxygen cannot deal with access
declarations and has problems with member typedefs.
- \b 19/12/2002 (thof)
- \b !! aff::Array provides access to base classes through access
......@@ -74,7 +78,7 @@
/*! \page page_project_status Project status (AFF)
$Id: README.changelog,v 1.15 2002-12-20 16:39:40 forbrig Exp $
$Id: README.changelog,v 1.16 2002-12-20 18:04:13 forbrig Exp $
\sa \ref page_changelog
......@@ -85,7 +89,10 @@
<TD><B>code is tested</B></TD>
<TD><B>revision is required</B></TD>
<TR><TD>libaff/README</TD>
<TD>has no code</TD><TD> </TD><TD>has no code</TD><TD> </TD>
<TD>has no code</TD><TD> </TD><TD>has no code</TD>
<TD>Explain Wolle's concept of multidimensional arrays.
The HOWTO page needs a revision and much more examples.
</TD>
</TR>
<TR><TD>libaff/array.h</TD>
<TD>8/12/02</TD><TD> </TD><TD>19/12/2002</TD><TD> </TD>
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: array_dec.h,v 1.13 2002-12-20 12:21:04 forbrig Exp $
* $Id: array_dec.h,v 1.14 2002-12-20 18:04:13 forbrig Exp $
* \author Thomas Forbriger
* \since 08/12/2002
*
......@@ -44,7 +44,7 @@
#define AFF_ARRAY_DEC_H_VERSION \
"AFF_ARRAY_DEC_H V1.3"
#define AFF_ARRAY_DEC_H_CVSID \
"$Id: array_dec.h,v 1.13 2002-12-20 12:21:04 forbrig Exp $"
"$Id: array_dec.h,v 1.14 2002-12-20 18:04:13 forbrig Exp $"
#include <aff/lib/sharedheap.h>
#include <aff/lib/strided.h>
......@@ -67,7 +67,6 @@ namespace prebuilt {
* class type (passed to Subscriptor base class)
* \param Subscriptor Subscriptor base class type
*
* \sa \ref page_shapes_and_subscriptors
* \sa \ref page_representation
* \sa \ref sec_main_modules
* \sa tests/arraytest.cc
......@@ -105,8 +104,7 @@ namespace prebuilt {
* several typedefs to declare types derived from the element type of
* the array.
*
* \sa \ref sec_main_constness
* \sa aff::util::Qualified<T>
* \sa \ref sec_design_const
*/
//@{
//! Type of this array
......@@ -118,7 +116,7 @@ namespace prebuilt {
/*! \brief short for Tcontainer_of_const
*
* We generally distinguish between constness of the array and
* constness of the contained data (see \ref sec_main_constness).
* constness of the contained data (see \ref sec_design_const).
* There will be situations, when you want to promise that a function
* will not change the contents of an array. In this case you may use
* a declaration (prototype) like
......@@ -227,8 +225,7 @@ namespace prebuilt {
* several typedefs to declare types derived from the element type of
* the array.
*
* \sa \ref sec_main_constness
* \sa aff::util::Qualified<T>
* \sa \ref sec_design_const
*/
//@{
//! Type of representation
......@@ -250,7 +247,7 @@ namespace prebuilt {
/*! \brief short for Tcontainer_of_const
*
* We generally distinguish between constness of the array and
* constness of the contained data (see \ref sec_main_constness).
* constness of the contained data (see \ref sec_design_const).
* There will be situations, when you want to promise that a function
* will not change the contents of an array. In this case you may use
* a declaration (prototype) like
......@@ -299,7 +296,7 @@ namespace prebuilt {
*
* Although we generally distinguish between the constness of the
* container and the constness of the contained data (see
* \ref sec_main_constness), we provide const element access operators
* \ref sec_design_const), we provide const element access operators
* the prohibit element modification. We assume that a const version
* of the array is usually meant to be used only for reading.
*/
......
......@@ -3,13 +3,13 @@
*
* ----------------------------------------------------------------------------
*
* $Id: binarray.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* $Id: binarray.h,v 1.3 2002-12-20 18:04:13 forbrig Exp $
* \author Thomas Forbriger
* \since 08/12/2002
*
* just arrays class definitions (for binary libraray contents) (prototypes)
*
* \sa \ref sec_main_binary
* \sa \ref sec_design_binary
* \sa aff::Array
*
* \todo
......@@ -29,7 +29,7 @@
#define AFF_BINARRAY_H_VERSION \
"AFF_BINARRAY_H V1.0 "
#define AFF_BINARRAY_H_CVSID \
"$Id: binarray.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
"$Id: binarray.h,v 1.3 2002-12-20 18:04:13 forbrig Exp $"
#ifndef AFF_COMPILING_LIBRARY
#define AFF_NO_DEFINITIONS
......@@ -37,11 +37,9 @@
/*! \def AFF_PREBUILT
*
* This preprocessor macro is set in contxx/binarray.h.
* It requests to place all declarations in contxx::prebuilt to match the
* contents of the \ref sec_main_binary "precompiled binary library".
*
* \sa \ref sec_using_include
* This preprocessor macro is set in aff/binarray.h.
* It requests to place all declarations in aff::prebuilt to match the
* contents of the \ref sec_design_binary "precompiled binary library".
*/
#ifndef DOXYGEN_MUST_SKIP_THIS
#define AFF_PREBUILT
......
......@@ -59,7 +59,7 @@ FILE_PATTERNS = README \
RECURSIVE = YES
EXCLUDE =
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATH = tests
EXAMPLE_PATTERNS =
IMAGE_PATH =
INPUT_FILTER =
......
......@@ -59,7 +59,7 @@ FILE_PATTERNS = README \
RECURSIVE = YES
EXCLUDE =
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATH = tests
EXAMPLE_PATTERNS =
IMAGE_PATH =
INPUT_FILTER =
......
/*! \file repr/README
/*! \file libaff/lib/README
* \brief about the concept of memory representations
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.4 2002-12-20 16:39:41 forbrig Exp $
* $Id: README,v 1.5 2002-12-20 18:04:14 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: simplearray.h,v 1.7 2002-12-15 20:48:01 forbrig Exp $
* $Id: simplearray.h,v 1.8 2002-12-20 18:04:15 forbrig Exp $
* \author Thomas Forbriger
* \since 08/12/2002
*
......@@ -26,7 +26,7 @@
#define AFF_SIMPLEARRAY_H_VERSION \
"AFF_SIMPLEARRAY_H V1.1 "
#define AFF_SIMPLEARRAY_H_CVSID \
"$Id: simplearray.h,v 1.7 2002-12-15 20:48:01 forbrig Exp $"
"$Id: simplearray.h,v 1.8 2002-12-20 18:04:15 forbrig Exp $"
#include<aff/lib/types.h>
#include<aff/lib/rawarfun.h>
......@@ -64,7 +64,6 @@ using namespace aff::util;
* \endcode
* This function returns exactly the SimpleRigidArray object you need.
* For an example see tests/arraytest.cc
* \sa \ref sec_general_dimension
*
* \param T element type
* \param N dimension of the array
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: strided.h,v 1.13 2002-12-20 12:21:05 forbrig Exp $
* $Id: strided.h,v 1.14 2002-12-20 18:04:15 forbrig Exp $
* \author Thomas Forbriger
* \since 08/12/2002
*
......@@ -50,7 +50,7 @@
#define AFF_STRIDED_H_VERSION \
"AFF_STRIDED_H V1.5"
#define AFF_STRIDED_H_CVSID \
"$Id: strided.h,v 1.13 2002-12-20 12:21:05 forbrig Exp $"
"$Id: strided.h,v 1.14 2002-12-20 18:04:15 forbrig Exp $"
#include<aff/lib/types.h>
#include<aff/lib/simplearray.h>
......@@ -68,9 +68,6 @@ namespace aff {
* arrays. This is in contrast to packed layouts for banded matrices or
* triangular matrices that do not hold every array element.
*
* \sa contxx::subscriptor::DenseStridedRepresentation