0024042: Performance improvements: Foundation Classes
[occt.git] / src / TCollection / TCollection_Array2.cdl
1 -- Created on: 1992-12-09
2 -- Copyright (c) 1992-1999 Matra Datavision
3 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
4 --
5 -- The content of this file is subject to the Open CASCADE Technology Public
6 -- License Version 6.5 (the "License"). You may not use the content of this file
7 -- except in compliance with the License. Please obtain a copy of the License
8 -- at http://www.opencascade.org and read it completely before using this file.
9 --
10 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
11 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
12 --
13 -- The Original Code and all software distributed under the License is
14 -- distributed on an "AS IS" basis, without warranty of any kind, and the
15 -- Initial Developer hereby disclaims all such warranties, including without
16 -- limitation, any warranties of merchantability, fitness for a particular
17 -- purpose or non-infringement. Please see the License for the specific terms
18 -- and conditions governing the rights and limitations under the License.
19
20
21 generic class Array2 from TCollection (Array2Item as any)
22
23         ---Purpose: The class Array2 represents bi-dimensionnal arrays 
24         --          of fixed size dynamically dimensioned at construction time. 
25         --          As with a C array, the access time to an Array2 indexed
26         --          item is constant and independent of the array size. Arrays
27         --          are commonly used as elementary data structures for more complex objects.
28         --          Array2 is a generic class, which depends on Item, the type of element in the array.
29         --          Warning
30         --          Array2 indexes start and end at a user-defined position.
31         --          Thus, when accessing an item you must base the indexes
32         --          on the lower and upper bounds of the array.
33
34 raises
35     RangeError from Standard,
36     OutOfRange from Standard,
37     OutOfMemory from Standard,
38     DimensionMismatch from Standard
39
40    
41
42 is
43     
44     Create (R1, R2, C1, C2: Integer from Standard) 
45     returns  Array2 from TCollection
46         ---Purpose: Creates an array of lower bound <R1><C1> and upper
47         --          bound <R2><C2>.    Range from  Standard  error  is
48         --          raised when <R2> is less than <R1> or <C2> is less
49         --          than <C1>.
50     raises 
51         RangeError  from Standard,
52         OutOfMemory from Standard;
53         ---C++: inline
54
55     Create (AnArray : Array2) 
56     returns Array2 from TCollection
57         ---Purpose: creates an Array2 by copy of an Array2.
58     raises OutOfMemory from Standard is private ;
59         ---C++: inline
60
61     Create (Item : Array2Item; R1, R2, C1, C2: Integer from Standard) 
62     returns  Array2 from TCollection
63         ---Purpose: Creates an double array sharing datas with a C array.
64         --          Examples:
65         --            Item tab[100][200];
66         --            Array2OfItem thetab (tab[0][0],1,100,1,200);
67         --               or
68         --            Item tab[10000];
69         --            Array2OfItem thetab (tab[0],1,100,1,100);
70         --            
71         --  Warning: The validity of R1,R2,C1,C2 values are under the responsability
72         --          of the user.
73         --          The C array must be a validate address during the life of
74         --          the Array2.
75     raises
76         RangeError  from Standard,
77         OutOfMemory from Standard;
78         ---C++: inline
79         
80     Init(me : in out; V : Array2Item);
81         ---Purpose: Initializes this array with the value <Value>.
82         ---C++: inline
83
84     Destroy (me : in out );
85         ---Level: Advanced
86         ---Purpose: Frees   the allocated   area corresponding to  the
87         --          array.   If  the array    was  constructed from  a
88         --          DoubleArray the Destroy doesn't delete the area.
89         --          
90         ---C++: alias ~
91         ---C++: inline
92
93     Assign (me: in out; Other: Array2) 
94     returns Array2 from TCollection
95         ---Purpose: Copies the contents of <Other> into <me>.
96         --          <Other> and <me> must have the same dimension.
97         -- Example
98         -- TColStd_Array2OfInteger tab1(1,10,1,10);
99         -- TColStd_Array2OfInteger tab2(11,20,11,20);
100         -- tab1.Init(4);
101         -- tab2 = tab1;
102         -- assert ( tab2(15,15) == 4 );
103         -- Exceptions
104         -- Standard_DimensionMismatch if this array and array
105         -- Other do not have the same dimensions.
106         ---C++: alias operator =
107         ---C++: return const &    
108     raises DimensionMismatch from Standard;
109
110     ColLength (me) returns Integer from Standard;
111         ---Level: Public
112         ---Purpose: Return the number of rows of <me>.
113         --          
114         ---C++: inline
115
116     RowLength (me) returns Integer from Standard;
117         ---Level: Public
118         ---Purpose: Returns the number of columns of <me>.
119         --          
120         ---C++: inline
121
122     LowerCol (me) returns Integer from Standard;
123         ---Level: Public
124         ---Purpose: Returns the lower column number of the array.
125         --          
126         ---C++: inline
127
128     LowerRow (me) returns Integer from Standard;
129         ---Level: Public
130         ---Purpose:  Returns the lower row number of the array.
131         --          
132         ---C++: inline
133
134     UpperCol (me) returns Integer from Standard;
135         ---Level: Public
136         ---Purpose:  Returns the upper column number of the array.
137         --          
138         ---C++: inline
139
140     UpperRow (me) returns Integer from Standard
141         ---Level: Public
142         ---Purpose:  Returns the upper row number of the array.
143         --          
144         ---C++: inline
145     is static ;
146
147     SetValue (me : in out; Row, Col: Integer from Standard; Value: Array2Item) 
148         ---Purpose: Purpose
149         -- Assigns the value Value to the (Row,Col) item of this array.
150         -- Example
151         -- TColStd_Array2OfInteger array(0,100,0,100);
152         -- array.SetValue(3,3,1515);
153         -- assert ( array(3,3) == 1515 );
154         -- Exceptions
155         -- Standard_OutOfRange if Row or Col lies outside the bounds of this array.
156         ---C++: inline
157         raises OutOfRange from Standard;
158
159
160     Value (me; Row,Col: Integer from Standard) returns any Array2Item
161         ---Level: Public
162         ---Purpose: Returns the value of the element of index 
163         --          <Row><Col>
164         --
165         ---C++: alias operator()
166         ---C++: return const &
167         ---C++: inline
168     raises OutOfRange from Standard;
169
170
171     ChangeValue (me: in out; Row,Col: Integer from Standard) returns any Array2Item
172         ---Level: Public
173         ---Purpose: Returns the value of the element of index 
174         --          <Row><Col>
175         --
176         ---C++: alias operator()
177         ---C++: return &
178         ---C++: inline
179     raises OutOfRange from Standard;
180
181     Allocate (me: in out) raises OutOfMemory is private;
182         ---Level: Private
183
184 fields
185
186         myLowerRow    : Integer from Standard ;
187         myLowerColumn : Integer from Standard ;
188         myUpperRow    : Integer from Standard ;
189         myUpperColumn : Integer from Standard ;
190         myDeletable   : Boolean;
191         myData        : Address;
192         
193 end Array2 ;