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
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23 #ifndef INCLUDED_COM_SUN_STAR_UNO_SEQUENCE_H
  24 #define INCLUDED_COM_SUN_STAR_UNO_SEQUENCE_H
  25
  26 #include "typelib/typedescription.h"
  27 #include "uno/sequence2.h"
  28 #include "com/sun/star/uno/Type.h"
  29 #include "rtl/alloc.h"
  30
  31 #include <new>
  32
  33 #if defined LIBO_INTERNAL_ONLY
  34 #include <cassert>
  35 #include <initializer_list>
  36 #endif
  37
  38 namespace rtl
  39 {
  40 class ByteSequence;
  41 }
  42
  43 namespace com
  44 {
  45 namespace sun
  46 {
  47 namespace star
  48 {
  49 namespace uno
  50 {
  51
  52 /** Template C++ class representing an IDL sequence. Template argument is the
  53     sequence element type.  C++ Sequences are reference counted and shared,
  54     so the sequence keeps a handle to its data.  To keep value semantics,
  55     copies are only generated if the sequence is to be modified (new handle).
  56
  57     @tparam E element type of sequence
  58 */
  59 template< class E >
  60 class SAL_WARN_UNUSED SAL_DLLPUBLIC_RTTI Sequence
  61 {
  62     /** sequence handle
  63     */
  64     uno_Sequence * _pSequence;
  65
  66 public:
  67     /// @cond INTERNAL
  68
  69     // these are here to force memory de/allocation to sal lib.
  70     static void * SAL_CALL operator new ( ::size_t nSize )
  71         { return ::rtl_allocateMemory( nSize ); }
  72     static void SAL_CALL operator delete ( void * pMem )
  73         { ::rtl_freeMemory( pMem ); }
  74     static void * SAL_CALL operator new ( ::size_t, void * pMem )
  75         { return pMem; }
  76     static void SAL_CALL operator delete ( void *, void * )
  77         {}
  78
  79     /** Static pointer to typelib type of sequence.
  80         Don't use directly, call getCppuType().
  81     */
  82     static typelib_TypeDescriptionReference * s_pType;
  83
  84     /// @endcond
  85
  86     /** typedefs the element type of the sequence
  87     */
  88     typedef E ElementType;
  89
  90     /** Default constructor: Creates an empty sequence.
  91     */
  92     inline Sequence();
  93
  94     /** Copy constructor: Creates a copy of given sequence.
  95
  96         @param rSeq another sequence of same type
  97     */
  98     inline Sequence( const Sequence & rSeq );
  99
 100     /** Constructor: Takes over ownership of given sequence.
 101
 102         @param pSequence a sequence
 103         @param dummy SAL_NO_ACQUIRE to force obvious distinction to other
 104         constructors
 105     */
 106     inline Sequence( uno_Sequence * pSequence, __sal_NoAcquire dummy );
 107
 108     /** Constructor: Creates a copy of given elements.
 109
 110         @param pElements an array of elements
 111         @param len length of array
 112     */
 113     inline Sequence( const E * pElements, sal_Int32 len );
 114
 115     /** Constructor: Creates a default constructed sequence of given length.
 116
 117         @param len initial sequence length
 118     */
 119     inline explicit Sequence( sal_Int32 len );
 120
 121 #if defined LIBO_INTERNAL_ONLY
 122     /** Create a sequence with the given elements.
 123
 124         @param init an initializer_list
 125
 126         @since LibreOffice 5.0
 127      */
 128     inline Sequence(std::initializer_list<E> init);
 129 #endif
 130
 131     /** Destructor: Releases sequence handle. Last handle will destruct
 132         elements and free memory.
 133     */
 134     inline ~Sequence();
 135
 136     /** Assignment operator: Acquires given sequence handle and releases
 137         previously set handle.
 138
 139         @param rSeq another sequence of same type
 140         @return this sequence
 141     */
 142     inline Sequence & SAL_CALL operator = ( const Sequence & rSeq );
 143
 144 #if defined LIBO_INTERNAL_ONLY
 145     inline Sequence & operator =(Sequence && other);
 146 #endif
 147
 148     /** Gets length of the sequence.
 149
 150         @return length of sequence
 151     */
 152     sal_Int32 SAL_CALL getLength() const
 153         { return _pSequence->nElements; }
 154
 155     /** Tests whether the sequence has elements, i.e. elements count is
 156         greater than zero.
 157
 158         @return true, if elements count is greater than zero
 159     */
 160     bool SAL_CALL hasElements() const
 161         { return (_pSequence->nElements > 0); }
 162
 163 #if defined LIBO_INTERNAL_ONLY
 164     /** This function allows to use Sequence in cases where  std::size is needed, and the like.
 165
 166         @since LibreOffice 6.4
 167     */
 168     sal_uInt32 size() const
 169         { assert(getLength() >= 0); return static_cast<sal_uInt32>(getLength()); }
 170 #endif
 171
 172     /** Gets a pointer to elements array for reading.
 173         If the sequence has a length of 0, then the returned pointer is
 174         undefined.
 175
 176         @return pointer to elements array
 177     */
 178     const E * SAL_CALL getConstArray() const
 179         { return reinterpret_cast< const E * >( _pSequence->elements ); }
 180
 181     /** Gets a pointer to elements array for reading and writing.
 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         If the sequence has a length of 0, then the returned pointer is
 186         undefined.
 187
 188         @return pointer to elements array
 189     */
 190     inline E * SAL_CALL getArray();
 191
 192 #if !defined LIBO_INTERNAL_ONLY
 193     /** This function allows to use Sequence in standard algorithms, like std::find
 194         and others.
 195
 196         @since LibreOffice 4.2
 197     */
 198     inline E * begin();
 199 #endif
 200
 201     /** This function allows to use Sequence in standard algorithms, like std::find
 202         and others.
 203
 204         @since LibreOffice 4.2
 205     */
 206     inline E const * begin() const;
 207
 208 #if !defined LIBO_INTERNAL_ONLY
 209     /** This function allows to use Sequence in standard algorithms, like std::find
 210         and others.
 211
 212         @since LibreOffice 4.2
 213     */
 214     inline E * end();
 215 #endif
 216
 217     /** This function allows to use Sequence in standard algorithms, like std::find
 218         and others.
 219
 220         @since LibreOffice 4.2
 221     */
 222     inline E const * end() const;
 223
 224 // Non-const operator[] is not available in internal code. Consider explicit use
 225 // of getArray(), out of tight loops if possible to avoid unneeded COW overhead.
 226 #if !defined LIBO_INTERNAL_ONLY
 227     /** Non-const index operator: Obtains a reference to element indexed at
 228         given position.
 229         The implementation does not check for array bounds!
 230         In general if the sequence has a handle acquired by other sequences
 231         (reference count > 1), then a new sequence is created copy constructing
 232         all elements to keep value semantics!
 233
 234         @param nIndex index
 235         @return non-const C++ reference to element
 236     */
 237     inline E & SAL_CALL operator [] ( sal_Int32 nIndex );
 238 #endif
 239
 240     /** Const index operator: Obtains a reference to element indexed at
 241         given position.  The implementation does not check for array bounds!
 242
 243         @param nIndex index
 244         @return const C++ reference to element
 245     */
 246     inline const E & SAL_CALL operator [] ( sal_Int32 nIndex ) const;
 247
 248     /** Equality operator: Compares two sequences.
 249
 250         @param rSeq another sequence of same type (right side)
 251         @return true if both sequences are equal, false otherwise
 252     */
 253     inline bool SAL_CALL operator == ( const Sequence & rSeq ) const;
 254
 255     /** Inequality operator: Compares two sequences.
 256
 257         @param rSeq another sequence of same type (right side)
 258         @return false if both sequences are equal, true otherwise
 259     */
 260     inline bool SAL_CALL operator != ( const Sequence & rSeq ) const;
 261
 262     /** Reallocates sequence to new length.
 263         If the new length is smaller than the former, then upper elements will
 264         be destructed (and their memory freed).  If the new length is greater
 265         than the former, then upper (new) elements are default constructed.
 266         If the sequence has a handle acquired by other sequences
 267         (reference count > 1), then the remaining elements are copy constructed
 268         to a new sequence handle to keep value semantics!
 269
 270         @param nSize new size of sequence
 271     */
 272     inline void SAL_CALL realloc( sal_Int32 nSize );
 273
 274     /** Provides UNacquired sequence handle.
 275
 276         @return UNacquired sequence handle
 277     */
 278     uno_Sequence * SAL_CALL get() const
 279         { return _pSequence; }
 280
 281 #if defined LIBO_INTERNAL_ONLY
 282     /** Swaps sequences efficiently exchanging their underlying representations.
 283
 284         @param other another sequence of same type
 285
 286         @since LibreOffice 7.3
 287     */
 288     inline void swap(Sequence& other);
 289 #endif
 290 };
 291
 292 // Find uses of illegal Sequence<bool> (instead of Sequence<sal_Bool>) during
 293 // compilation:
 294 template<> class Sequence<bool> {
 295     Sequence(Sequence<bool> const &) SAL_DELETED_FUNCTION;
 296 };
 297
 298 /** Creates a UNO byte sequence from a SAL byte sequence.
 299
 300     @param rByteSequence a byte sequence
 301     @return a UNO byte sequence
 302 */
 303 inline ::com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL toUnoSequence(
 304     const ::rtl::ByteSequence & rByteSequence );
 305
 306 }
 307 }
 308 }
 309 }
 310
 311 /** Gets the meta type of IDL sequence.
 312
 313     There are cases (involving templates) where uses of getCppuType are known to
 314     not compile.  Use cppu::UnoType or cppu::getTypeFavourUnsigned instead.
 315
 316     The dummy parameter is just a typed pointer for function signature.
 317
 318     @tparam E element type of sequence
 319     @return type of IDL sequence
 320
 321     @deprecated
 322     Use cppu::UnoType instead.
 323 */
 324 template< class E > SAL_DEPRECATED("use cppu::UnoType")
 325 inline const ::com::sun::star::uno::Type &
 326 SAL_CALL getCppuType( const ::com::sun::star::uno::Sequence< E > * );
 327
 328 /** Gets the meta type of IDL sequence.
 329     This function has been introduced, because one cannot get the (templated)
 330     cppu type out of C++ array types.
 331
 332     @attention
 333     the given element type must be the same as the template argument type!
 334     @tparam E element type of sequence
 335     @param rElementType element type of sequence
 336     @return type of IDL sequence
 337
 338     @deprecated
 339     Use cppu::UnoType instead.
 340 */
 341 template< class E > SAL_DEPRECATED("use cppu::UnoType")
 342 inline const ::com::sun::star::uno::Type &
 343 SAL_CALL getCppuSequenceType( const ::com::sun::star::uno::Type & rElementType );
 344
 345 /** Gets the meta type of IDL sequence< char >.
 346     This function has been introduced due to ambiguities with unsigned short.
 347
 348     The dummy parameter is just a typed pointer for function signature.
 349
 350     @return type of IDL sequence< char >
 351
 352     @deprecated
 353     Use cppu::UnoType instead.
 354 */
 355 SAL_DEPRECATED("use cppu::UnoType")
 356 inline const ::com::sun::star::uno::Type &
 357 SAL_CALL getCharSequenceCppuType();
 358
 359 #endif
 360
 361 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */