Changeset 2917 in Sophya for trunk/SophyaLib/TArray/tarray.cc

Timestamp:

Feb 23, 2006, 2:50:26 PM (20 years ago)

Author:

ansari

Message:

Documentation + debug Range et extraction sous-tableaux , Reza 23/02/2006

File:

• trunk/SophyaLib/TArray/tarray.cc (modified) (8 diffs)

trunk/SophyaLib/TArray/tarray.cc

@@ -17 +17 @@
   Class for template arrays with numerical data types (int, float, complex).
 
-  This class implements arrays with number of dimensions up to
-  \ref BASEARRAY_MAXNDIMS "BASEARRAY_MAXNDIMS"
-
-  Standard arithmetic operations on numerical arrays are implemented,
-  as well as sub-array manipulation services.
+  This class handles arrays with number of dimensions up to
+  \ref BASEARRAY_MAXNDIMS "BASEARRAY_MAXNDIMS" (=5). The class has a performant 
+  memory management system, including reference sharing for the array data.
+  (copy constructor and sub-arrays (or slices)). 
+
+  An important feature of this class is the transparent handling of sub-arrays,
+  or slices. Arbitrary sub-arrays or slices can be defined, provided regular 
+  spacing along each array axe (or dimension). 
+  The second example below illustrate the use of this possibility.
+  
+  Standard arithmetic operations, sum or product as well as application of usual
+  math functions (Sin, Cos ...) on numerical arrays are implemented.
+  These operations usually provide high performance, despite of the complex 
+  memory management pattern.
+
+  ASCII input/output (or read write) and binary I/O (persistence) in different
+  formats are also provided through helper (or handler) classes.
+
+  This class is mainly intented for arrays with large number of data elements.
+  (Size() \> 100 .. 1000). Arrays with few data elements (\< 10) have significant 
+  memory overhead, due to variables describing array shape and memory organisation.
+  However, a single higher dimensional array can be used to represent a large number 
+  of identical size small arrays. For example, TArray<T> tab(2,2, 1000) can be used
+  to hold 1000 2x2 matrices.
+
   \b Array is a typedef for double precision floating point arrays ( TArray<r_8> )
+
   \sa SOPHYA::Range
   \sa SOPHYA::Sequence
   \sa SOPHYA::MathArray
+  \sa SOPHYA::NDataBlock
 
   \code
@@ -35 +57 @@
   es = 24, 35, 46, 57, 68;
   ia = es;
-  cout << "Array<int> ia = " << ia;
+  cout << "Array<int> ia = \n" << ia;
   // 2-D array of floats 
   TArray<r_4> b(6,4), c(6,4);
@@ -44 +66 @@
   // Arithmetic operations
   TArray<r_4> d = b+0.3f*c;
-  cout << "Array<float> d = " << d;  
+  cout << "Array<float> d = \n" << d;  
   \endcode
 
+  Example for sub-arrays, or slices
+  \code 
+  // Creating and initialising a 2-D (6 x 4) array of integers
+  TArray<int> iaa(6, 4);
+  iaa = RegularSequence(1,2);
+  cout << "Array<int> iaa = \n" << iaa;
+  // We extract a sub-array - data is shared with iaa
+  TArray<int> iae = iaa(Range(1, Range::lastIndex(), 3) ,
+                        Range::all(), Range::first() );
+  cout << "Array<int> iae=subarray(iaa) = \n" << iae;
+  // Changing iae elements changes corresponding iaa elements
+  iae = 0;
+  cout << "Array<int> iae=0 --> iaa = \n" << iaa;
+  \endcode 
 */
 
@@ -344 +380 @@
 
 
-//! Compact dimensions in one or more is equal to 1.
+/*!
+  \brief Compact arrays - supresses size=1 axes.
+  Changes the array rank (number of dimensions), suppressing all axes with size equal 1.
+  Example: 
+  Compacting Rank=NDim=5  Sizes=3x1x6x1x1  =====\>  Rank=NDim=2  Sizes=3x6 
+*/
 template <class T>
 TArray<T>& TArray<T>::CompactAllDimensions()
@@ -352 +393 @@
 }
 
-//! Compact dimensions if the last one is equal to 1.
+/*!
+  \brief Compact array taling dimensions, for size=1 traling axes.
+  Changes the array rank (number of dimensions), suppressing all axes with size equal 1,
+  after the last axe with size \> 1
+  Example: 
+  Compacting Rank=NDim=5  Sizes=3x1x6x1x1  =====\>  Rank=NDim=3  Sizes=3x1x6 
+*/
 template <class T>
 TArray<T>& TArray<T>::CompactTrailingDimensions()
@@ -393 +440 @@
 }
 
-//! Return array with elements packed
-/*!
+/*!
+  \brief Return a new array with elements packed in memory
+
+
   \param force : if true, pack elements in a new array.
                  If false and array is already packed, return
@@ -424 +473 @@
 /*!
   \param rx,ry,rz,rt,ru : range of extraction along dimensions
+  \param compact : if \b compact == true, compact trailing dimensions (suppressed if =1)
+  (See CompactTrailingDimensions() )
   \sa SOPHYA::Range
  */
 template <class T>
-TArray<T> TArray<T>::SubArray(Range rx, Range ry, Range rz, Range rt, Range ru) const
+TArray<T> TArray<T>::SubArray(Range rx, Range ry, Range rz, Range rt, Range ru, bool compact) const
 {
   if (NbDimensions() < 1) 
@@ -467 +518 @@
   UpdateSubArraySizes(ra, ndim, size, pos, step); 
   ra.DataBlock().Share(this->DataBlock());
+  if (compact) ra.CompactTrailingDim();
   ra.SetTemp(true);
   return(ra);