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