src/TCollection/TCollection_Array1.cdl

   1 -- Copyright (c) 1998-1999 Matra Datavision
   2 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   3 --
   4 -- The content of this file is subject to the Open CASCADE Technology Public
   5 -- License Version 6.5 (the "License"). You may not use the content of this file
   6 -- except in compliance with the License. Please obtain a copy of the License
   7 -- at http://www.opencascade.org and read it completely before using this file.
   8 --
   9 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  10 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  11 --
  12 -- The Original Code and all software distributed under the License is
  13 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  14 -- Initial Developer hereby disclaims all such warranties, including without
  15 -- limitation, any warranties of merchantability, fitness for a particular
  16 -- purpose or non-infringement. Please see the License for the specific terms
  17 -- and conditions governing the rights and limitations under the License.
  18
  19 generic class Array1 from TCollection (Array1Item as any)
  20
  21 raises  RangeError from Standard,
  22         DimensionMismatch from Standard,
  23         OutOfRange from Standard,
  24         OutOfMemory from Standard
  25
  26         ---Purpose: The class Array1 represents unidimensionnal arrays
  27         --          of fixed size dynamically dimensioned at construction time..
  28         --
  29         --          The range of the index is user defined.
  30         --
  31         --          As with a C array, the access time to an Array1
  32         --          indexed item is constant and is
  33         --          array-size-independent. Arrays are commonly
  34         --          used as elementary data structures for more complex objects.
  35         --          Array1 is a generic class, which depends on
  36         --          Item, the type of element in the array.
  37         --          An array1 can be constructed with a "C array".
  38         --          This functionality is useful to call methods expecting
  39         --          an Array1. It allows to carry the bounds inside the arrays.
  40         --
  41         --  Examples: Item tab[100]; //  An example with a C array
  42         --          Array1OfItem ttab (tab[0],1,100);
  43         --
  44         --          Array1OfItem tttab (ttab(10),10,20); // a slice of ttab
  45         --
  46         --          If you want to reindex an array from 1 to Length do :
  47         --
  48         --          Array1 tab1(tab(tab.Lower()),1,tab.Length());
  49         --
  50         --  Warning: Programs client of such a class must be independant
  51         --          of the range of the first element. Then, a C++ for
  52         --          loop must be written like this
  53         --
  54         --          for (i = A.Lower(); i <= A.Upper(); i++)
  55
  56
  57
  58 is
  59
  60     Create (Low, Up: Integer from Standard)
  61     returns  Array1 from TCollection
  62         ---Purpose: Creates an array  of lower  bound <Low>  and upper
  63         --          bound <Up>. Range  error  is raised  when <Up>  is
  64         --          less than <Low>.
  65     raises
  66         RangeError  from Standard,
  67         OutOfMemory from Standard;
  68         ---C++: inline
  69
  70     Create(Item : Array1Item;
  71            Low, Up: Integer from Standard)
  72     returns Array1 from TCollection
  73         ---Purpose: Creates an array sharing datas with a C array.
  74         --          Example:
  75         --            Item tab[100];
  76         --            Array1OfItem thetab (tab[0],1,100);
  77         --
  78         --  Warning: The validity of Low and Up values are under the responsability
  79         --          of the user.
  80         --          The C array must be a validate address during the life of
  81         --          the Array1.
  82     raises
  83         RangeError  from Standard;
  84         ---C++: inline
  85
  86     Init (me: in out; V: Array1Item);
  87         ---Purpose: Initializes the array with a given value.
  88         ---C++: inline
  89
  90     Destroy (me: in out);
  91         ---Purpose: Frees the  allocated   area  corresponding  to the
  92         --          array.   If  the  array   was constructed  either from  a
  93         --          C Array (when method Allocated returns False)
  94         --          the Destroy doesn't delete the area.
  95         --
  96         ---C++: alias ~
  97         ---C++: inline
  98
  99     IsAllocated (me) returns Boolean from Standard;
 100         ---Purpose: Returns True if the data was allocated by the array constructors.
 101         --          (i.e not a slice neither a C array)
 102         ---C++: inline
 103
 104     Assign (me: in out; Other: Array1 from TCollection)
 105     returns Array1 from TCollection
 106         ---Purpose: Copies the contents of <Other> into <me>.  <Other>
 107         --          and <me> must have the same dimension.
 108         --      This method is an alias of operator =.
 109         -- Example
 110         -- TColStd_Array1OfInteger
 111         -- t1(1,20), t2(1,20);
 112         -- t1.Init(3);
 113         -- t2 = t1;
 114         -- assert ( t2(10) == 3 );
 115         -- Exceptions
 116         -- Standard_DimensionMismatch if this array
 117         -- and array Other do not have the same dimension.
 118         ---C++: alias operator =
 119         ---C++: return const &
 120     raises DimensionMismatch from Standard;
 121
 122     Length (me) returns Integer from Standard;
 123         ---Purpose: Returns the number of elements of <me>.
 124         --
 125         ---C++: inline
 126
 127     Lower (me) returns Integer from Standard;
 128         ---Purpose:  Returns the lower bound.
 129         -- Warning
 130         --Client programs of the Array1 class must be independent of the first item range.--
 131         ---C++: inline
 132
 133     Upper (me) returns Integer from Standard;
 134         ---Purpose: Returns the upper bound.
 135         -- Warning
 136         --Client programs of the Array1 class must be independent of the first item range.--
 137         ---C++: inline
 138
 139     SetValue (me : out; Index: Integer from Standard; Value: Array1Item)
 140         ---Purpose: Assigns the value <Value> to the <Index>-th item of this array.
 141         -- Example
 142         -- TColStd_Array1OfInteger
 143         -- array(0,100);
 144         -- array.SetValue(3,1515);
 145         -- assert (array(3) == 1515 );
 146         -- Exceptions
 147         -- Standard_OutOfRange if Index lies outside the bounds of this array.
 148     ---C++: inline
 149     raises OutOfRange from Standard;
 150
 151     Value (me; Index:Integer from Standard) returns any Array1Item
 152         ---Purpose: Return the value of  the  <Index>th element of the
 153         --          array.
 154         --
 155         ---C++: alias operator ()
 156         ---C++: return const &
 157         ---C++: inline
 158     raises OutOfRange from Standard;
 159
 160     ChangeValue (me: in out; Index:Integer from Standard) returns any Array1Item
 161         ---Purpose: return the value  of the <Index>th element  of the
 162         --          array.
 163         --
 164         ---C++: alias operator ()
 165         ---C++: return &
 166         ---C++: inline
 167     raises OutOfRange from Standard;
 168
 169     Create (AnArray : Array1 from TCollection)
 170     returns Array1 from TCollection
 171     is private;
 172         ---Purpose: Creates an Array1 by copy of an Array1.
 173
 174 fields
 175
 176         myLowerBound : Integer;
 177         myUpperBound : Integer;
 178         myStart      : Address;
 179         isAllocated  : Boolean;
 180
 181 end Array1 ;
 182