include/com/sun/star/uno/Any.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_ANY_H
  24 #define INCLUDED_COM_SUN_STAR_UNO_ANY_H
  25
  26 #include "sal/config.h"
  27
  28 #include <cstddef>
  29
  30 #include "rtl/ustring.hxx"
  31 #include "uno/any2.h"
  32 #include "typelib/typedescription.h"
  33 #include "cppu/unotype.hxx"
  34 #include "com/sun/star/uno/TypeClass.hdl"
  35 #include "rtl/alloc.h"
  36
  37 namespace com
  38 {
  39 namespace sun
  40 {
  41 namespace star
  42 {
  43 namespace uno
  44 {
  45
  46 class Type;
  47 template<class interface_type> class Reference;
  48
  49 /** C++ class representing an IDL any.
  50     This class is used to transport any type defined in IDL. The class inherits from the
  51     binary C representation of uno_Any.
  52     You can insert a value by using the <<= operators.
  53     No any can hold an any. You can extract values from an any by using the >>= operators which
  54     return true if the any contains an assignable value (no data loss), e.g. the any contains a
  55     short and you >>= it into a long variable.
  56 */
  57 class SAL_WARN_UNUSED SAL_DLLPUBLIC_RTTI Any : public uno_Any
  58 {
  59 public:
  60     /// @cond INTERNAL
  61     // these are here to force memory de/allocation to sal lib.
  62     static void * SAL_CALL operator new ( size_t nSize )
  63         { return ::rtl_allocateMemory( nSize ); }
  64     static void SAL_CALL operator delete ( void * pMem )
  65         { ::rtl_freeMemory( pMem ); }
  66     static void * SAL_CALL operator new ( size_t, void * pMem )
  67         { return pMem; }
  68     static void SAL_CALL operator delete ( void *, void * )
  69         {}
  70     /// @endcond
  71
  72     /** Default constructor: Any holds no value; its type is void.
  73     */
  74     inline Any();
  75
  76     /** Templated ctor.  Sets a copy of the given value.
  77
  78         @param value value of the Any
  79     */
  80     template <typename T>
  81     explicit inline Any( T const & value );
  82     /// Ctor support for C++ bool.
  83     explicit inline Any( bool value );
  84
  85 #if defined LIBO_INTERNAL_ONLY
  86     template<typename T1, typename T2>
  87     explicit inline Any(rtl::OUStringConcat<T1, T2> && value);
  88     template<typename T1, typename T2>
  89     explicit Any(rtl::OUStringConcat<T1, T2> const &) = delete;
  90     template<std::size_t nBufSize> explicit inline Any(rtl::StringNumber<sal_Unicode, nBufSize> && value);
  91     template<std::size_t nBufSize> explicit Any(rtl::StringNumber<sal_Unicode, nBufSize> const &) = delete;
  92     template <std::size_t N> explicit inline Any(const rtl::OUStringLiteral<N>& value);
  93 #endif
  94
  95     /** Copy constructor: Sets value of the given any.
  96
  97         @param rAny another any
  98     */
  99     inline Any( const Any & rAny );
 100
 101     /** Constructor: Sets a copy of the given data.
 102
 103         @param pData_ value
 104         @param rType type of value
 105     */
 106     inline Any( const void * pData_, const Type & rType );
 107
 108     /** Constructor: Sets a copy of the given data.
 109
 110         @param pData_ value
 111         @param pTypeDescr type of value
 112     */
 113     inline Any( const void * pData_, typelib_TypeDescription * pTypeDescr );
 114
 115     /** Constructor: Sets a copy of the given data.
 116
 117         @param pData_ value
 118         @param pType_ type of value
 119     */
 120     inline Any( const void * pData_, typelib_TypeDescriptionReference * pType_ );
 121
 122 #if defined LIBO_INTERNAL_ONLY
 123     Any(bool const *, Type const &) = delete;
 124     Any(bool const *, typelib_TypeDescription *) = delete;
 125     Any(bool const *, typelib_TypeDescriptionReference *) = delete;
 126     Any(sal_Bool const *, Type const &) = delete;
 127     Any(sal_Bool const *, typelib_TypeDescription *) = delete;
 128     Any(sal_Bool const *, typelib_TypeDescriptionReference *) = delete;
 129     Any(std::nullptr_t, Type const & type):
 130         Any(static_cast<void *>(nullptr), type) {}
 131     Any(std::nullptr_t, typelib_TypeDescription * type):
 132         Any(static_cast<void *>(nullptr), type) {}
 133     Any(std::nullptr_t, typelib_TypeDescriptionReference * type):
 134         Any(static_cast<void *>(nullptr), type) {}
 135 #endif
 136
 137     /** Destructor: Destructs any content and frees memory.
 138     */
 139     inline ~Any();
 140
 141     /** Assignment operator: Sets the value of the given any.
 142
 143         @param rAny another any (right side)
 144         @return this any
 145     */
 146     inline Any & SAL_CALL operator = ( const Any & rAny );
 147
 148 #if defined LIBO_INTERNAL_ONLY
 149 #if !defined(__COVERITY__) // suppress COPY_INSTEAD_OF_MOVE suggestions
 150     inline Any(Any && other) noexcept;
 151 #endif
 152     inline Any & operator =(Any && other) noexcept;
 153 #endif
 154
 155     /** Gets the type of the set value.
 156
 157         @return a Type object of the set value
 158      */
 159     const Type & SAL_CALL getValueType() const
 160         { return * reinterpret_cast< const Type * >( &pType ); }
 161     /** Gets the type of the set value.
 162
 163         @return the unacquired type description reference of the set value
 164      */
 165     typelib_TypeDescriptionReference * SAL_CALL getValueTypeRef() const
 166         { return pType; }
 167
 168     /** Gets the type description of the set value. Provides ownership of the type description!
 169         Call an explicit typelib_typedescription_release() to release afterwards.
 170
 171         @param ppTypeDescr a pointer to type description pointer
 172     */
 173     void SAL_CALL getValueTypeDescription( typelib_TypeDescription ** ppTypeDescr ) const
 174         { ::typelib_typedescriptionreference_getDescription( ppTypeDescr, pType ); }
 175
 176     /** Gets the type class of the set value.
 177
 178         @return the type class of the set value
 179      */
 180     TypeClass SAL_CALL getValueTypeClass() const
 181         { return static_cast<TypeClass>(pType->eTypeClass); }
 182
 183     /** Gets the type name of the set value.
 184
 185         @return the type name of the set value
 186     */
 187     inline ::rtl::OUString SAL_CALL getValueTypeName() const;
 188
 189     /** Tests if any contains a value.
 190
 191         @return true if any has a value, false otherwise
 192     */
 193     bool SAL_CALL hasValue() const
 194         { return (typelib_TypeClass_VOID != pType->eTypeClass); }
 195
 196     /** Gets a pointer to the set value.
 197
 198         @return a pointer to the set value
 199     */
 200     const void * SAL_CALL getValue() const
 201         { return pData; }
 202
 203     /** Provides a value of specified type, so you can easily write e.g.
 204         <pre>
 205         sal_Int32 myVal = myAny.get<sal_Int32>();
 206         </pre>
 207         Widening conversion without data loss is taken into account.
 208         Throws a com::sun::star::uno::RuntimeException if the specified type
 209         cannot be provided.
 210
 211         @return value of specified type
 212         @exception com::sun::star::uno::RuntimeException
 213                    in case the specified type cannot be provided
 214     */
 215     template <typename T>
 216     inline T get() const;
 217
 218     /** Sets a value. If the any already contains a value, that value will be destructed
 219         and its memory freed.
 220
 221         @param pData_ pointer to value
 222         @param rType type of value
 223     */
 224     inline void SAL_CALL setValue( const void * pData_, const Type & rType );
 225     /** Sets a value. If the any already contains a value, that value will be destructed
 226         and its memory freed.
 227
 228         @param pData_ pointer to value
 229         @param pType_ type of value
 230     */
 231     inline void SAL_CALL setValue( const void * pData_, typelib_TypeDescriptionReference * pType_ );
 232     /** Sets a value. If the any already contains a value, that value will be destructed
 233         and its memory freed.
 234
 235         @param pData_ pointer to value
 236         @param pTypeDescr type description of value
 237     */
 238     inline void SAL_CALL setValue( const void * pData_, typelib_TypeDescription * pTypeDescr );
 239
 240 #if defined LIBO_INTERNAL_ONLY
 241     void setValue(bool const *, Type const &) = delete;
 242     void setValue(bool const *, typelib_TypeDescriptionReference *) = delete;
 243     void setValue(bool const *, typelib_TypeDescription *) = delete;
 244     void setValue(sal_Bool const *, Type const &) = delete;
 245     void setValue(sal_Bool const *, typelib_TypeDescriptionReference *)
 246         = delete;
 247     void setValue(sal_Bool const *, typelib_TypeDescription *) = delete;
 248     void setValue(std::nullptr_t, Type const & type)
 249     { setValue(static_cast<void *>(nullptr), type); }
 250     void setValue(std::nullptr_t, typelib_TypeDescriptionReference * type)
 251     { setValue(static_cast<void *>(nullptr), type); }
 252     void setValue(std::nullptr_t, typelib_TypeDescription * type)
 253     { setValue(static_cast<void *>(nullptr), type); }
 254 #endif
 255
 256     /** Clears this any. If the any already contains a value, that value will be destructed
 257         and its memory freed. After this has been called, the any does not contain a value.
 258     */
 259     inline void SAL_CALL clear();
 260
 261     /** Tests whether this any is extractable to a value of given type.
 262         Widening conversion without data loss is taken into account.
 263
 264         @param rType destination type
 265         @return true if this any is extractable to value of given type (e.g. using >>= operator)
 266     */
 267     inline bool SAL_CALL isExtractableTo( const Type & rType ) const;
 268
 269     /** Tests whether this any can provide a value of specified type.
 270         Widening conversion without data loss is taken into account.
 271
 272         @return true if this any can provide a value of specified type
 273         (e.g. using >>= operator)
 274     */
 275     template <typename T>
 276     inline bool has() const;
 277
 278     /** Equality operator: compares two anys.
 279         The values need not be of equal type, e.g. a short integer is compared to a long integer.
 280
 281         @param rAny another any (right side)
 282         @return true if both any contains equal values
 283     */
 284     inline bool SAL_CALL operator == ( const Any & rAny ) const;
 285     /** Inequality operator: compares two anys.
 286         The values need not be of equal type, e.g. a short integer is compared to a long integer.
 287
 288         @param rAny another any (right side)
 289         @return true if both any contains unequal values
 290     */
 291     inline bool SAL_CALL operator != ( const Any & rAny ) const;
 292
 293 #if defined LIBO_INTERNAL_ONLY
 294     // Similar to Reference::query/queryThrow, these allow to simplify calling constructors of
 295     // Reference taking Any. queryThrow is functionally similar to get(), but doesn't require
 296     // to specify the full Reference type explicitly, only the interface type.
 297     template<class interface_type> inline Reference<interface_type> query() const;
 298     template<class interface_type> inline Reference<interface_type> queryThrow() const;
 299 #endif
 300
 301 private:
 302 #if !defined LIBO_INTERNAL_ONLY
 303     /// @cond INTERNAL
 304     // Forbid use with ambiguous type (sal_Unicode, sal_uInt16):
 305     explicit Any(sal_uInt16) SAL_DELETED_FUNCTION;
 306     /// @endcond
 307 #endif
 308 };
 309
 310 #if !defined LIBO_INTERNAL_ONLY
 311 /// @cond INTERNAL
 312 // Forbid use with ambiguous type (sal_Unicode, sal_uInt16):
 313 template<> sal_uInt16 Any::get<sal_uInt16>() const SAL_DELETED_FUNCTION;
 314 template<> bool Any::has<sal_uInt16>() const SAL_DELETED_FUNCTION;
 315 /// @endcond
 316 #endif
 317
 318 #if !defined LIBO_INTERNAL_ONLY
 319 /** Template function to generically construct an any from a C++ value.
 320
 321     @deprecated Just use an Any constructor with an appropriately typed argument.  (When the
 322     (UNO) type recorded in the Any instance shall be different from what would
 323     be deduced from the (C++) type of the argument, cast the argument to the appropriate type
 324     first.)
 325
 326     @tparam C value type
 327     @param value a value
 328     @return an any
 329 */
 330 template< class C >
 331 inline Any SAL_CALL makeAny( const C & value );
 332
 333 template<> inline Any SAL_CALL makeAny(sal_uInt16 const & value);
 334
 335 template<> Any SAL_CALL makeAny(Any const &) SAL_DELETED_FUNCTION;
 336 #endif
 337
 338 /** Wrap a value in an Any, if necessary.
 339
 340     (A difference to the deprecated makeAny is that makeAny cannot be called on an Any, while
 341     toAny just returns the given Any.)
 342
 343     @since LibreOffice 5.0
 344 */
 345 template<typename T> inline Any toAny(T const & value);
 346
 347 template<> inline Any toAny(Any const & value);
 348
 349 #if defined LIBO_INTERNAL_ONLY
 350
 351 /** Extract a value from an Any, if necessary.
 352
 353     The difference to operator >>= is that operator >>= cannot be called with an
 354     Any as right-hand side (in LIBO_INTERNAL_ONLY), while fromAny just passes on
 355     the given Any (and always succeeds) in the specialization for T = Any.
 356
 357     @tparam T  any type representing a UNO type
 358
 359     @param any  any Any value
 360
 361     @param value  a non-null pointer, receiving the extracted value if
 362     extraction succeeded (and left unmodified otherwise)
 363
 364     @return  true iff extraction succeeded
 365
 366     @since LibreOffice 5.3
 367 */
 368 template<typename T> inline bool fromAny(Any const & any, T * value);
 369
 370 template<> inline bool fromAny(Any const & any, Any * value);
 371
 372 #endif
 373
 374 class BaseReference;
 375
 376 /** Template binary <<= operator to set the value of an any.
 377
 378     @tparam C value type
 379     @param rAny destination any (left side)
 380     @param value source value (right side)
 381 */
 382 template< class C >
 383 inline void SAL_CALL operator <<= ( Any & rAny, const C & value );
 384
 385 // additionally for C++ bool:
 386 template<>
 387 inline void SAL_CALL operator <<= ( Any & rAny, bool const & value );
 388
 389 /** Template binary >>= operator to assign a value from an any.
 390     If the any does not contain a value that can be assigned without data loss, then this
 391     operation will fail returning false.
 392
 393     @tparam C value type
 394     @param rAny source any (left side)
 395     @param value destination value (right side)
 396     @return true if assignment was possible without data loss
 397 */
 398 template< class C >
 399 inline bool SAL_CALL operator >>= ( const Any & rAny, C & value );
 400
 401 /** Template equality operator: compares set value of left side any to right side value.
 402     The values need not be of equal type, e.g. a short integer is compared to a long integer.
 403     This operator can be implemented as template member function, if all supported compilers
 404     can cope with template member functions.
 405
 406     @tparam C value type
 407     @param rAny another any (left side)
 408     @param value a value (right side)
 409     @return true if values are equal, false otherwise
 410 */
 411 template< class C >
 412 inline bool SAL_CALL operator == ( const Any & rAny, const C & value );
 413 /** Template inequality operator: compares set value of left side any to right side value.
 414     The values need not be of equal type, e.g. a short integer is compared to a long integer.
 415     This operator can be implemented as template member function, if all supported compilers
 416     can cope with template member functions.
 417
 418     @tparam C value type
 419     @param rAny another any (left side)
 420     @param value a value (right side)
 421     @return true if values are unequal, false otherwise
 422 */
 423 template< class C >
 424 inline bool SAL_CALL operator != ( const Any & rAny, const C & value );
 425
 426 // additional specialized >>= and == operators
 427 // bool
 428 template<>
 429 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_Bool & value );
 430 template<>
 431 inline bool SAL_CALL operator == ( const Any & rAny, const sal_Bool & value );
 432 template<>
 433 inline bool SAL_CALL operator >>= ( Any const & rAny, bool & value );
 434 template<>
 435 inline bool SAL_CALL operator == ( Any const & rAny, bool const & value );
 436 // byte
 437 template<>
 438 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_Int8 & value );
 439 // short
 440 template<>
 441 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_Int16 & value );
 442 template<>
 443 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt16 & value );
 444 // long
 445 template<>
 446 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_Int32 & value );
 447 template<>
 448 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt32 & value );
 449 // hyper
 450 template<>
 451 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_Int64 & value );
 452 template<>
 453 inline bool SAL_CALL operator >>= ( const Any & rAny, sal_uInt64 & value );
 454 // float
 455 template<>
 456 inline bool SAL_CALL operator >>= ( const Any & rAny, float & value );
 457 // double
 458 template<>
 459 inline bool SAL_CALL operator >>= ( const Any & rAny, double & value );
 460 // string
 461 template<>
 462 inline bool SAL_CALL operator >>= ( const Any & rAny, ::rtl::OUString & value );
 463 template<>
 464 inline bool SAL_CALL operator == ( const Any & rAny, const ::rtl::OUString & value );
 465 #if defined LIBO_INTERNAL_ONLY
 466 template<std::size_t N>
 467 inline bool SAL_CALL operator == (const Any& rAny, const rtl::OUStringLiteral<N>& value);
 468 #endif
 469 // type
 470 template<>
 471 inline bool SAL_CALL operator >>= ( const Any & rAny, Type & value );
 472 template<>
 473 inline bool SAL_CALL operator == ( const Any & rAny, const Type & value );
 474 // any
 475 #if !defined LIBO_INTERNAL_ONLY
 476 template<>
 477 inline bool SAL_CALL operator >>= ( const Any & rAny, Any & value );
 478 #endif
 479 // interface
 480 template<>
 481 inline bool SAL_CALL operator == ( const Any & rAny, const BaseReference & value );
 482
 483 }
 484 }
 485 }
 486 }
 487
 488 /** Gets the meta type of IDL type any.
 489
 490     There are cases (involving templates) where uses of getCppuType are known to
 491     not compile.  Use cppu::UnoType or cppu::getTypeFavourUnsigned instead.
 492
 493     The dummy parameter is just a typed pointer for function signature.
 494
 495     @return type of IDL type any
 496
 497     @deprecated
 498     Use cppu::UnoType instead.
 499 */
 500 SAL_DEPRECATED("use cppu::UnoType")
 501 inline const ::com::sun::star::uno::Type & SAL_CALL getCppuType( SAL_UNUSED_PARAMETER const ::com::sun::star::uno::Any * )
 502 {
 503     return ::cppu::UnoType< ::com::sun::star::uno::Any >::get();
 504 }
 505
 506 #endif
 507
 508 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */