Line data Source code
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 : #if defined LIBO_INTERNAL_ONLY
30 : #include <initializer_list>
31 : #endif
32 :
33 : namespace rtl
34 : {
35 : class ByteSequence;
36 : }
37 :
38 : namespace com
39 : {
40 : namespace sun
41 : {
42 : namespace star
43 : {
44 : namespace uno
45 : {
46 :
47 : /** Template C++ class representing an IDL sequence. Template argument is the
48 : sequence element type. C++ Sequences are reference counted and shared,
49 : so the sequence keeps a handle to its data. To keep value semantics,
50 : copies are only generated if the sequence is to be modified (new handle).
51 :
52 : @tparam E element type of sequence
53 : */
54 : template< class E >
55 : class SAL_WARN_UNUSED SAL_DLLPUBLIC_RTTI Sequence
56 : {
57 : /** sequence handle
58 : */
59 : uno_Sequence * _pSequence;
60 :
61 : public:
62 : /// @cond INTERNAL
63 :
64 : // these are here to force memory de/allocation to sal lib.
65 1817756 : inline static void * SAL_CALL operator new ( ::size_t nSize )
66 1817756 : { return ::rtl_allocateMemory( nSize ); }
67 1812927 : inline static void SAL_CALL operator delete ( void * pMem )
68 1812927 : { ::rtl_freeMemory( pMem ); }
69 : inline static void * SAL_CALL operator new ( ::size_t, void * pMem )
70 : { return pMem; }
71 : inline static void SAL_CALL operator delete ( void *, void * )
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();
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 );
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 :
103 : /** Constructor: Creates a copy of given elements.
104 :
105 : @param pElements an array of elements
106 : @param len length of array
107 : */
108 : inline Sequence( const E * pElements, sal_Int32 len );
109 :
110 : /** Constructor: Creates a default constructed sequence of given length.
111 :
112 : @param len initial sequence length
113 : */
114 : inline explicit Sequence( sal_Int32 len );
115 :
116 : #if defined LIBO_INTERNAL_ONLY
117 : /** Create a sequence with the given elements.
118 :
119 : @param init an initializer_list
120 :
121 : @since LibreOffice 5.0
122 : */
123 : inline Sequence(std::initializer_list<E> init);
124 : #endif
125 :
126 : /** Destructor: Releases sequence handle. Last handle will destruct
127 : elements and free memory.
128 : */
129 : inline ~Sequence();
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 :
139 : /** Gets length of the sequence.
140 :
141 : @return length of sequence
142 : */
143 1104094139 : inline sal_Int32 SAL_CALL getLength() const
144 1104094139 : { return _pSequence->nElements; }
145 :
146 : /** Tests whether the sequence has elements, i.e. elements count is
147 : greater than zero.
148 :
149 : @return true, if elements count is greater than zero
150 : */
151 5003221 : inline bool SAL_CALL hasElements() const
152 5003221 : { return (_pSequence->nElements > 0); }
153 :
154 : /** Gets a pointer to elements array for reading.
155 : If the sequence has a length of 0, then the returned pointer is
156 : undefined.
157 :
158 : @return pointer to elements array
159 : */
160 1035743874 : inline const E * SAL_CALL getConstArray() const
161 1035743874 : { return reinterpret_cast< const E * >( _pSequence->elements ); }
162 :
163 : /** Gets a pointer to elements array for reading and writing.
164 : In general if the sequence has a handle acquired by other sequences
165 : (reference count > 1), then a new sequence is created copy constructing
166 : all elements to keep value semantics!
167 : If the sequence has a length of 0, then the returned pointer is
168 : undefined.
169 :
170 : @return pointer to elements array
171 : */
172 : inline E * SAL_CALL getArray();
173 :
174 : /** This function allows to use Sequence in standard algorightms, like std::find
175 : and others.
176 :
177 : @since LibreOffice 4.2
178 : */
179 : inline E * begin();
180 :
181 : /** This function allows to use Sequence in standard algorightms, like std::find
182 : and others.
183 :
184 : @since LibreOffice 4.2
185 : */
186 : inline E const * begin() const;
187 :
188 : /** This function allows to use Sequence in standard algorightms, like std::find
189 : and others.
190 :
191 : @since LibreOffice 4.2
192 : */
193 : inline E * end();
194 :
195 : /** This function allows to use Sequence in standard algorightms, like std::find
196 : and others.
197 :
198 : @since LibreOffice 4.2
199 : */
200 : inline E const * end() const;
201 :
202 : /** Non-const index operator: Obtains a reference to element indexed at
203 : given position.
204 : The implementation does not check for array bounds!
205 : In general if the sequence has a handle acquired by other sequences
206 : (reference count > 1), then a new sequence is created copy constructing
207 : all elements to keep value semantics!
208 :
209 : @param nIndex index
210 : @return non-const C++ reference to element
211 : */
212 : inline E & SAL_CALL operator [] ( sal_Int32 nIndex );
213 :
214 : /** Const index operator: Obtains a reference to element indexed at
215 : given position. The implementation does not check for array bounds!
216 :
217 : @param nIndex index
218 : @return const C++ reference to element
219 : */
220 : inline const E & SAL_CALL operator [] ( sal_Int32 nIndex ) const;
221 :
222 : /** Equality operator: Compares two sequences.
223 :
224 : @param rSeq another sequence of same type (right side)
225 : @return true if both sequences are equal, false otherwise
226 : */
227 : inline bool SAL_CALL operator == ( const Sequence< E > & rSeq ) const;
228 :
229 : /** Unequality operator: Compares two sequences.
230 :
231 : @param rSeq another sequence of same type (right side)
232 : @return false if both sequences are equal, true otherwise
233 : */
234 : inline bool SAL_CALL operator != ( const Sequence< E > & rSeq ) const;
235 :
236 : /** Reallocates sequence to new length.
237 : If the new length is smaller than the former, then upper elements will
238 : be destructed (and their memory freed). If the new length is greater
239 : than the former, then upper (new) elements are default constructed.
240 : If the sequence has a handle acquired by other sequences
241 : (reference count > 1), then the remaining elements are copy constructed
242 : to a new sequence handle to keep value semantics!
243 :
244 : @param nSize new size of sequence
245 : */
246 : inline void SAL_CALL realloc( sal_Int32 nSize );
247 :
248 : /** Provides UNacquired sequence handle.
249 :
250 : @return UNacquired sequence handle
251 : */
252 4671 : inline uno_Sequence * SAL_CALL get() const
253 4671 : { return _pSequence; }
254 : };
255 :
256 : // Find uses of illegal Sequence<bool> (instead of Sequence<sal_Bool>) during
257 : // compilation:
258 : template<> class Sequence<bool> {
259 : Sequence(Sequence<bool> const &) SAL_DELETED_FUNCTION;
260 : };
261 :
262 : /** Creates a UNO byte sequence from a SAL byte sequence.
263 :
264 : @param rByteSequence a byte sequence
265 : @return a UNO byte sequence
266 : */
267 : inline ::com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL toUnoSequence(
268 : const ::rtl::ByteSequence & rByteSequence );
269 :
270 : }
271 : }
272 : }
273 : }
274 :
275 : /** Gets the meta type of IDL sequence.
276 :
277 : There are cases (involving templates) where uses of getCppuType are known to
278 : not compile. Use cppu::UnoType or cppu::getTypeFavourUnsigned instead.
279 :
280 : The dummy parameter is just a typed pointer for function signature.
281 :
282 : @tparam E element type of sequence
283 : @return type of IDL sequence
284 :
285 : @deprecated
286 : Use cppu::UnoType instead.
287 : */
288 : template< class E > SAL_DEPRECATED("use cppu::UnoType")
289 : inline const ::com::sun::star::uno::Type &
290 : SAL_CALL getCppuType( const ::com::sun::star::uno::Sequence< E > * );
291 :
292 : /** Gets the meta type of IDL sequence.
293 : This function has been introduced, because one cannot get the (templated)
294 : cppu type out of C++ array types.
295 :
296 : @attention
297 : the given element type must be the same as the template argument type!
298 : @tparam E element type of sequence
299 : @param rElementType element type of sequence
300 : @return type of IDL sequence
301 :
302 : @deprecated
303 : Use cppu::UnoType instead.
304 : */
305 : template< class E > SAL_DEPRECATED("use cppu::UnoType")
306 : inline const ::com::sun::star::uno::Type &
307 : SAL_CALL getCppuSequenceType( const ::com::sun::star::uno::Type & rElementType );
308 :
309 : /** Gets the meta type of IDL sequence< char >.
310 : This function has been introduced due to ambiguities with unsigned short.
311 :
312 : The dummy parameter is just a typed pointer for function signature.
313 :
314 : @return type of IDL sequence< char >
315 :
316 : @deprecated
317 : Use cppu::UnoType instead.
318 : */
319 : SAL_DEPRECATED("use cppu::UnoType")
320 : inline const ::com::sun::star::uno::Type &
321 : SAL_CALL getCharSequenceCppuType();
322 :
323 : #endif
324 :
325 : /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|
