1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef _COMPHELPER_SEQUENCEASHASHMAP_HXX_ 25 #define _COMPHELPER_SEQUENCEASHASHMAP_HXX_ 26 27 //_______________________________________________ 28 // includes 29 30 #ifndef INCLUDED_HASH_MAP 31 #include <hash_map> 32 #define INCLUDED_HASH_MAP 33 #endif 34 35 #ifndef INCLUDED_ALGORITHM 36 #include <algorithm> 37 #define INCLUDED_ALGORITHM 38 #endif 39 #include <com/sun/star/uno/Sequence.hxx> 40 #include <com/sun/star/beans/PropertyValue.hpp> 41 #include <com/sun/star/beans/NamedValue.hpp> 42 43 #ifndef _COM_SUN_STAR_BEANS_IllegalTypeException_HPP_ 44 #include <com/sun/star/beans/IllegalTypeException.hpp> 45 #endif 46 #include "comphelper/comphelperdllapi.h" 47 48 // see method dbg_dumpToFile() below! 49 #if OSL_DEBUG_LEVEL > 1 50 #ifndef _RTL_USTRBUF_HXX_ 51 #include <rtl/ustrbuf.hxx> 52 #endif 53 54 #include <stdio.h> 55 #endif 56 57 //_______________________________________________ 58 // namespace 59 60 namespace comphelper{ 61 62 //_______________________________________________ 63 // definitions 64 65 /** @short Implements a stl hash map on top of some 66 specialized sequence from type PropertyValue 67 or NamedValue. 68 69 @descr That provides the possibility to modify 70 such name sequences very easy ... 71 */ 72 73 struct SequenceAsHashMapBase : public ::std::hash_map< 74 ::rtl::OUString , 75 ::com::sun::star::uno::Any , 76 ::rtl::OUStringHash , 77 ::std::equal_to< ::rtl::OUString > > 78 { 79 }; 80 81 class COMPHELPER_DLLPUBLIC SequenceAsHashMap : public SequenceAsHashMapBase 82 { 83 //------------------------------------------- 84 public: 85 86 //--------------------------------------- 87 /** @short creates an empty hash map. 88 */ 89 SequenceAsHashMap(); 90 91 //--------------------------------------- 92 /** @see operator<<(const ::com::sun::star::uno::Any&) 93 */ 94 SequenceAsHashMap(const ::com::sun::star::uno::Any& aSource); 95 96 //--------------------------------------- 97 /** @see operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >&) 98 */ 99 SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& lSource); 100 101 //--------------------------------------- 102 /** @see operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >&) 103 */ 104 SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lSource); 105 106 //--------------------------------------- 107 /** @see operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >&) 108 */ 109 SequenceAsHashMap(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lSource); 110 111 //--------------------------------------- 112 /** @short not realy used but maybe usefull :-) 113 */ 114 ~SequenceAsHashMap(); 115 116 //--------------------------------------- 117 /** @short fill this map from the given 118 any, which of course must contain 119 a suitable sequence of element types 120 "css.beans.PropertyValue" or "css.beans.NamedValue". 121 122 @attention If the given Any is an empty one 123 (if its set to VOID), no exception 124 is thrown. In such case this instance will 125 be created as an empty one too! 126 127 @param aSource 128 contains the new items for this map. 129 130 @throw An <type scope="com::sun::star::beans">IllegalTypeException</type> 131 is thrown, if the given any does not contain a suitable sequence ... 132 but not if its a VOID Any! 133 */ 134 void operator<<(const ::com::sun::star::uno::Any& aSource); 135 136 //--------------------------------------- 137 /** @short fill this map from the given 138 sequence, where every Any must contain 139 an item from type "css.beans.PropertyValue" 140 "css.beans.NamedValue". 141 142 @param lSource 143 contains the new items for this map. 144 145 @throw An <type scope="com::sun::star::beans">IllegalTypeException</type> 146 is thrown, if the given any sequence 147 uses wrong types for its items. VOID Any will be ignored! 148 */ 149 void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any >& lSource); 150 151 //--------------------------------------- 152 /** @short fill this map from the given 153 PropertyValue sequence. 154 155 @param lSource 156 contains the new items for this map. 157 */ 158 void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lSource); 159 160 //--------------------------------------- 161 /** @short fill this map from the given 162 NamedValue sequence. 163 164 @param lSource 165 contains the new items for this map. 166 */ 167 void operator<<(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lSource); 168 169 //--------------------------------------- 170 /** @short converts this map instance to an 171 PropertyValue sequence. 172 173 @param lDestination 174 target sequence for converting. 175 */ 176 void operator>>(::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lDestination) const; 177 178 //--------------------------------------- 179 /** @short converts this map instance to an 180 NamedValue sequence. 181 182 @param lDestination 183 target sequence for converting. 184 */ 185 void operator>>(::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue >& lDestination) const; 186 187 //--------------------------------------- 188 /** @short return this map instance as an 189 Any, which can be 190 used in const environments only. 191 192 @descr Its made const to prevent using of the 193 return value directly as an in/out parameter! 194 usage: myMethod(stlDequeAdapter.getAsAnyList()); 195 196 @param bAsPropertyValue 197 switch between using of PropertyValue or NamedValue as 198 value type. 199 200 @return A const Any, which 201 contains all items of this map. 202 */ 203 const ::com::sun::star::uno::Any getAsConstAny(::sal_Bool bAsPropertyValue) const; 204 205 //--------------------------------------- 206 /** @short return this map instance as a 207 sequence< Any >, which can be 208 used in const environments only. 209 210 @descr Its made const to prevent using of the 211 return value directly as an in/out parameter! 212 usage: myMethod(stlDequeAdapter.getAsAnyList()); 213 214 @param bAsPropertyValue 215 switch between using of PropertyValue or NamedValue as 216 value type. 217 218 @return A const sequence which elements of Any, which 219 contains all items of this map. 220 */ 221 const ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > getAsConstAnyList(::sal_Bool bAsPropertyValue) const; 222 223 //--------------------------------------- 224 /** @short return this map instance to as a 225 NamedValue sequence, which can be 226 used in const environments only. 227 228 @descr Its made const to prevent using of the 229 return value directly as an in/out parameter! 230 usage: myMethod(stlDequeAdapter.getAsNamedValueList()); 231 232 @return A const sequence of type NamedValue, which 233 contains all items of this map. 234 */ 235 const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::NamedValue > getAsConstNamedValueList() const; 236 237 //--------------------------------------- 238 /** @short return this map instance to as a 239 PropertyValue sequence, which can be 240 used in const environments only. 241 242 @descr Its made const to prevent using of the 243 return value directly as an in/out parameter! 244 usage: myMethod(stlDequeAdapter.getAsPropertyValueList()); 245 246 @return A const sequence of type PropertyValue, which 247 contains all items of this map. 248 */ 249 const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue > getAsConstPropertyValueList() const; 250 251 //--------------------------------------- 252 /** @short check if the specified item exists 253 and return its (unpacked!) value or it returns the 254 specified default value otherwhise. 255 256 @descr If a value should be extracted only in case 257 the requsted property exists realy (without creating 258 of new items as it the index operator of a 259 has_map does!) this method can be used. 260 261 @param sKey 262 key name of the item. 263 264 @param aDefault 265 the default value, which is returned 266 if the specified item could not 267 be found. 268 269 @return The (unpacked!) value of the specified property or 270 the given default value otherwhise. 271 272 @attention "unpacked" means the Any content of every iterator->second! 273 */ 274 template< class TValueType > getUnpackedValueOrDefault(const::rtl::OUString & sKey,const TValueType & aDefault) const275 TValueType getUnpackedValueOrDefault(const ::rtl::OUString& sKey , 276 const TValueType& aDefault) const 277 { 278 const_iterator pIt = find(sKey); 279 if (pIt == end()) 280 return aDefault; 281 282 TValueType aValue = TValueType(); 283 if (!(pIt->second >>= aValue)) 284 return aDefault; 285 286 return aValue; 287 } 288 289 //--------------------------------------- 290 /** @short creates a new item with the specified 291 name and value only in case such item name 292 does not already exist. 293 294 @descr To check if the property already exists only 295 her name is used for compare. Its value isnt 296 checked! 297 298 @param sKey 299 key name of the property. 300 301 @param aValue 302 the new (unpacked!) value. 303 Note: This value will be transformed to an Any 304 internaly, because only Any values can be 305 part of a PropertyValue or NamedValue structure. 306 307 @return TRUE if this property was added as new item; 308 FALSE if it already exists. 309 */ 310 template< class TValueType > createItemIfMissing(const::rtl::OUString & sKey,const TValueType & aValue)311 sal_Bool createItemIfMissing(const ::rtl::OUString& sKey , 312 const TValueType& aValue) 313 { 314 if (find(sKey) == end()) 315 { 316 (*this)[sKey] = ::com::sun::star::uno::makeAny(aValue); 317 return sal_True; 318 } 319 320 return sal_False; 321 } 322 323 //--------------------------------------- 324 /** @short check if all items of given map 325 exists in these called map also. 326 327 @descr Every item of the given map must exists 328 with same name and value inside these map. 329 But these map can contain additional items 330 which are not part of the search-map. 331 332 @param rCheck 333 the map containing all items for checking. 334 335 @return 336 TRUE if all items of Rcheck could be found 337 in these map; FALSE otherwise. 338 */ 339 sal_Bool match(const SequenceAsHashMap& rCheck) const; 340 341 //--------------------------------------- 342 /** @short merge all values from the given map into 343 this one. 344 345 @descr Existing items will be overwritten ... 346 missing items will be created new ... 347 but non specified items will stay alive ! 348 349 @param rSource 350 the map containing all items for the update. 351 */ 352 void update(const SequenceAsHashMap& rSource); 353 354 //--------------------------------------- 355 /** @short can be used to generate a file dump of 356 the current content of this instance. 357 358 @descr Because the content of STL container 359 cant be analyzed easy, such dump function 360 seem to be usefull. 361 Of course its available in debug versions 362 only. 363 364 @param pFileName 365 a system file name. 366 (doesnt matter if relativ or absolute) 367 368 @param pComment 369 used to mark the dump inside the same log file. 370 Can be usefull to analyze changes of this 371 hash map due to the parts of an operation. 372 */ 373 #if OSL_DEBUG_LEVEL > 1 374 void dbg_dumpToFile(const char* pFileName, const char* pComment) const; 375 #endif 376 }; 377 378 } // namespace comphelper 379 380 #endif // _COMPHELPER_SEQUENCEASHASHMAP_HXX_ 381