Commit 21d06dc3 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

docu corrections and remembered the need for an Interface Definition Base

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.
Class Template (wow - what a name)


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 1360
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 1db88d54
# this is <Makefile>
# ----------------------------------------------------------------------------
# $Id: Makefile,v 1.19 2003-06-27 13:58:08 tforb Exp $
# $Id: Makefile,v 1.20 2003-06-27 18:12:50 tforb Exp $
#
# Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
#
......@@ -309,6 +309,8 @@ kdoc:
kdoc -f html -d $(KDOCDIR) -n libaff -p -P -I$(LOCINCLUDEDIR) $(HEADERS)
kdocview: kdoc; mozilla file:$(KDOCDIR)/index.html &
showsections: $(README)
egrep -n '\\subsection|\\section|\\page' $^
#======================================================================
# delegate test targets
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.22 2003-06-27 14:20:39 tforb Exp $
* $Id: README,v 1.23 2003-06-27 18:12:50 tforb Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -68,7 +68,7 @@ namespace aff {
\since December 2002
\date December 2002
\version V1.0
$Id: README,v 1.22 2003-06-27 14:20:39 tforb Exp $
$Id: README,v 1.23 2003-06-27 18:12:50 tforb Exp $
Contents of this page:
- \ref sec_main_aims
......@@ -119,13 +119,13 @@ $Id: README,v 1.22 2003-06-27 14:20:39 tforb Exp $
-# aff::SharedHeap is the representation used by aff::Array. It holds the
data in memory and provides an interface to it. This interface
may be passed separately from the array object (see also
"\ref page_representation" and example tests/reprtest.cc).
\ref page_representation and example tests/reprtest.cc).
-# aff::SimpleRigidArray is a linear array with size fixed at compile-time.
There are several inline functions defined for operations with
this array class (see example tests/simplearraytest.cc).
-# aff::Exception is the exception base class used in the library.
-# aff::AllocException is the exception that indicated a failed memory
allocation(see also "\ref group_error").
allocation(see also \ref group_error).
It additionally offers the following type definitions:
......@@ -163,7 +163,7 @@ $Id: README,v 1.22 2003-06-27 14:20:39 tforb Exp $
example tests/f77test.cc).
-# 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. See also "\ref group_helpers".
debugging your code. See also \ref group_helpers.
In the \ref sec_design_binary "binary version" some of the modules
......@@ -178,19 +178,19 @@ $Id: README,v 1.22 2003-06-27 14:20:39 tforb Exp $
All containers (e.g. aff::Array, aff::Series) use counted references to access
global memory. Assigning one container object to another just assigns the
reference. Both will use the same data in memory afterwards.
See also "\ref page_representation".
See also \ref page_representation.
\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".
See also \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".
See also \ref sec_design_multidimensional.
*/
......@@ -234,8 +234,8 @@ See also "\ref sec_design_multidimensional".
slices (aff::Slice presented in aff/slice.h) should be external to the
aff::Array class. This allows us to load their definitions only where
needed. However, this approach requires that the internals of aff::Array are
exposed to the outside through appropriate functions (see "\ref
sec_design_interface_internals").
exposed to the outside through appropriate functions (see
\ref sec_design_interface_internals).
\subsection sec_design_interface_typedef Member typedefs
......@@ -390,7 +390,7 @@ See also "\ref sec_design_multidimensional".
\subsection sec_design_interface_internals Accessing internals
Providing extended functionality outside of aff::Array (see
"\ref sec_design_interface_sparse") requires, that aff::Array,
\ref sec_design_interface_sparse) requires, that aff::Array,
aff::ConstArray, aff::Series, and aff::ConstSeries expose some of their
internals. This concerns the underlying shape as well as the represented
data.
......@@ -405,8 +405,7 @@ See also "\ref sec_design_multidimensional".
All of them return a copy of their shape through the member functions
aff::Array::shape, aff::ConstArray::shape, aff::Series::shape, and
aff::ConstSeries::shape, respectively. The type of the appropriate shape is
available through a member typedef (
see "\ref sec_design_interface_typedef").
available through a member typedef (see \ref sec_design_interface_typedef).
In return all containers provide a constructor that takes a representation
and a shape object and checks for their consistency.
......@@ -416,13 +415,13 @@ See also "\ref sec_design_multidimensional".
Containers like aff::Array rely on functionality provided by other classes.
They are based on shapes like aff::Strided and memory representations like
aff::SharedHeap (see "\ref page_representation").
aff::SharedHeap (see \ref page_representation).
\par An array isn't a shape.
Thus it would look like better design to use shapes as member data.
We prefer, \b however, to derive privately from the shape classes.
This hides them from the outside (apart from explicit access -
see "\ref sec_design_interface_internals").
see \ref sec_design_interface_internals).
At the same time we make use of using declarations to provide access to
member functions like aff::Strided::size() that make also sense as a member
of aff::Array.
......@@ -435,7 +434,7 @@ See also "\ref sec_design_multidimensional".
We think of the representation as an individual and independent object
that can be passed (e.g.) from an aff::Array to and aff::Series.
Also due to the replication of the representation in aff::Array
(see "\ref sec_design_replicated") and the distinction between containers
(see \ref sec_design_replicated) and the distinction between containers
that allow data modification and containers that allow only read access
this leads to a clearer design.
This is reflected by the conciseness of the array constructors.
......@@ -465,7 +464,7 @@ See also "\ref sec_design_multidimensional".
Having an array object \c a declared
\code aff::Array<T> a; \endcode where \c T is any type, we want to pass this
object to a function that promises constness of the elements (see
"\ref sec_design_const"). The function is thus declared
\ref sec_design_const). The function is thus declared
\code void func(const aff::ConstArray<T>&); \endcode
and we want to use it like
\code func(a) \endcode
......@@ -524,12 +523,12 @@ See also "\ref sec_design_multidimensional".
the full aff::SharedHeap together with the aff::Array object, since this must
return an aff::SharedHeap through aff::Array::representation to allow the
above operation (accessing data through aff::Series or constructing a
slice - see "\ref sec_design_interface_sparse").
slice - see \ref sec_design_interface_sparse).
\subsection sec_design_replicated_solution Solution
The most convincing solution (IMHO) to this problem is to use an
(additional) member of type aff::SharedHeap<T> in aff::Array<T> which
derives aff::ConstArray<T>.
inherits from aff::ConstArray<T>.
In consequence aff::ConstSharedHeap<T> is then a replicated within
aff::Array<T>. For a proper design we might consider to make
aff::ConstSharedHeap a virtual base, thus avoiding member data duplication.
......@@ -545,7 +544,7 @@ See also "\ref sec_design_multidimensional".
base of aff::Array and the aff::ConstSharedHeap base of aff::ConstArray
during construction. This is no major concern, but it is error-prone to some
degree. It is, however, much easier to keep them synchronous when using
member data instead if inheritance.
member data instead of inheritance.
<HR>
\section sec_design_copy Copy constructor and copy operator
......@@ -634,7 +633,7 @@ See also "\ref sec_design_multidimensional".
\sa DOXYGEN_MUST_SKIP_THIS
\note
Since we reduced to number of template parameters significantly in this
Since we reduced the 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
......@@ -664,10 +663,10 @@ in the structure of header files and may be activated in the future.
A declaration
\code void func(const Array<int>& v) \endcode
does not what we want (see "\ref sec_design_const_general"). It just
does not what we want (see \ref sec_design_const_general). It just
promises the constness of the container, not of the data. Within the
function the passed reference may be assigned to a non-const \c Array<int>,
which allows modification of the data (see "\ref page_representation").
which allows modification of the data (see \ref page_representation).
Thus we must use something like
\code void func(const ConstArray<int>& v) \endcode
......@@ -753,7 +752,7 @@ in the structure of header files and may be activated in the future.
where an array of elements of type \c T should be used, that we do not allow
to be changed. This design concept can be accomplished with a special traits
class that is specialized for \c const \c T and allows to derive a mutable
or const version of any type. Be further providing appropriate conversion
or const version of any type. By further providing appropriate conversion
operators, an \code Array<T> \endcode could be converted to an
\code Array<const T>, \endcode both sharing the same elements in memory.
In this approach, however, both container classes are completely
......@@ -766,14 +765,15 @@ in the structure of header files and may be activated in the future.
\par Deriving from a template specialization
The name commonality could still be achieved by deriving the Array<T> from
template specialization Array<const T>. In this case the specialization must
be used as a base class before it is actually defined. That's impropoer
be used as a base class before it is actually defined. That's improper
design.
\par Ensuring constness of elements through const qualifier of functions
We could strictly follow the concept (as we do anyway to some extent) to
couple the constness of the container to the constness of the contained
data. This is done by const qualifiers to member functions that allow
modification of the data. Avoid pitfalls, we have to consider copy operators
modification of the data. To avoid pitfalls,
we have to consider copy operators
and copy constructors then too. Both must not promise const-ness to their
arguments. While this works in principle, we would end up with a container
class which doesn't allow copies of const instances. Hence we could not
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README.changelog,v 1.35 2003-01-09 17:30:07 forbrig Exp $
* $Id: README.changelog,v 1.36 2003-06-27 18:12:51 tforb Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -21,7 +21,7 @@
/*! \page page_changelog ChangeLog (AFF)
$Id: README.changelog,v 1.35 2003-01-09 17:30:07 forbrig Exp $
$Id: README.changelog,v 1.36 2003-06-27 18:12:51 tforb Exp $
\sa \ref page_project_status
......@@ -35,7 +35,7 @@
- \b 04/01/2003 (thof)
- aff::deepcopy now converts to Tcontainer. And aff::util::Subarray
and aff::util::Slice therefore provide a Tcontainer typedef. See also
"\ref sec_design_interface_tcontainer".
\ref sec_design_interface_tcontainer.
- \b 03/01/2003 (thof)
- introduced lib/checkedcast.h and aff::util::SizeCheckedCast
......@@ -60,7 +60,7 @@
- \b 29/12/2002 (thof)
- aff::ConstArray and aff::ConstSeries now inherit from
aff::ConstSharedHeap. See "\ref sec_design_replicated".
aff::ConstSharedHeap. See \ref sec_design_replicated.
- added section about sparse interface
(\ref sec_design_interface_sparse)
- added section about accessing internals
......@@ -88,7 +88,7 @@
- \b !! Wolfgang pointed out a fundamental design error: Classes
aff::Array, aff::Series and aff::SharedHeap used a specialization of
themselves as base class to implement a version for const element type
(see "\ref sec_design_const"). Since specialization may only be declared
(see \ref sec_design_const). Since specialization may only be declared
after the general template itself, the base class definition is not
available at the point it is used in the declaration of the general
class template. We made the base class a completely independent class
......@@ -168,7 +168,7 @@
/*! \page page_project_status Project status (AFF)
$Id: README.changelog,v 1.35 2003-01-09 17:30:07 forbrig Exp $
$Id: README.changelog,v 1.36 2003-06-27 18:12:51 tforb Exp $
\sa \ref page_changelog
......
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.15 2003-06-27 14:20:40 tforb Exp $
* $Id: README,v 1.16 2003-06-27 18:12:51 tforb Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -80,7 +80,7 @@ deep copy (elementwise copy) and a shallow copy (copying the representation).
pointer on creation. In this case, memory management lies outside the
representation class and the underlying aff::SHeap object will \em never
call the delete operator in the destructor. This is usefull when interfacing
arrays allocated trhough Fortran code subroutines.
arrays allocated through Fortran code subroutines.
Creating an array projection may be
done by copying the representation (reference to free store) with an array
......@@ -290,7 +290,7 @@ Aspects to consider:
the same common block from tests/f77test.cc through calls to Fortran
subroutines.
Addtionally to the considerations for "\ref sec_fortran_call" we have to
Addtionally to the considerations for \ref sec_fortran_call we have to
discuss the following:
- f77interface::fillarray passes AFF arrays to Fortran code just in the
way f77interface::fill discussed above. Since Fortran doesn't know of
......@@ -298,7 +298,7 @@ Aspects to consider:
\code const aff::Array<float>& \endcode
rather than
\code const aff::ConstArray<float>& \endcode
(see also "\ref sec_design_const").
(see also \ref sec_design_const).
- f77interface::sums has to create an AFF array of appropriate size before
passing a pointer to the underlying Fortran subroutine. Since the
dimensions of fixed sized Fortran arrays are usually given by parameter
......
/*! \file iteratable.h
* \brief Interface base class template definition
*
* ----------------------------------------------------------------------------
*
* $Id: iteratable.h,v 1.1 2003-06-27 18:12:52 tforb Exp $
* \author Thomas Forbriger
* \date 27/06/2003
*
* Interface base class template definition
*
* Copyright (c) 2003 by Thomas Forbriger (BFO Schiltach)
*
* REVISIONS and CHANGES
* - 27/06/2003 V1.0 Thomas Forbriger
*
* ============================================================================
*/
// include guard
#ifndef AFF_ITERATABLE_H_VERSION
#define AFF_ITERATABLE_H_VERSION \
"AFF_ITERATABLE_H V1.0"
#define AFF_ITERATABLE_H_CVSID \
"$Id: iteratable.h,v 1.1 2003-06-27 18:12:52 tforb Exp $"
namespace aff {
/*! Base class template defining mandatory interface for iteratable containers
*
* This uses the Barton and Nackman trick for class template inheritance. The
* class template aff::Iteratable is a base class to all iteratable
* containers, i.e. containers that may be used together with with the
* aff::Iterator class template. In case you define a function template the
* may take any interatable container class as argument type for browsing
* elements, use a declaration like
* \code
* template<class C>
* void func(const aff::Iteratable<C>& cont);
* \endcode
*
* \todo
* Implement aff::Iteratable
*
* \todo
* Inherit aff::Array and aff::Series from aff::Iteratable
*
* \todo
* explain why this construct is helpful
*/
template<class C>
class Iteratable {
public:
private:
//! reference to leaf
C& Mleaf;
}; // class Iteratable
} // namespace aff
#endif // AFF_ITERATABLE_H_VERSION (includeguard)
/* ----- END OF iteratable.h ----- */
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment