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