comphelper/inc/comphelper/optionalvalue.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: optionalvalue.hxx,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _COMPHELPER_OPTIONALVALUE_HXX
  32 #define _COMPHELPER_OPTIONALVALUE_HXX
  33
  34 #include <com/sun/star/uno/Any.hxx>
  35
  36 namespace comphelper
  37 {
  38
  39 /** @deprecated
  40     Use boost/optional.hpp instead.
  41 */
  42
  43
  44
  45     /* Definition of OptionalValue template */
  46
  47     /** This template provides 'optionality' for the given value type.
  48
  49         Especially for PODs, optionality either needs to be achieved
  50         by special 'magic' values (i.e. an int value is not set when
  51         -1 etc.), or an additional bool denoting value
  52         validity. This template encapsulates the latter into an atomic
  53         data type.
  54
  55         @tpl Element
  56         The value type that should be made optional
  57      */
  58     template< typename Element > class OptionalValue
  59     {
  60     public:
  61         typedef Element ValueType;
  62
  63         /** Default-construct the value.
  64
  65             A default-constructed value is not valid. You have to
  66             explicitely set a value.
  67          */
  68         OptionalValue() :
  69             maValue(),
  70             mbValid( false )
  71         {
  72         }
  73
  74         /** Construct the value.
  75
  76             An explicitely constructed value is valid. To create an
  77             invalid value, you have to default-construct it.
  78          */
  79         OptionalValue( const Element& rValue ) :
  80             maValue( rValue ),
  81             mbValid( true )
  82         {
  83         }
  84
  85         // default copy/assignment operators are okay here
  86         //OptionalValue(const OptionalValue&);
  87         //OptionalValue& operator=( const OptionalValue& );
  88
  89         /** Query whether the value is valid
  90
  91             @return true, if this object contains a valid value.
  92          */
  93         bool isValid() const
  94         {
  95             return mbValid;
  96         }
  97
  98         /** Set a value.
  99
 100             After this call, the object contains a valid value.
 101          */
 102         void setValue( const Element& rValue )
 103         {
 104             maValue = rValue;
 105             mbValid = true;
 106         }
 107
 108         /** Get the value.
 109
 110             The return value of this method is undefined, if the
 111             object does not contain a valid value.
 112          */
 113         Element getValue() const
 114         {
 115             return maValue;
 116         }
 117
 118         /** Clear the value.
 119
 120             After this call, the object no longer contains a valid
 121             value.
 122          */
 123         void clearValue()
 124         {
 125             mbValid = false;
 126         }
 127
 128         // NOTE: The following two methods would optimally have been
 129         // implemented as operator>>=/operator<<=
 130         // overloads. Unfortunately, there's already a templatized
 131         // version for those two methods, namely for UNO interface
 132         // types. Adding a second would lead to ambiguities.
 133
 134         /** Export the value into an Any.
 135
 136             This method extracts the value into an Any. If the value
 137             is invalid, the Any will be cleared.
 138
 139             @return true, if the value has been successfully
 140             transferred to the Any. Clearing the Any from an invalid
 141             object is also considered a successful operation.
 142          */
 143         bool exportValue( ::com::sun::star::uno::Any& o_rAny )
 144         {
 145             o_rAny.clear();
 146
 147             if( isValid() )
 148             {
 149                 if( !(o_rAny <<= getValue()) )
 150                     return false;
 151             }
 152
 153             return true;
 154         }
 155
 156         /** Import the value from an Any.
 157
 158             This method imports the value from an Any. If the Any
 159             is invalid, the object will get an invalid value.
 160
 161             @return true, if the value has been successfully
 162             transferred from the Any. Setting the value to invalid
 163             from an empty Any is also considered a successful
 164             operation.
 165          */
 166         bool importValue( const ::com::sun::star::uno::Any& rAny )
 167         {
 168             clearValue();
 169
 170             if( rAny.hasValue() )
 171             {
 172                 Element tmp;
 173
 174                 if( !(rAny >>= tmp) )
 175                     return false;
 176
 177                 setValue( tmp );
 178             }
 179
 180             return true;
 181         }
 182
 183     private:
 184         Element         maValue;
 185         bool            mbValid;
 186     };
 187
 188 }
 189
 190 #endif /* _COMPHELPER_OPTIONALVALUE_HXX */