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