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