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
29namespace rtl
30{
31class ByteSequence;
32}
33
34namespace com
35{
36namespace sun
37{
38namespace star
39{
40namespace 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*/
50template< class E >
51class SAL_WARN_UNUSED Sequence
52{
53 /** sequence handle
54 */
55 uno_Sequence * _pSequence;
56
57public:
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*/
256inline ::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*/
274template< class E >
275inline const ::com::sun::star::uno::Type &
276SAL_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*/
289template< class E >
290inline const ::com::sun::star::uno::Type &
291SAL_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*/
301inline const ::com::sun::star::uno::Type &
302SAL_CALL getCharSequenceCppuType() SAL_THROW(());
303
304#endif
305
306/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
307