include/comphelper/namedvaluecollection.hxx

   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 #ifndef INCLUDED_COMPHELPER_NAMEDVALUECOLLECTION_HXX
  21 #define INCLUDED_COMPHELPER_NAMEDVALUECOLLECTION_HXX
  22
  23 #include <comphelper/comphelperdllapi.h>
  24
  25 #include <com/sun/star/uno/Sequence.hxx>
  26 #include <com/sun/star/uno/Any.hxx>
  27 #include <com/sun/star/beans/PropertyValue.hpp>
  28 #include <com/sun/star/beans/NamedValue.hpp>
  29
  30 #include <memory>
  31 #include <algorithm>
  32 #include <vector>
  33
  34 //........................................................................
  35 namespace comphelper
  36 {
  37 //........................................................................
  38
  39     // ====================================================================
  40     // = NamedValueCollection
  41     // ====================================================================
  42     struct NamedValueCollection_Impl;
  43     /** a collection of named values, packed in various formats.
  44     */
  45     class COMPHELPER_DLLPUBLIC NamedValueCollection
  46     {
  47     private:
  48         ::std::auto_ptr< NamedValueCollection_Impl >    m_pImpl;
  49
  50     public:
  51         NamedValueCollection();
  52
  53         NamedValueCollection( const NamedValueCollection& _rCopySource );
  54
  55         NamedValueCollection& operator=( const NamedValueCollection& i_rCopySource );
  56
  57         /** constructs a collection
  58             @param  _rElements
  59                 the wrapped elements of the collection. The <code>Any</code> might contain a sequence of
  60                 property values, a sequence of named values, or directly a property value or named value.
  61                 All other cases are worth an assertion in non-product builds.
  62         */
  63         NamedValueCollection( const ::com::sun::star::uno::Any& _rElements );
  64
  65         /** constructs a collection
  66             @param _rArguments
  67                 a sequence of Any's containing either PropertyValue's or NamedValue's.
  68         */
  69         NamedValueCollection( const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments );
  70
  71         /** constructs a collection
  72             @param _rArguments
  73                 a sequence of PropertyValues's
  74         */
  75         NamedValueCollection( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& _rArguments );
  76
  77         /** constructs a collection
  78             @param _rArguments
  79                 a sequence of NamedValue's
  80         */
  81         NamedValueCollection( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& _rArguments );
  82
  83         ~NamedValueCollection();
  84
  85         inline void assign( const ::com::sun::star::uno::Any& i_rWrappedElements )
  86         {
  87             impl_assign( i_rWrappedElements );
  88         }
  89
  90         inline void assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments )
  91         {
  92             impl_assign( _rArguments );
  93         }
  94
  95         inline void assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& _rArguments )
  96         {
  97             impl_assign( _rArguments );
  98         }
  99
 100         inline void assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& _rArguments )
 101         {
 102             impl_assign( _rArguments );
 103         }
 104
 105         inline void clear()
 106         {
 107             impl_assign( ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >() );
 108         }
 109
 110         /** determines whether or not named values can be extracted from the given value
 111
 112             @return
 113                 <TRUE/> if and only if the given <code>Any</code> contains a <code>NamedValue</code>, a
 114                 <code>PropertyValue</code>, or a sequence thereof.
 115         */
 116         static bool canExtractFrom( ::com::sun::star::uno::Any const & i_value );
 117
 118         /// returns the number of elements in the collection
 119         size_t  size() const;
 120
 121         /// determines whether the collection is empty
 122         bool    empty() const;
 123
 124         /** returns the names of all elements in the collection
 125         */
 126         ::std::vector< OUString >
 127                 getNames() const;
 128
 129         /** merges the content of another collection into |this|
 130             @param _rAdditionalValues
 131                 the collection whose values are to be merged
 132             @param _bOverwriteExisting
 133                 defines whether or not elements which are already present in |this|
 134                 should be overwritten (<TRUE/>) or preserved (<FALSE/>).
 135             @return |*this|
 136         */
 137         NamedValueCollection&
 138                 merge(
 139                     const NamedValueCollection& _rAdditionalValues,
 140                     bool _bOverwriteExisting
 141                 );
 142
 143         /** retrieves a value with a given name from the collection, if it is present
 144
 145             @param _pAsciiValueName
 146                 the ASCII name of the value to retrieve
 147
 148             @param _out_rValue
 149                 is the output parameter taking the desired value upon successful return. If
 150                 a value with the given name is not present in the collection, or if a wrong-typed
 151                 value is present, then this parameter will not be touched.
 152
 153             @return
 154                 <TRUE/> if there is a value with the given name, which could successfully
 155                 be extraced. In this case, <arg>_out_rValue</arg> will contain the requested
 156                 value.<br/>
 157                 <FALSE/>, if there is no value with the given name.
 158             @throws IllegalArgumentException
 159                 in case there is a value with the given name, but it cannot legally assigned to
 160                 _out_rValue.
 161         */
 162         template < typename VALUE_TYPE >
 163         bool get_ensureType( const sal_Char* _pAsciiValueName, VALUE_TYPE& _out_rValue ) const
 164         {
 165             return get_ensureType( OUString::createFromAscii( _pAsciiValueName ), &_out_rValue, ::cppu::UnoType< VALUE_TYPE >::get() );
 166         }
 167
 168         template < typename VALUE_TYPE >
 169         bool    get_ensureType( const OUString& _rValueName, VALUE_TYPE& _out_rValue ) const
 170         {
 171             return get_ensureType( _rValueName, &_out_rValue, ::cppu::UnoType< VALUE_TYPE >::get() );
 172         }
 173
 174         /** retrieves a value with a given name, or defaults it to a given value, if its not present
 175             in the colllection
 176         */
 177         template < typename VALUE_TYPE >
 178         VALUE_TYPE  getOrDefault( const sal_Char* _pAsciiValueName, const VALUE_TYPE& _rDefault ) const
 179         {
 180             return getOrDefault( OUString::createFromAscii( _pAsciiValueName ), _rDefault );
 181         }
 182
 183         template < typename VALUE_TYPE >
 184         VALUE_TYPE  getOrDefault( const OUString& _rValueName, const VALUE_TYPE& _rDefault ) const
 185         {
 186             VALUE_TYPE retVal( _rDefault );
 187             get_ensureType( _rValueName, retVal );
 188             return retVal;
 189         }
 190
 191         /** retrieves a (untyped) value with a given name
 192
 193             If the collection does not contain a value with the given name, an empty
 194             Any is returned.
 195         */
 196         const ::com::sun::star::uno::Any& get( const sal_Char* _pAsciiValueName ) const
 197         {
 198             return get( OUString::createFromAscii( _pAsciiValueName ) );
 199         }
 200
 201         /** retrieves a (untyped) value with a given name
 202
 203             If the collection does not contain a value with the given name, an empty
 204             Any is returned.
 205         */
 206         const ::com::sun::star::uno::Any& get( const OUString& _rValueName ) const
 207         {
 208             return impl_get( _rValueName );
 209         }
 210
 211         /// determines whether a value with a given name is present in the collection
 212         inline bool has( const sal_Char* _pAsciiValueName ) const
 213         {
 214             return impl_has( OUString::createFromAscii( _pAsciiValueName ) );
 215         }
 216
 217         /// determines whether a value with a given name is present in the collection
 218         inline bool has( const OUString& _rValueName ) const
 219         {
 220             return impl_has( _rValueName );
 221         }
 222
 223         /** puts a value into the collection
 224
 225             @return <TRUE/> if and only if a value was already present previously, in
 226                 which case it has been overwritten.
 227         */
 228         template < typename VALUE_TYPE >
 229         inline bool put( const sal_Char* _pAsciiValueName, const VALUE_TYPE& _rValue )
 230         {
 231             return impl_put( OUString::createFromAscii( _pAsciiValueName ), ::com::sun::star::uno::makeAny( _rValue ) );
 232         }
 233
 234         /** puts a value into the collection
 235
 236             @return <TRUE/> if and only if a value was already present previously, in
 237                 which case it has been overwritten.
 238         */
 239         template < typename VALUE_TYPE >
 240         inline bool put( const OUString& _rValueName, const VALUE_TYPE& _rValue )
 241         {
 242             return impl_put( _rValueName, ::com::sun::star::uno::makeAny( _rValue ) );
 243         }
 244
 245         inline bool put( const sal_Char* _pAsciiValueName, const ::com::sun::star::uno::Any& _rValue )
 246         {
 247             return impl_put( OUString::createFromAscii( _pAsciiValueName ), _rValue );
 248         }
 249
 250         inline bool put( const OUString& _rValueName, const ::com::sun::star::uno::Any& _rValue )
 251         {
 252             return impl_put( _rValueName, _rValue );
 253         }
 254
 255         /** removes the value with the given name from the collection
 256
 257             @return <TRUE/> if and only if a value with the given name existed in the collection.
 258         */
 259         inline bool remove( const sal_Char* _pAsciiValueName )
 260         {
 261             return impl_remove( OUString::createFromAscii( _pAsciiValueName ) );
 262         }
 263
 264         /** removes the value with the given name from the collection
 265
 266             @return <TRUE/> if and only if a value with the given name existed in the collection.
 267         */
 268         inline bool remove( const OUString& _rValueName )
 269         {
 270             return impl_remove( _rValueName );
 271         }
 272
 273         /** transforms the collection to a sequence of PropertyValues
 274
 275             @return
 276                 the  number of elements in the sequence
 277         */
 278         sal_Int32 operator >>= ( ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& _out_rValues ) const;
 279
 280         /** transforms the collection to a sequence of NamedValues
 281
 282             @return
 283                 the  number of elements in the sequence
 284         */
 285         sal_Int32 operator >>= ( ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& _out_rValues ) const;
 286
 287         /** transforms the collection into a sequence of PropertyValues
 288         */
 289         inline ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >
 290                 getPropertyValues() const
 291         {
 292             ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > aValues;
 293             *this >>= aValues;
 294             return aValues;
 295         }
 296
 297         /** returns a Sequence< Any >, containing PropertyValues
 298         */
 299         inline ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >
 300                 getWrappedPropertyValues() const
 301         {
 302             return impl_wrap< ::com::sun::star::beans::PropertyValue >();
 303         }
 304
 305         /** returns a Sequence< Any >, containing NamedValues
 306         */
 307         inline ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >
 308                 getWrappedNamedValues() const
 309         {
 310             return impl_wrap< ::com::sun::star::beans::NamedValue >();
 311         }
 312
 313         /** transforms the collection into a sequence of NamedValues
 314         */
 315         inline ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >
 316                 getNamedValues() const
 317         {
 318             ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue > aValues;
 319             *this >>= aValues;
 320             return aValues;
 321         }
 322
 323     private:
 324         void    impl_assign( const ::com::sun::star::uno::Any& i_rWrappedElements );
 325         void    impl_assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& _rArguments );
 326         void    impl_assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& _rArguments );
 327         void    impl_assign( const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& _rArguments );
 328
 329         bool    get_ensureType(
 330                     const OUString& _rValueName,
 331                     void* _pValueLocation,
 332                     const ::com::sun::star::uno::Type& _rExpectedValueType
 333                 ) const;
 334
 335         const ::com::sun::star::uno::Any&
 336                 impl_get( const OUString& _rValueName ) const;
 337
 338         bool    impl_has( const OUString& _rValueName ) const;
 339
 340         bool    impl_put( const OUString& _rValueName, const ::com::sun::star::uno::Any& _rValue );
 341
 342         bool    impl_remove( const OUString& _rValueName );
 343
 344         template< class VALUE_TYPE >
 345         ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > impl_wrap() const
 346         {
 347             ::com::sun::star::uno::Sequence< VALUE_TYPE > aValues;
 348             *this >>= aValues;
 349             ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > aWrappedValues( aValues.getLength() );
 350
 351             ::com::sun::star::uno::Any* pO = aWrappedValues.getArray();
 352             const VALUE_TYPE* pV = aValues.getConstArray();
 353             const sal_Int32 nLen = aValues.getLength();
 354             for( sal_Int32 i = 0; i < nLen; ++i )
 355                 *(pO++) = ::com::sun::star::uno::makeAny<VALUE_TYPE>( *(pV++) );
 356
 357             return aWrappedValues;
 358         }
 359     };
 360
 361 //........................................................................
 362 } // namespace comphelper
 363 //........................................................................
 364
 365 #endif // INCLUDED_COMPHELPER_NAMEDVALUECOLLECTION_HXX
 366
 367 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */