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