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 namespace rtl
  30 {
  31 class ByteSequence;
  32 }
  33
  34 namespace com
  35 {
  36 namespace sun
  37 {
  38 namespace star
  39 {
  40 namespace 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 */
  50 template< class E >
  51 class SAL_WARN_UNUSED Sequence
  52 {
  53     /** sequence handle
  54     */
  55     uno_Sequence * _pSequence;
  56
  57 public:
  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 sal_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 sal_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 sal_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 */
 256 inline ::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 */
 274 template< class E >
 275 inline const ::com::sun::star::uno::Type &
 276 SAL_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.  Array types have special
 282     getCppuArrayTypeN() functions.
 283
 284     @attention
 285     the given element type must be the same as the template argument type!
 286     @tparam E element type of sequence
 287     @param rElementType element type of sequence
 288     @return type of IDL sequence
 289 */
 290 template< class E >
 291 inline const ::com::sun::star::uno::Type &
 292 SAL_CALL getCppuSequenceType( const ::com::sun::star::uno::Type & rElementType )
 293     SAL_THROW(());
 294
 295 /** Gets the meta type of IDL sequence< char >.
 296     This function has been introduced due to ambiguities with unsigned short.
 297
 298     The dummy parameter is just a typed pointer for function signature.
 299
 300     @return type of IDL sequence< char >
 301 */
 302 inline const ::com::sun::star::uno::Type &
 303 SAL_CALL getCharSequenceCppuType() SAL_THROW(());
 304
 305 #endif
 306
 307 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */