src/TCollection/TCollection_Array1.cdl

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