include/comphelper/sequenceashashmap.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 _COMPHELPER_SEQUENCEASHASHMAP_HXX_
  21 #define _COMPHELPER_SEQUENCEASHASHMAP_HXX_
  22
  23 #include <boost/unordered_map.hpp>
  24
  25 #include <algorithm>
  26 #include <com/sun/star/uno/Sequence.hxx>
  27 #include <com/sun/star/beans/PropertyValue.hpp>
  28 #include <com/sun/star/beans/NamedValue.hpp>
  29
  30 #include <com/sun/star/beans/IllegalTypeException.hpp>
  31 #include "comphelper/comphelperdllapi.h"
  32
  33
  34 namespace comphelper{
  35
  36
  37 /** @short  Implements a stl hash map on top of some
  38             specialized sequence from type PropertyValue
  39             or NamedValue.
  40
  41     @descr  That provides the possibility to modify
  42             such name sequences very easy ...
  43  */
  44
  45 struct SequenceAsHashMapBase : public ::boost::unordered_map<
  46     OUString                    ,
  47     ::com::sun::star::uno::Any         ,
  48     OUStringHash                ,
  49     ::std::equal_to< OUString > >
  50 {
  51 };
  52
  53 class COMPHELPER_DLLPUBLIC SequenceAsHashMap : public SequenceAsHashMapBase
  54 {
  55     //-------------------------------------------
  56     public:
  57
  58         //---------------------------------------
  59         /** @short  creates an empty hash map.
  60          */
  61         SequenceAsHashMap();
  62
  63         //---------------------------------------
  64         /** @see    operator<<(const ::com::sun::star::uno::Any&)
  65          */
  66         SequenceAsHashMap(const ::com::sun::star::uno::Any& aSource);
  67
  68         //---------------------------------------
  69         /** @see    operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >&)
  70          */
  71         SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& lSource);
  72
  73         //---------------------------------------
  74         /** @see    operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >&)
  75          */
  76         SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lSource);
  77
  78         //---------------------------------------
  79         /** @see    operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >&)
  80          */
  81         SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lSource);
  82
  83         //---------------------------------------
  84         /** @short  not realy used but maybe useful :-)
  85          */
  86         ~SequenceAsHashMap();
  87
  88         //---------------------------------------
  89         /** @short  fill this map from the given
  90                     any, which of course must contain
  91                     a suitable sequence of element types
  92                     "css.beans.PropertyValue" or "css.beans.NamedValue".
  93
  94             @attention  If the given Any is an empty one
  95                         (if its set to VOID), no exception
  96                         is thrown. In such case this instance will
  97                         be created as an empty one too!
  98
  99             @param  aSource
 100                     contains the new items for this map.
 101
 102             @throw  An <type scope="com::sun::star::beans">IllegalTypeException</type>
 103                     is thrown, if the given any does not contain a suitable sequence ...
 104                     but not if its a VOID Any!
 105          */
 106         void operator<<(const ::com::sun::star::uno::Any& aSource);
 107
 108         //---------------------------------------
 109         /** @short  fill this map from the given
 110                     sequence, where every Any must contain
 111                     an item from type "css.beans.PropertyValue"
 112                     "css.beans.NamedValue".
 113
 114             @param  lSource
 115                     contains the new items for this map.
 116
 117             @throw  An <type scope="com::sun::star::beans">IllegalTypeException</type>
 118                     is thrown, if the given any sequence
 119                     uses wrong types for its items. VOID Any will be ignored!
 120          */
 121         void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& lSource);
 122
 123         //---------------------------------------
 124         /** @short  fill this map from the given
 125                     PropertyValue sequence.
 126
 127             @param  lSource
 128                     contains the new items for this map.
 129          */
 130         void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lSource);
 131
 132         //---------------------------------------
 133         /** @short  fill this map from the given
 134                     NamedValue sequence.
 135
 136             @param  lSource
 137                     contains the new items for this map.
 138          */
 139         void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lSource);
 140
 141         //---------------------------------------
 142         /** @short  converts this map instance to an
 143                     PropertyValue sequence.
 144
 145             @param  lDestination
 146                     target sequence for converting.
 147          */
 148         void operator>>(::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lDestination) const;
 149
 150         //---------------------------------------
 151         /** @short  converts this map instance to an
 152                     NamedValue sequence.
 153
 154             @param  lDestination
 155                     target sequence for converting.
 156          */
 157         void operator>>(::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lDestination) const;
 158
 159         //---------------------------------------
 160         /** @short  return this map instance as an
 161                     Any, which can be
 162                     used in const environments only.
 163
 164             @descr  Its made const to prevent using of the
 165                     return value directly as an in/out parameter!
 166                     usage: myMethod(stlDequeAdapter.getAsAnyList());
 167
 168             @param  bAsPropertyValue
 169                     switch between using of PropertyValue or NamedValue as
 170                     value type.
 171
 172             @return A const Any, which
 173                     contains all items of this map.
 174          */
 175         const ::com::sun::star::uno::Any getAsConstAny(::sal_Bool bAsPropertyValue) const;
 176
 177         //---------------------------------------
 178         /** @short  return this map instance to as a
 179                     NamedValue sequence, which can be
 180                     used in const environments only.
 181
 182             @descr  Its made const to prevent using of the
 183                     return value directly as an in/out parameter!
 184                     usage: myMethod(stlDequeAdapter.getAsNamedValueList());
 185
 186             @return A const sequence of type NamedValue, which
 187                     contains all items of this map.
 188          */
 189         const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue > getAsConstNamedValueList() const;
 190
 191         //---------------------------------------
 192         /** @short  return this map instance to as a
 193                     PropertyValue sequence, which can be
 194                     used in const environments only.
 195
 196             @descr  Its made const to prevent using of the
 197                     return value directly as an in/out parameter!
 198                     usage: myMethod(stlDequeAdapter.getAsPropertyValueList());
 199
 200             @return A const sequence of type PropertyValue, which
 201                     contains all items of this map.
 202          */
 203         const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > getAsConstPropertyValueList() const;
 204
 205         //---------------------------------------
 206         /** @short  check if the specified item exists
 207                     and return its (unpacked!) value or it returns the
 208                     specified default value otherwise.
 209
 210             @descr  If a value should be extracted only in case
 211                     the requsted property exists realy (without creating
 212                     of new items as it the index operator of a
 213                     has_map does!) this method can be used.
 214
 215             @param  sKey
 216                     key name of the item.
 217
 218             @param  aDefault
 219                     the default value, which is returned
 220                     if the specified item could not
 221                     be found.
 222
 223             @return The (unpacked!) value of the specified property or
 224                     the given default value otherwise.
 225
 226             @attention  "unpacked" means the Any content of every iterator->second!
 227          */
 228         template< class TValueType >
 229         TValueType getUnpackedValueOrDefault(const OUString& sKey    ,
 230                                              const TValueType&      aDefault) const
 231         {
 232             const_iterator pIt = find(sKey);
 233             if (pIt == end())
 234                 return aDefault;
 235
 236             TValueType aValue = TValueType();
 237             if (!(pIt->second >>= aValue))
 238                 return aDefault;
 239
 240             return aValue;
 241         }
 242
 243         //---------------------------------------
 244         /** @short  creates a new item with the specified
 245                     name and value only in case such item name
 246                     does not already exist.
 247
 248             @descr  To check if the property already exists only
 249                     her name is used for compare. Its value isnt
 250                     checked!
 251
 252             @param  sKey
 253                     key name of the property.
 254
 255             @param  aValue
 256                     the new (unpacked!) value.
 257                     Note: This value will be transformed to an Any
 258                     internaly, because only Any values can be
 259                     part of a PropertyValue or NamedValue structure.
 260
 261             @return TRUE if this property was added as new item;
 262                     FALSE if it already exists.
 263          */
 264         template< class TValueType >
 265         sal_Bool createItemIfMissing(const OUString& sKey  ,
 266                                      const TValueType&      aValue)
 267         {
 268             if (find(sKey) == end())
 269             {
 270                 (*this)[sKey] = ::com::sun::star::uno::makeAny(aValue);
 271                 return sal_True;
 272             }
 273
 274             return sal_False;
 275         }
 276
 277         //---------------------------------------
 278         /** @short  check if all items of given map
 279                     exists in these called map also.
 280
 281             @descr  Every item of the given map must exists
 282                     with same name and value inside these map.
 283                     But these map can contain additional items
 284                     which are not part of the search-map.
 285
 286             @param  rCheck
 287                     the map containing all items for checking.
 288
 289             @return
 290                     TRUE if all items of Rcheck could be found
 291                     in these map; FALSE otherwise.
 292          */
 293         sal_Bool match(const SequenceAsHashMap& rCheck) const;
 294
 295         //---------------------------------------
 296         /** @short  merge all values from the given map into
 297                     this one.
 298
 299             @descr  Existing items will be overwritten ...
 300                     missing items will be created new ...
 301                     but non specified items will stay alive !
 302
 303             @param  rSource
 304                     the map containing all items for the update.
 305          */
 306         void update(const SequenceAsHashMap& rSource);
 307 };
 308
 309 } // namespace comphelper
 310
 311 #endif // _COMPHELPER_SEQUENCEASHASHMAP_HXX_
 312
 313 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */