xref: /aoo4110/main/cppu/inc/com/sun/star/uno/Sequence.h (revision b1cdbd2c)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _COM_SUN_STAR_UNO_SEQUENCE_H_
24 #define _COM_SUN_STAR_UNO_SEQUENCE_H_
25 
26 #include "typelib/typedescription.h"
27 #include "uno/sequence2.h"
28 #include "com/sun/star/uno/Type.h"
29 #include "rtl/alloc.h"
30 
31 #if ! defined EXCEPTIONS_OFF
32 #include <new>
33 #endif
34 
35 
36 namespace rtl
37 {
38 class ByteSequence;
39 }
40 
41 namespace com
42 {
43 namespace sun
44 {
45 namespace star
46 {
47 namespace uno
48 {
49 
50 /** Template C++ class representing an IDL sequence. Template argument is the
51     sequence element type.  C++ Sequences are reference counted and shared,
52     so the sequence keeps a handle to its data.  To keep value semantics,
53     copies are only generated if the sequence is to be modified (new handle).
54 
55     @tplparam E element type of sequence
56 */
57 template< class E >
58 class Sequence
59 {
60     /** sequence handle
61         @internal
62     */
63     uno_Sequence * _pSequence;
64 
65 public:
66     // these are here to force memory de/allocation to sal lib.
67     /** @internal */
operator new(size_t nSize)68     inline static void * SAL_CALL operator new ( size_t nSize )
69         SAL_THROW( () )
70         { return ::rtl_allocateMemory( nSize ); }
71     /** @internal */
operator delete(void * pMem)72     inline static void SAL_CALL operator delete ( void * pMem )
73         SAL_THROW( () )
74         { ::rtl_freeMemory( pMem ); }
75     /** @internal */
operator new(size_t,void * pMem)76     inline static void * SAL_CALL operator new ( size_t, void * pMem )
77         SAL_THROW( () )
78         { return pMem; }
79     /** @internal */
operator delete(void *,void *)80     inline static void SAL_CALL operator delete ( void *, void * )
81         SAL_THROW( () )
82         {}
83 
84     /** Static pointer to typelib type of sequence.
85         Don't use directly, call getCppuType().
86         @internal
87     */
88     static typelib_TypeDescriptionReference * s_pType;
89 
90     /** typedefs the element type of the sequence
91     */
92     typedef E ElementType;
93 
94     /** Default constructor: Creates an empty sequence.
95     */
96     inline Sequence() SAL_THROW( () );
97 
98     /** Copy constructor: Creates a copy of given sequence.
99 
100         @param rSeq another sequence of same type
101     */
102     inline Sequence( const Sequence< E > & rSeq ) SAL_THROW( () );
103 
104     /** Constructor: Takes over ownership of given sequence.
105 
106         @param pSequence a sequence
107         @param dummy SAL_NO_ACQUIRE to force obvious distinction to other
108         constructors
109     */
110     inline Sequence( uno_Sequence * pSequence, __sal_NoAcquire )
111         SAL_THROW( () );
112 
113     /** Constructor: Creates a copy of given elements.
114 
115         @param pElement an array of elements
116         @param len length of array
117     */
118     inline Sequence( const E * pElements, sal_Int32 len );
119 
120     /** Constructor: Creates a default constructed sequence of given length.
121 
122         @param len initial sequence length
123     */
124     inline explicit Sequence( sal_Int32 len );
125 
126     /** Destructor: Releases sequence handle. Last handle will destruct
127         elements and free memory.
128     */
129     inline ~Sequence() SAL_THROW( () );
130 
131     /** Assignment operator: Acquires given sequence handle and releases
132         previously set handle.
133 
134         @param rSeq another sequence of same type
135         @return this sequence
136     */
137     inline Sequence< E > & SAL_CALL operator = ( const Sequence< E > & rSeq )
138         SAL_THROW( () );
139 
140     /** Gets length of the sequence.
141 
142         @return length of sequence
143     */
getLength() const144     inline sal_Int32 SAL_CALL getLength() const SAL_THROW( () )
145         { return _pSequence->nElements; }
146 
147     /** Tests whether the sequence has elements, i.e. elements count is
148         greater than zero.
149 
150         @return true, if elements count is greater than zero
151     */
hasElements() const152     inline sal_Bool SAL_CALL hasElements() const SAL_THROW( () )
153         { return (_pSequence->nElements > 0); }
154 
155     /** Gets a pointer to elements array for reading.
156         If the sequence has a length of 0, then the returned pointer is
157         undefined.
158 
159         @return pointer to elements array
160     */
getConstArray() const161     inline const E * SAL_CALL getConstArray() const SAL_THROW( () )
162         { return reinterpret_cast< const E * >( _pSequence->elements ); }
163 
164     /** Gets a pointer to elements array for reading and writing.
165         In general if the sequence has a handle acquired by other sequences
166         (reference count > 1), then a new sequence is created copy constructing
167         all elements to keep value semantics!
168         If the sequence has a length of 0, then the returned pointer is
169         undefined.
170 
171         @return pointer to elements array
172     */
173     inline E * SAL_CALL getArray();
174 
175     /** Non-const index operator: Obtains a reference to element indexed at
176         given position.
177         The implementation does not check for array bounds!
178         In general if the sequence has a handle acquired by other sequences
179         (reference count > 1), then a new sequence is created copy constructing
180         all elements to keep value semantics!
181 
182         @param nIndex index
183         @return non-const C++ reference to element
184     */
185     inline E & SAL_CALL operator [] ( sal_Int32 nIndex );
186 
187     /** Const index operator: Obtains a reference to element indexed at
188         given position.  The implementation does not check for array bounds!
189 
190         @param nIndex index
191         @return const C++ reference to element
192     */
193     inline const E & SAL_CALL operator [] ( sal_Int32 nIndex ) const
194         SAL_THROW( () );
195 
196     /** Equality operator: Compares two sequences.
197 
198         @param rSeq another sequence of same type (right side)
199         @return true if both sequences are equal, false otherwise
200     */
201     inline sal_Bool SAL_CALL operator == ( const Sequence< E > & rSeq ) const
202         SAL_THROW( () );
203 
204     /** Unequality operator: Compares two sequences.
205 
206         @param rSeq another sequence of same type (right side)
207         @return false if both sequences are equal, true otherwise
208     */
209     inline sal_Bool SAL_CALL operator != ( const Sequence< E > & rSeq ) const
210         SAL_THROW( () );
211 
212     /** Reallocates sequence to new length.
213         If the new length is smaller than the former, then upper elements will
214         be destructed (and their memory freed).  If the new length is greater
215         than the former, then upper (new) elements are default constructed.
216         If the sequence has a handle acquired by other sequences
217         (reference count > 1), then the remaining elements are copy constructed
218         to a new sequence handle to keep value semantics!
219 
220         @param nSize new size of sequence
221     */
222     inline void SAL_CALL realloc( sal_Int32 nSize );
223 
224     /** Provides UNacquired sequence handle.
225 
226         @return UNacquired sequence handle
227     */
get() const228     inline uno_Sequence * SAL_CALL get() const SAL_THROW( () )
229         { return _pSequence; }
230 };
231 
232 /** Creates a UNO byte sequence from a SAL byte sequence.
233 
234     @param rByteSequence a byte sequence
235     @return a UNO byte sequence
236 */
237 inline ::com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL toUnoSequence(
238     const ::rtl::ByteSequence & rByteSequence ) SAL_THROW( () );
239 
240 }
241 }
242 }
243 }
244 
245 /** Gets the meta type of IDL sequence.
246 
247     There are cases (involving templates) where uses of getCppuType are known to
248     not compile.  Use cppu::UnoType or cppu::getTypeFavourUnsigned instead.
249 
250     @tplparam E element type of sequence
251     @param dummy typed pointer for function signature
252     @return type of IDL sequence
253 */
254 template< class E >
255 inline const ::com::sun::star::uno::Type &
256 SAL_CALL getCppuType( const ::com::sun::star::uno::Sequence< E > * )
257     SAL_THROW( () );
258 
259 /** Gets the meta type of IDL sequence.
260     This function has been introduced, because one cannot get the (templated)
261     cppu type out of C++ array types.  Array types have special
262     getCppuArrayTypeN() functions.
263 
264     @attention
265     the given element type must be the same as the template argument type!
266     @tplparam E element type of sequence
267     @param rElementType element type of sequence
268     @return type of IDL sequence
269 */
270 template< class E >
271 inline const ::com::sun::star::uno::Type &
272 SAL_CALL getCppuSequenceType( const ::com::sun::star::uno::Type & rElementType )
273     SAL_THROW( () );
274 
275 /** Gets the meta type of IDL sequence< char >.
276     This function has been introduced due to ambiguities with unsigned short.
277 
278     @param dummy typed pointer for function signature
279     @return type of IDL sequence< char >
280 */
281 inline const ::com::sun::star::uno::Type &
282 SAL_CALL getCharSequenceCppuType() SAL_THROW( () );
283 
284 #endif
285