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 __com_sun_star_container_XMap_idl__ 25#define __com_sun_star_container_XMap_idl__ 26 27#include <com/sun/star/beans/IllegalTypeException.idl> 28#include <com/sun/star/lang/IllegalArgumentException.idl> 29#include <com/sun/star/container/NoSuchElementException.idl> 30#include <com/sun/star/lang/NoSupportException.idl> 31#include <com/sun/star/container/XElementAccess.idl> 32 33//============================================================================= 34 35module com { module sun { module star { module container { 36 37//============================================================================= 38 39/** describes a map between keys and values. 40 41 <p>Keys in the map are unique, and each key maps to exactly one value.</p> 42 43 <p>Locating elements in the map, both values and keys, requires a notion of equality of two objects. 44 In conformance with the <a href="http://udk.openoffice.org/common/man/typesystem.html">UNO type system</a>, 45 two values are said to be equal if and only if they have the same type, and both denote the same element of this 46 type's value set.</p> 47 48 @see <type>Map</type> for a default implementation of this interface 49*/ 50interface XMap 51{ 52 interface XElementAccess; 53 54 /** denotes the type of the keys in the map. 55 56 <p>Implementations are free to accept any supertype of <code>KeyType</code> as keys.</p> 57 */ 58 [attribute, readonly] type KeyType; 59 60 /** denotes the type of the values in the map. 61 62 <p>Implementations are free to accept any supertype of the <code>ValueType</code> as values.</p> 63 */ 64 [attribute, readonly] type ValueType; 65 66 /** clears the map, removing all key-value pairs from it. 67 68 @throws ::com::sun::star::beans::NoSupportException 69 if the map is not mutable. 70 */ 71 void clear() 72 raises( ::com::sun::star::lang::NoSupportException ); 73 74 /** determines whether a mapping for he given key exists in the map 75 76 @param Key 77 is the key whose presence in the map is to be tested. 78 @return 79 <TRUE/> if and only if the map contains a mapping for the given key. 80 81 @throws ::com::sun::star::beans::IllegalTypeException 82 if the given key is not of a type which is accepted by the map 83 @throws ::com::sun::star::lang::IllegalArgumentException 84 if the given key is not supported to be put into the map. It's up to the service 85 implementing the <code>XMap</code> interface to specify which special values are not 86 supported. For instances, implementations might decide to not allow <VOID/> keys, or 87 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 88 behavior with respect to equality. 89 */ 90 boolean containsKey( [in] any Key ) 91 raises( ::com::sun::star::beans::IllegalTypeException, 92 ::com::sun::star::lang::IllegalArgumentException ); 93 94 /** determines whether the map contains a mapping to a given value. 95 96 @param Value 97 is the value whose presence in the map is to be tested. 98 @return 99 <TRUE/> if and only one or more keys map to the given value. 100 101 @throws ::com::sun::star::beans::IllegalTypeException 102 if the given value is not of a type which is accepted by the map. It's up to the service 103 implementing the <code>XMap</code> interface to specify which special values are not 104 supported. For instances, implementations might decide to not allow <code>Double.NaN</code> 105 (<em>not a number</em>) to due its problematic behavior with respect to equality. 106 @throws ::com::sun::star::lang::IllegalArgumentException 107 if the given value is not supported to be put into the map. 108 */ 109 boolean containsValue( [in] any Value ) 110 raises( ::com::sun::star::beans::IllegalTypeException, 111 ::com::sun::star::lang::IllegalArgumentException ); 112 113 /** gets the value to which a given key maps. 114 115 @param Key 116 they key whose associated value is to be returned. 117 @return 118 the value which is associated with the given key. 119 120 @throws ::com::sun::star::beans::IllegalTypeException 121 if the given key is not of a type which is accepted by the map 122 @throws ::com::sun::star::beans::IllegalArgumentException 123 if the given key is not supported to be put into the map. It's up to the service 124 implementing the <code>XMap</code> interface to specify which special values are not 125 supported. For instances, implementations might decide to not allow <VOID/> keys, or 126 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 127 behavior with respect to equality. 128 @throws ::com::sun::star::container::NoSuchElementException 129 if there is no value associated with the given key 130 */ 131 any get( [in] any Key ) 132 raises( ::com::sun::star::beans::IllegalTypeException, 133 ::com::sun::star::lang::IllegalArgumentException, 134 ::com::sun::star::container::NoSuchElementException ); 135 136 /** associates a given key with a given value 137 138 <p>If the map already contains a mapping for the given key, then the old value is replaced by the 139 given new value.</p> 140 141 @param Key 142 is the key which the given value should be associated with 143 @param Value 144 is the value which should be associated with the given key 145 @return 146 the value which was previously associated with the given key, or <VOID/> 147 if there was no such previous association. 148 149 @throws ::com::sun::star::beans::IllegalTypeException 150 if the given key is not of a type which is accepted by the map 151 @throws ::com::sun::star::lang::IllegalArgumentException 152 if the given key, or the given value, is not supported to be put into the map. It's up to 153 the service implementing the <code>XMap</code> interface to specify which special values 154 are not supported.<br/> 155 For instances, implementations might decide to not allow <VOID/> keys or values, or to 156 reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic behavior 157 with respect to equality. 158 @throws ::com::sun::star::beans::NoSupportException 159 if the map does not support putting new mappings into it 160 */ 161 any put( [in] any Key, [in] any Value ) 162 raises( ::com::sun::star::lang::NoSupportException, 163 ::com::sun::star::beans::IllegalTypeException, 164 ::com::sun::star::lang::IllegalArgumentException ); 165 166 /** removes a key-value mapping, given by key, from the map. 167 168 @param Key 169 is the key whose mapping should be removed from the map 170 @return 171 the value which was associated with the given key before the removal 172 173 @throws ::com::sun::star::beans::IllegalTypeException 174 if the given key is not of a type which is accepted by the map 175 @throws ::com::sun::star::lang::IllegalArgumentException 176 if the given key is not supported to be put into the map. It's up to the service 177 implementing the <code>XMap</code> interface to specify which special values are not 178 supported. For instances, implementations might decide to not allow <VOID/> keys, or 179 to reject <code>Double.NaN</code> (<em>not a number</em>) to due its problematic 180 behavior with respect to equality. 181 @throws ::com::sun::star::beans::NoSupportException 182 if the map does not support removing mappings 183 @throws ::com::sun::star::container::NoSuchElementException 184 if there is no value associated with the given key 185 */ 186 any remove( [in] any Key ) 187 raises( ::com::sun::star::lang::NoSupportException, 188 ::com::sun::star::beans::IllegalTypeException, 189 ::com::sun::star::lang::IllegalArgumentException, 190 ::com::sun::star::container::NoSuchElementException ); 191}; 192 193//============================================================================= 194 195}; }; }; }; 196 197//============================================================================= 198 199#endif 200