include/com/sun/star/uno/Sequence.h

   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     static void * SAL_CALL operator new ( ::size_t nSize )
  66         { return ::rtl_allocateMemory( nSize ); }
  67     static void SAL_CALL operator delete ( void * pMem )
  68         { ::rtl_freeMemory( pMem ); }
  69     static void * SAL_CALL operator new ( ::size_t, void * pMem )
  70         { return pMem; }
  71     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 & 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 & SAL_CALL operator = ( const Sequence & rSeq );
 138
 139     /** Gets length of the sequence.
 140
 141         @return length of sequence
 142     */
 143     sal_Int32 SAL_CALL getLength() const
 144         { 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     bool SAL_CALL hasElements() const
 152         { 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     const E * SAL_CALL getConstArray() const
 161         { 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 & 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 & 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     uno_Sequence * SAL_CALL get() const
 253         { 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: */