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