README 26.8 KB
Newer Older
thomas.forbriger's avatar
thomas.forbriger committed
1
/*! \file libaff/README
thomas.forbriger's avatar
thomas.forbriger committed
2
 * \brief C++ containers for numbers (libaff)
3
4
5
 *
 * ----------------------------------------------------------------------------
 *
thomas.forbriger's avatar
thomas.forbriger committed
6
 * $Id: README,v 1.14 2002-12-29 00:09:05 forbrig Exp $
7
8
9
 * 
 * Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt) 
 * 
thomas.forbriger's avatar
thomas.forbriger committed
10
 * C++ containers for numbers (libaff)
11
12
 *
 * This file contains:
thomas.forbriger's avatar
thomas.forbriger committed
13
 *  - documentation of namespace aff
14
15
 *  - mainpage text
 *  - documentation for pages:
16
 *    - \ref page_design
17
18
 *    - \ref page_using
 *    - \ref page_notes
19
 *    - \ref page_naming
20
21
 * 
 * REVISIONS and CHANGES 
thomas.forbriger's avatar
thomas.forbriger committed
22
 *  - 06/12/2002   V1.0   Thomas Forbriger (copied from libcontxx)
thomas.forbriger's avatar
thomas.forbriger committed
23
24
25
26
27
 *  - 20/12/2002   V1.1   (thof)
 *                        - complete revision of this file
 *                        - there are major gaps in
 *                          -# \ref sec_design_multidimensional
 *                          -# \ref page_using
thomas.forbriger's avatar
thomas.forbriger committed
28
29
30
31
32
 *  - 28/12/2002   V1.2   (thof)
 *                        - new term for containers of const elements
 *                        - added documentation regarding the concept of 
 *                          const correctness
 *                        - added documentation regarding member typedefs
33
34
35
36
37
38
39
 * 
 * ============================================================================
 */

/*! \brief Root namespace of library
  
  This namespace contains all modules of the library
thomas.forbriger's avatar
thomas.forbriger committed
40
41
42
  (see \ref sec_main_modules). 
  Here you should find all components, the user needs to work with this
  library.
43
  When working with the binary version of the library, you have to use
thomas.forbriger's avatar
thomas.forbriger committed
44
  aff::prebuilt in place of aff (see \ref sec_design_binary).
45
 */
46
47
namespace aff {
} // namespace aff
48
49
50
51
52
53

/*======================================================================*/

/*! \mainpage

\author Thomas Forbriger
thomas.forbriger's avatar
thomas.forbriger committed
54
55
56
\author Wolfgang Friederich
\since December 2002
\date December 2002
57
\version V1.0
thomas.forbriger's avatar
thomas.forbriger committed
58
$Id: README,v 1.14 2002-12-29 00:09:05 forbrig Exp $
59
60

  Contents of this page:
61
  - \ref sec_main_aims
62
  - \ref sec_main_modules
thomas.forbriger's avatar
thomas.forbriger committed
63
64
    - \ref sec_main_modules_basic
    - \ref sec_main_modules_extended
thomas.forbriger's avatar
thomas.forbriger committed
65
  - \ref sec_main_peculiar
66
67

  Additional information:
68
69
70
71
  - \ref page_design
  - \ref page_using
  - \ref page_notes
  - \ref page_naming
72
  - \ref page_representation
thomas.forbriger's avatar
thomas.forbriger committed
73
  - \ref page_fortran
thomas.forbriger's avatar
thomas.forbriger committed
74
  - \ref page_changelog
thomas.forbriger's avatar
thomas.forbriger committed
75
  - \ref page_project_status
76
77
78
79
80
81
82

\section sec_main_aims Aims of the library
  
  The AFF (Array of Friederich and Forbriger) is a lightweight class library.
  It offers a simple and easy to use container for numbers as is necessary in
  numerical code. The offered array always has a rectangular strided layout,
  reference semantics (through counted references) and a Fortran layout in
thomas.forbriger's avatar
thomas.forbriger committed
83
  memory. The interface is intentionally kept sparse to keep compilation times
84
85
86
87
88
89
90
  small. The array itself is meant to be used to pass numbers from one program
  module to the other. If you want to exploit the power of expression
  templates, pass the array contents to something like Blitz++.

  \sa \ref sec_notes_need

/*----------------------------------------------------------------------*/
91
92
93

\section sec_main_modules Modules of the library

94
95
  The main module is the array class aff::Array. It provides basic
  functionality through its interface. See the explanation there.
thomas.forbriger's avatar
thomas.forbriger committed
96
97
  It is presented in aff/array.h and aff/binarray.h (see also 
  \ref sec_design_binary).
thomas.forbriger's avatar
thomas.forbriger committed
98
  The object code is placed in libaff.a.
thomas.forbriger's avatar
thomas.forbriger committed
99
100
101
102
103

\subsection sec_main_modules_basic Basic array modules

  By including aff/array.h you will get access to the following modules:

thomas.forbriger's avatar
thomas.forbriger committed
104
  -# aff::Array is the main array interface (see example tests/arraytest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
105
  -# aff::Strided is the shape of a strided Fortran array and defines the
thomas.forbriger's avatar
thomas.forbriger committed
106
107
                memory layout of aff::Array objects (see example
                tests/shapetest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
108
109
110
  -# 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
thomas.forbriger's avatar
thomas.forbriger committed
111
                "\ref page_representation" and example tests/reprtest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
112
113
  -# aff::SimpleRigidArray is a linear array with size fixed at compile-time.
                There are several inline functions defined for operations with
thomas.forbriger's avatar
thomas.forbriger committed
114
115
                this array class (see example tests/simplearraytest.cc).
  -# aff::Exception is the exception base class used in the library.
thomas.forbriger's avatar
thomas.forbriger committed
116
  -# aff::AllocException is the exception that indicated a failed memory
thomas.forbriger's avatar
thomas.forbriger committed
117
                allocation(see also "\ref group_error").
thomas.forbriger's avatar
thomas.forbriger committed
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

  It additionally offers the following type definitions:

  -# aff::Tsubscript is the type of subscripts to arrays (positive and
                     negative).
  -# aff::Tsize      is the type of size values (non-negative).
  -# aff::Tdim       is the type of the dimension index (small, non-negative).

\subsection sec_main_modules_extended Extensions
  
  The library provides some additional modules. You need only include the
  header file of those modules that you really want to use in addition to the
  basic aff::Array functionality.
  These additional modules are:

thomas.forbriger's avatar
thomas.forbriger committed
133
  -# aff::Shaper presented in aff/shaper.h and used to pass Fortran layouts
thomas.forbriger's avatar
thomas.forbriger committed
134
                 to array constructors (see example tests/shapetest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
135
136
137
  -# aff::Series presented in aff/series.h which is used to interface linear
                 sequences of data (like time series or Fourier spectra).
  -# aff::Iterator presented in aff/iterator.h which is an iterator interface
thomas.forbriger's avatar
thomas.forbriger committed
138
139
                 to containers like aff::Array or aff::Series (see example
                 tests/helpertest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
140
141
142
143
  -# aff::Range presented in aff/lib/range.h which is usefull where ever you
                 need to deal with numerical ranges (calculate with them, find 
                 the smallest in a set, etc.).
  -# aff::Subarray presented in aff/subarray.h to conveniently create
thomas.forbriger's avatar
thomas.forbriger committed
144
145
                 subarrays from aff::Array objects (see example
                 tests/helpertest.cc).
thomas.forbriger's avatar
thomas.forbriger committed
146
  -# aff::Slice presented in aff/slice.h to conveniently create
thomas.forbriger's avatar
thomas.forbriger committed
147
148
                 slices from aff::Array objects (see example
                 tests/helpertest.cc).
149
150
  -# aff::FortranArray and its associate aff::util::FortranShape are presented
                 in aff/fortranshape.h. They calculate a Fortran 77 array
thomas.forbriger's avatar
thomas.forbriger committed
151
152
                 layout (leading dimensions) from a given AFF array (see
                 example tests/f77test.cc).
thomas.forbriger's avatar
thomas.forbriger committed
153
154
  -# 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
thomas.forbriger's avatar
thomas.forbriger committed
155
                 debugging your code. See also "\ref group_helpers".
thomas.forbriger's avatar
thomas.forbriger committed
156

157

thomas.forbriger's avatar
thomas.forbriger committed
158
159
  In the \ref sec_design_binary "binary version" some of the modules
  (aff::Array and aff::SharedHeap) are presented in namespace aff::prebuilt.
160

161
  \sa \ref sec_design_namespaces
thomas.forbriger's avatar
thomas.forbriger committed
162
  \sa \ref sec_naming_files
163
164
165

/*----------------------------------------------------------------------*/

thomas.forbriger's avatar
thomas.forbriger committed
166
\section sec_main_peculiar Peculiarities
167

thomas.forbriger's avatar
thomas.forbriger committed
168
169
170
171
172
173
\par Containers use counted references
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".

thomas.forbriger's avatar
thomas.forbriger committed
174
175
176
177
\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".
178

thomas.forbriger's avatar
thomas.forbriger committed
179
180
181
182
183
184
\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".
185

186
*/
187

188
/*======================================================================*/
189

190
/*! \page page_design Design decisions
191

192
  Contents of this page:
thomas.forbriger's avatar
thomas.forbriger committed
193
  - \ref sec_design_interface
194
195
196
197
198
  - \ref sec_design_copy
  - \ref sec_design_namespaces
  - \ref sec_design_binary
  - \ref sec_design_multidimensional
  - \ref sec_design_const
199

thomas.forbriger's avatar
thomas.forbriger committed
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
\section sec_design_interface Common interface elements

\subsection sec_design_interface_typedef Member typedefs

  Class templates like aff::Iterator may be used with any container class,
  that provides an appropriate interface. This interface convention concerns
  the access to the type of related objects. I will explain by example:

  We use an iterator \c i which was declared
  \code aff::Iterator<Cont> i \endcode
  for a container of type \c Cont, it expects to find a corresponding
  container class that promises constness of the elements through 
  \code Cont::Tcontainer_of_const \endcode
  or short
  \code Cont::Tcoc \endcode

  For aff::ConstArray the type aff::ConstArray::Tcoc is just the class itself.
  However aff::Array::Tcoc gives an aff::ConstArray.

  \sa aff::SharedHeap::Tcontainer_of_const
  \sa aff::ConstSharedHeap::Tcontainer_of_const
  \sa aff::Array::Tcontainer_of_const
  \sa aff::ConstArray::Tcontainer_of_const
  \sa aff::Series::Tcontainer_of_const
  \sa aff::ConstSeries::Tcontainer_of_const

  In the same way we may access the appropriate element type through
  \code Cont::Tvalue \endcode
  which is \c T for aff::Array<T> and \c const \T for aff::ConstArray<T>.
  However a 
  \code Cont::Tconst_value \endcode
  will always provide a type with const qualifier.

  \sa aff::Array::Tvalue
  \sa aff::Array::Tconst_value
  \sa aff::ConstArray::Tvalue
  \sa aff::ConstArray::Tconst_value
  \sa aff::Series::Tvalue
  \sa aff::Series::Tconst_value
  \sa aff::ConstSeries::Tvalue
  \sa aff::ConstSeries::Tconst_value

  In the same way we may access the type of the appropriate representation
  (although the base class of any container is always an aff::SharedHeap) by
  \code Cont::Trepresentation \endcode

  \sa aff::Array::Trepresentation
  \sa aff::ConstArray::Trepresentation
  \sa aff::Series::Trepresentation
  \sa aff::ConstSeries::Trepresentation

  \b Notice: Using these typedefs (and also the typedefs for the shape class,
  etc.) improves the maintainability of your code. Think of using the $HOME
  variable in shell scripts. Once the name of your home directory changes, you
  need not modify all your shell scripts. Now consider one day your shape
  class might be renamed...

/*----------------------------------------------------------------------*/

259
260
261
262
263
264
265
266
267
\section sec_design_copy Copy constructor and copy operator
  
  Usually we would expect the copy operator and the copy constructor to have
  the same semantics. Here the copy constructor of aff::Array must have
  reference semantics (it does a shallow copy). This is necessary to allow
  arrays as return values from functions. In this case the copy constructor is
  automatically invoked. Reference semantics ensure a minimal overhead. in
  terms of memory usage and execution time.

thomas.forbriger's avatar
thomas.forbriger committed
268
269
  In the case of the copy (assignment) operator things are less clear: 
  If we define the
270
  copy operator to have reference semantics, it has the same behaviour as the
thomas.forbriger's avatar
thomas.forbriger committed
271
  copy constructor. That is what we usually would expect. An expression like
272
  \code
273
  A=B;
274
  \endcode
275
276
277
278
  means that array \c A drops its reference to the memory location it was
  pointing to and forgets its previous shape. Following this statement array
  \c A will refer to the same memory location as array \c B and will have the
  same shape. Both are indistinguishable.
279

thomas.forbriger's avatar
thomas.forbriger committed
280
281
282
  However, in many cases (most cases?) we will use the copy (assignment)
  operator in the
  sense of a mathematical equation. This may read like
283
  \code
284
  A=B+C;
285
  \endcode
286
  although expressions like this are not yet supported by the library
thomas.forbriger's avatar
thomas.forbriger committed
287
  features. In this case we do not mean that \c A should drop it reference. 
288
289
290
  \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.
291

thomas.forbriger's avatar
thomas.forbriger committed
292
293
294
295
296
297
298
  \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.
299
300
301

/*----------------------------------------------------------------------*/

302
\section sec_design_namespaces Namespaces
303

304
  We group all code in two namespaces. Major modules which will be accessed by
thomas.forbriger's avatar
thomas.forbriger committed
305
306
307
308
309
310
311
312
313
314
315
  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.
316
317
318

/*----------------------------------------------------------------------*/

319
\section sec_design_binary Binary library
320
321
322

  We provide a binary version of the library. It contains a set of prebuilt
  class objects. Using this version and linking against the binary library
323
  libaff.a should reduce compilation times in comparison to complete
324
325
326
327
328
329
330
  template evaluation.
  This will become more significant the more code is factored out to separate
  definition headers.
  This approach offers no improvement with inlined code (which we use
  extensively in array access functions).

  To use the binary version you should include binarry.h in place of array.h
thomas.forbriger's avatar
thomas.forbriger committed
331
332
  You will find modules aff::Array and aff::SharedHeap
  in aff::prebuilt that are in aff in the full-template version.
333
334
335
336

  \sa tests/binarraytest.cc
  \sa binarray.h

337
338
  The inclusion of header files is controlled by a set of preprocessor macros.
  \sa AFF_PREBUILT
339
  \sa AFF_INDEXCHECK
340
341
342
  \sa AFF_NO_DEFINITIONS
  \sa AFF_COMPILING_LIBRARY
  \sa DOXYGEN_MUST_SKIP_THIS
343

thomas.forbriger's avatar
thomas.forbriger committed
344
345
346
347
348
349
350
\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
351

352
/*----------------------------------------------------------------------*/
353

354
\section sec_design_multidimensional Multidimensional arrays
355

356
357
  \todo
  Explain Wolfgangs idea of multidimensional arrays.
358

359
/*----------------------------------------------------------------------*/
360

361
362
\section sec_design_const Notes on the const-correctness of arrays

thomas.forbriger's avatar
thomas.forbriger committed
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
\subsection sec_design_const_problem Where is the problem?
  When passing a container (i.e. an array) to a function, we would like to
  promise that the values in the container are not modified, in case the
  function uses only read-access. Consider a declaration
  \code void func(const int& v) \endcode
  of a function that takes an argumtn of type \c int an promises that this
  will not be modified. Passing by reference is used, because this is more
  efficient than passing by value (in particular for large objects - which is
  not the case for \c int). And qualifying the type \c const promises that the
  value passed by reference will not be changed.

  A declaration
  \code void func(const Array<int>& v) \endcode
  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").

  Thus we must use something like
  \code void func(const ConstArray<int>& v) \endcode
  where \c ConstArray<int> does not allow modification of the data (be no
  means - copying and conversions included) and may be derived from an 
  \c Array<int> by a trivial conversion (like a conversion to a public base
  class).

\subsection sec_design_const_approach The approach used in this library
thomas.forbriger's avatar
thomas.forbriger committed
389
390
391
392
393
394
395
396
397
398
399
400
401
402

  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
thomas.forbriger's avatar
thomas.forbriger committed
403
  aff::ConstArray<int> C(A);
thomas.forbriger's avatar
thomas.forbriger committed
404
405
406
407
408
409
410
411
412
413
  \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
thomas.forbriger's avatar
thomas.forbriger committed
414
  void func(const aff::ConstArray<int>& array);
thomas.forbriger's avatar
thomas.forbriger committed
415
416
417
418
419
420
  \endcode
  and may be called like
  \code
  aff::Array<int> A(12,12);
  func(A);
  \endcode
thomas.forbriger's avatar
thomas.forbriger committed
421
422
  The type conversion from \code aff::Array<int> \endcode to 
  \code const aff::ConstArray<int>& \endcode is trivial and has no runtime
thomas.forbriger's avatar
thomas.forbriger committed
423
424
  overhead.

thomas.forbriger's avatar
thomas.forbriger committed
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
  Each container class must deal with this issue on its own. Sorry...

  \sa aff::ConstSharedHeap
  \sa aff::ConstArray
  \sa aff::ConstSeries

\par Restrictions for containers with const qualifier
  Strictly distinguishing between constness of the container and constness of
  the contained data would allow to modify data through an object \c c that
  was declared
  \code const Array<int> c; \endcode
  The containers in this library (aff::Array, etc.), however, provide only a
  reduced set of access operators, when declared with \c const qualifier.
  They do not allow direct modification of the data (only through assignment
  to a non-const container instance).
thomas.forbriger's avatar
thomas.forbriger committed
440
441
442
  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.
thomas.forbriger's avatar
thomas.forbriger committed
443
444
445
446
447
448
  To ensure true constness of the data, you have to assign to the base class
  of the container. 
  Any container class (e.g. \c Cont) provides the type of container for const
  elements through a typedef Tcontainer_of_const 
  (i.e. \c Cont::Tcontainer_of_const) or short Tcoc.
  Remember that a \c const \c aff::Array always
thomas.forbriger's avatar
thomas.forbriger committed
449
450
451
  may be assigned to a mutable aff::Array, which in turn allows modification
  of the data!

thomas.forbriger's avatar
thomas.forbriger committed
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
\subsection sec_design_const_alternatives Alternatives

  Three alternatives to this concept have been discussed (and discarded).
  Both have the appealing property of needing only one class definition for
  each container (in contrast to a class and a base class in our case).
  Additionally both would offer name commonality for containers of non-const
  elements and containers of const elements.

\par Using arrays with element type \c const \c T
  A rather straight approach is to use the element type \c const \c T
  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
  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
  independent (although having the same name) due to their different template
  arguments. The conversion to the container for const elements is not a
  trivial conversion (like for a reference to a reference of a public base
  class) and must be done explicitely. That's inconvenient for the most common
  use (i.e. passing a container to a function).

\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
  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
  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
  return a container from a function, that ensures that the accessed data
  cannot be modified.
thomas.forbriger's avatar
thomas.forbriger committed
491
492
493

\subsection sec_design_const_general General considerations

494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
  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
  to the compiler. The array instances are values in the sense of C++ types
  and not references. Passing an \c const \c aff::Array to a function does
  not prohibit the function from assigning this instance to a non-const
  \c aff::Array, which then references the same memory area and allows the
  modification of the values contained in the array.

  Generally it has to be defined, what is meant by declaring an array instance
  to be \c const. In the first place this means constness of the container to
  the compiler. The compiler will ensure, that the container (array class) is
  not changed, thus no data member of the array is changed. This means that
  the array will keep the reference to the same data and that the
  index-mapping defined by the array shape may not be changed. However, the
  compiler will not prevent to change any data, the array refers to. 

  We may define access operators that have a non-const version that returns a
  reference to the data, allowing to change the data values together with a
  const version that returns a value of const reference, thus preventing the
  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
thomas.forbriger's avatar
thomas.forbriger committed
517
  const-ness of the source of the copy. The shape of the original array may
518
519
520
521
522
523
524
525
526
  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
  distinguish between const-ness of the container (array class instance) and
  the contained data (values in memory the arrays refers to).

  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
thomas.forbriger's avatar
thomas.forbriger committed
527
528
529
  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.
530
531
532
533
534
535
536
537
538
539
540
541

   -  The need of const-correctness is discussed in "Chapter 1 Introduction,
      C++ Conventions, Implementation of Vector and Matrix Classes" of
      "Numerical Recipes in C++". A link to a PDF file of this chapter is
      provided at "http://www.nr.com/cpp-blurb.html".
   - The "C++ FAQ Lite" discusses many aspects of const-correctness in Chapter
     18, which you find at
     "http://www.inf.uni-konstanz.de/~kuehl/cpp/cppfaq.htm/const-correctness.html".
   -  You may find my thoughts about const-correctness with containers that
      have reference semantics at
      "http://www.geophysik.uni-frankfurt.de/~forbrig/txt/cxx/tutorial/consthandle.doc/doc/html/index.html".

542
543
544
545
*/

/*======================================================================*/

546
/*! \page page_using HOWTO use this library
547

548
549
  Contents of this page:
  - \ref sec_using_constructor
thomas.forbriger's avatar
thomas.forbriger committed
550
  - \ref sec_using_examples
551
552

\section sec_using_constructor Constructing arrays
thomas.forbriger's avatar
thomas.forbriger committed
553
554
555
556
  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
557
  \code
thomas.forbriger's avatar
thomas.forbriger committed
558
559
  using namespace aff;
  Array<int> A(Shaper(-2,2)(4)(6,10));
560
  \endcode
thomas.forbriger's avatar
thomas.forbriger committed
561
  The shaper is presented in aff/shaper.h.
562

thomas.forbriger's avatar
thomas.forbriger committed
563
564
565
566
567
568
\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
569
570

\todo
thomas.forbriger's avatar
thomas.forbriger committed
571
572
We need more text and examples.

573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
*/


/*======================================================================*/

/*! \page page_notes General notes

  Contents of this page:
  - \ref sec_notes_need

\section sec_notes_need The need of an array library
  
  One major reason for replacing Fortran77 by C++ in numerical code is the
  convenience in expressing logistics. Data of different type and size may be
  packed into classes and encapsulated from the outside world. Most numerical
  results are to be stored in arrays, multi-dimensional arrays in particular.
  This library provides the basic functionality for storing many data of the
  same type in memory, passing them around between subroutines in an efficient
  way and accessing them through convenient interfaces. The main purpose of
  this library is not calculation but managing (passing between program
  modules, selection of subsets of the data) large amounts of numbers. In the
  future it might provide interfaces to libraries like blitz++ for finite
  difference calculations, MTL for linear algebra calculations, and POOMA for
  parallel computations.

598
599
600
601
*/

/*======================================================================*/

602
603
604
/*! \page page_naming Naming conventions

  Contents of this page:
thomas.forbriger's avatar
thomas.forbriger committed
605
606
607
  - \ref sec_naming_identifiers
  - \ref sec_naming_macros
  - \ref sec_naming_files
608

thomas.forbriger's avatar
thomas.forbriger committed
609
\section sec_naming_identifiers Classes, Typedefs, etc.
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627

  During coding it is sometimes helpfull to recognize the meaning of an
  identifier due to some signals in irs name. Therefor the following
  guidelines are used. The nameing of template parameters is left free for
  convenience.

  \par Classes
   
  Class names always start with a capital letter.

  \par Typedefs

  Typedefs always start with a capital \c T.

  \par Member data

  Member data identifiers always start with a capital \c M.

thomas.forbriger's avatar
thomas.forbriger committed
628
\section sec_naming_macros Preprocessor macros
629
630

  Preprocessor macros like include-guards should have the prefix "AFF_".
thomas.forbriger's avatar
thomas.forbriger committed
631
  The macros in the \ref group_helpers are an exception to this rule.
632

thomas.forbriger's avatar
thomas.forbriger committed
633
\section sec_naming_files Filenames
634
635
636
637
638
639
640

  Files with the extension \c .cc contain only non-template definitions. Files
  with the extension \c .h may contain prototypes, class declarations or
  template code. Files ending on \c def.h contain template code definitions
  that is factored out to be compilable into a binary library for explicit
  instantiation.

thomas.forbriger's avatar
thomas.forbriger committed
641
642
  The main directory %aff contains headers that are usually included by the
  user. A subdirectory %aff/lib contains additional headers that are mostly
643
644
  used internally.

645
646
647
*/

// ----- END OF README -----