0024042: Performance improvements: Foundation Classes
[occt.git] / 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