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 <unordered_map>
  24 #include <com/sun/star/uno/Sequence.hxx>
  25
  26 #include <comphelper/comphelperdllapi.h>
  27
  28 namespace com::sun::star::beans { struct NamedValue; }
  29 namespace com::sun::star::beans { struct PropertyValue; }
  30
  31 namespace comphelper{
  32
  33
  34 /** @short  Implements a stl hash map on top of some
  35             specialized sequence from type PropertyValue
  36             or NamedValue.
  37
  38     @descr  That provides the possibility to modify
  39             such name sequences very easy ...
  40  */
  41
  42 /** Cache the hash code since calculating it for every comparison adds up */
  43 struct OUStringAndHashCode
  44 {
  45     OUString maString;
  46     sal_Int32 mnHashCode;
  47
  48     OUStringAndHashCode(OUString s) : maString(s), mnHashCode(maString.hashCode()) {}
  49 };
  50 struct OUStringAndHashCodeEqual
  51 {
  52     bool operator()(const OUStringAndHashCode & lhs, const OUStringAndHashCode & rhs) const
  53     {
  54         return lhs.mnHashCode == rhs.mnHashCode && lhs.maString == rhs.maString;
  55     }
  56 };
  57 struct OUStringAndHashCodeHash
  58 {
  59     size_t operator()(const OUStringAndHashCode & i) const
  60     {
  61         return i.mnHashCode;
  62     }
  63 };
  64 using SequenceAsHashMapBase = std::unordered_map<OUStringAndHashCode, css::uno::Any, OUStringAndHashCodeHash, OUStringAndHashCodeEqual>;
  65
  66 class SAL_WARN_UNUSED COMPHELPER_DLLPUBLIC SequenceAsHashMap
  67 {
  68
  69     public:
  70
  71
  72         /** @short  creates an empty hash map.
  73          */
  74         SequenceAsHashMap();
  75
  76
  77         /** @see    operator<<(const css::uno::Any&)
  78          */
  79         SequenceAsHashMap(const css::uno::Any& aSource);
  80
  81
  82         /** @see    operator<<(const css::uno::Sequence< css::uno::Any >&)
  83          */
  84         SequenceAsHashMap(const css::uno::Sequence< css::uno::Any >& lSource);
  85
  86
  87         /** @see    operator<<(const css::uno::Sequence< css::beans::PropertyValue >&)
  88          */
  89         SequenceAsHashMap(const css::uno::Sequence< css::beans::PropertyValue >& lSource);
  90
  91
  92         /** @see    operator<<(const css::uno::Sequence< css::beans::NamedValue >&)
  93          */
  94         SequenceAsHashMap(const css::uno::Sequence< css::beans::NamedValue >& lSource);
  95
  96
  97         /** @short  fill this map from the given
  98                     Any, which of course must contain
  99                     a suitable sequence of element types
 100                     "css.beans.PropertyValue" or "css.beans.NamedValue".
 101
 102             @attention  If the given Any is an empty one
 103                         (if it's set to VOID), no exception
 104                         is thrown. In such case this instance will
 105                         be created as an empty one too!
 106
 107             @param  aSource
 108                     contains the new items for this map.
 109
 110             @throw  A css::lang::IllegalArgumentException
 111                     is thrown, if the given Any does not contain a suitable sequence ...
 112                     but not if it's a VOID Any!
 113          */
 114         void operator<<(const css::uno::Any& aSource);
 115
 116
 117         /** @short  fill this map from the given
 118                     sequence, where every Any must contain
 119                     an item from type "css.beans.PropertyValue"
 120                     "css.beans.NamedValue".
 121
 122             @param  lSource
 123                     contains the new items for this map.
 124
 125             @throw  A css::lang::IllegalArgumentException
 126                     is thrown, if the given Any sequence
 127                     uses wrong types for its items. VOID Any will be ignored!
 128          */
 129         void operator<<(const css::uno::Sequence< css::uno::Any >& lSource);
 130
 131
 132         /** @short  fill this map from the given
 133                     PropertyValue sequence.
 134
 135             @param  lSource
 136                     contains the new items for this map.
 137          */
 138         void operator<<(const css::uno::Sequence< css::beans::PropertyValue >& lSource);
 139
 140
 141         /** @short  fill this map from the given
 142                     NamedValue sequence.
 143
 144             @param  lSource
 145                     contains the new items for this map.
 146          */
 147         void operator<<(const css::uno::Sequence< css::beans::NamedValue >& lSource);
 148
 149
 150         /** @short  converts this map instance to an
 151                     PropertyValue sequence.
 152
 153             @param  lDestination
 154                     target sequence for converting.
 155          */
 156         void operator>>(css::uno::Sequence< css::beans::PropertyValue >& lDestination) const;
 157
 158
 159         /** @short  converts this map instance to an
 160                     NamedValue sequence.
 161
 162             @param  lDestination
 163                     target sequence for converting.
 164          */
 165         void operator>>(css::uno::Sequence< css::beans::NamedValue >& lDestination) const;
 166
 167
 168         /** @short  return this map instance as an
 169                     Any, which can be
 170                     used in const environments only.
 171
 172             @descr  It's made const to prevent using of the
 173                     return value directly as an in/out parameter!
 174                     usage: myMethod(stlDequeAdapter.getAsAnyList());
 175
 176             @param  bAsPropertyValue
 177                     switch between using of PropertyValue or NamedValue as
 178                     value type.
 179
 180             @return A const Any, which
 181                     contains all items of this map.
 182          */
 183         css::uno::Any getAsConstAny(bool bAsPropertyValue) const;
 184
 185
 186         /** @short  return this map instance to as a
 187                     NamedValue sequence, which can be
 188                     used in const environments only.
 189
 190             @descr  It's made const to prevent using of the
 191                     return value directly as an in/out parameter!
 192                     usage: myMethod(stlDequeAdapter.getAsNamedValueList());
 193
 194             @return A const sequence of type NamedValue, which
 195                     contains all items of this map.
 196          */
 197         css::uno::Sequence< css::beans::NamedValue > getAsConstNamedValueList() const;
 198
 199
 200         /** @short  return this map instance to as a
 201                     PropertyValue sequence, which can be
 202                     used in const environments only.
 203
 204             @descr  It's made const to prevent using of the
 205                     return value directly as an in/out parameter!
 206                     usage: myMethod(stlDequeAdapter.getAsPropertyValueList());
 207
 208             @return A const sequence of type PropertyValue, which
 209                     contains all items of this map.
 210          */
 211         css::uno::Sequence< css::beans::PropertyValue > getAsConstPropertyValueList() const;
 212
 213
 214         /** @short  check if the specified item exists
 215                     and return its (unpacked!) value or it returns the
 216                     specified default value otherwise.
 217
 218             @descr  If a value should be extracted only in case
 219                     the requested property exists really (without creating
 220                     of new items as it the index operator of a
 221                     hash map does!) this method can be used.
 222
 223             @param  sKey
 224                     key name of the item.
 225
 226             @param  aDefault
 227                     the default value, which is returned
 228                     if the specified item could not
 229                     be found.
 230
 231             @return The (unpacked!) value of the specified property or
 232                     the given default value otherwise.
 233
 234             @attention  "unpacked" means the Any content of every iterator->second!
 235          */
 236         template< class TValueType >
 237         TValueType getUnpackedValueOrDefault(const OUString& sKey    ,
 238                                              const TValueType&      aDefault) const
 239         {
 240             auto pIt = m_aMap.find(sKey);
 241             if (pIt == m_aMap.end())
 242                 return aDefault;
 243
 244             TValueType aValue = TValueType();
 245             if (!(pIt->second >>= aValue))
 246                 return aDefault;
 247
 248             return aValue;
 249         }
 250
 251         /** @short  check if the specified item exists
 252                     and return its value or it returns
 253                     an empty css::uno::Any.
 254
 255             @descr  If a value should be extracted only in case
 256                     the requested property exists really (without creating
 257                     of new items as the index operator of a
 258                     hash map does!) this method can be used.
 259
 260             @param  sKey
 261                     key name of the item.
 262
 263             @return The value of the specified property or
 264                     an empty css::uno::Any.
 265          */
 266         css::uno::Any getValue(const OUString& sKey) const
 267         {
 268             auto pIt = m_aMap.find(sKey);
 269             if (pIt == m_aMap.end())
 270                 return css::uno::Any();
 271
 272             return pIt->second;
 273         }
 274
 275
 276         /** @short  creates a new item with the specified
 277                     name and value only in case such item name
 278                     does not already exist.
 279
 280             @descr  To check if the property already exists only
 281                     its name is used for compare. Its value isn't
 282                     checked!
 283
 284             @param  sKey
 285                     key name of the property.
 286
 287             @param  aValue
 288                     the new (unpacked!) value.
 289                     Note: This value will be transformed to an Any
 290                     internally, because only Any values can be
 291                     part of a PropertyValue or NamedValue structure.
 292
 293             @return TRUE if this property was added as new item;
 294                     FALSE if it already exists.
 295          */
 296         template< class TValueType >
 297         bool createItemIfMissing(const OUString& sKey  ,
 298                                      const TValueType&      aValue)
 299         {
 300             if (m_aMap.find(sKey) == m_aMap.end())
 301             {
 302                 (*this)[sKey] = css::uno::toAny(aValue);
 303                 return true;
 304             }
 305
 306             return false;
 307         }
 308
 309
 310         /** @short  check if all items of given map
 311                     exists in these called map also.
 312
 313             @descr  Every item of the given map must exists
 314                     with same name and value inside these map.
 315                     But these map can contain additional items
 316                     which are not part of the search-map.
 317
 318             @param  rCheck
 319                     the map containing all items for checking.
 320
 321             @return
 322                     TRUE if all items of Rcheck could be found
 323                     in these map; FALSE otherwise.
 324          */
 325         bool match(const SequenceAsHashMap& rCheck) const;
 326
 327
 328         /** @short  merge all values from the given map into
 329                     this one.
 330
 331             @descr  Existing items will be overwritten ...
 332                     missing items will be created new ...
 333                     but non specified items will stay alive !
 334
 335             @param  rSource
 336                     the map containing all items for the update.
 337          */
 338         void update(const SequenceAsHashMap& rSource);
 339
 340         css::uno::Any& operator[](const OUString& rKey)
 341         {
 342             return m_aMap[rKey];
 343         }
 344
 345         css::uno::Any& operator[](const OUStringAndHashCode& rKey)
 346         {
 347             return m_aMap[rKey];
 348         }
 349
 350         using iterator = SequenceAsHashMapBase::iterator;
 351         using const_iterator = SequenceAsHashMapBase::const_iterator;
 352
 353         void clear()
 354         {
 355             m_aMap.clear();
 356         }
 357
 358         size_t size() const
 359         {
 360             return m_aMap.size();
 361         }
 362
 363         bool empty() const
 364         {
 365             return m_aMap.empty();
 366         }
 367
 368         iterator begin()
 369         {
 370             return m_aMap.begin();
 371         }
 372
 373         const_iterator begin() const
 374         {
 375             return m_aMap.begin();
 376         }
 377
 378         iterator end()
 379         {
 380             return m_aMap.end();
 381         }
 382
 383         const_iterator end() const
 384         {
 385             return m_aMap.end();
 386         }
 387
 388         iterator find(const OUString& rKey)
 389         {
 390             return m_aMap.find(rKey);
 391         }
 392
 393         const_iterator find(const OUString& rKey) const
 394         {
 395             return m_aMap.find(rKey);
 396         }
 397
 398         iterator find(const OUStringAndHashCode& rKey)
 399         {
 400             return m_aMap.find(rKey);
 401         }
 402
 403         const_iterator find(const OUStringAndHashCode& rKey) const
 404         {
 405             return m_aMap.find(rKey);
 406         }
 407
 408         iterator erase(iterator it)
 409         {
 410             return m_aMap.erase(it);
 411         }
 412
 413         size_t erase(const OUString& rKey)
 414         {
 415             return m_aMap.erase(rKey);
 416         }
 417
 418 private:
 419         SequenceAsHashMapBase m_aMap;
 420 };
 421
 422 } // namespace comphelper
 423
 424 #endif // INCLUDED_COMPHELPER_SEQUENCEASHASHMAP_HXX
 425
 426 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */