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