udkapi/com/sun/star/container/XMap.idl

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