include/oox/helper/containerhelper.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_OOX_HELPER_CONTAINERHELPER_HXX
  21 #define INCLUDED_OOX_HELPER_CONTAINERHELPER_HXX
  22
  23 #include <cstddef>
  24 #include <vector>
  25
  26 #include <com/sun/star/uno/Reference.hxx>
  27 #include <com/sun/star/uno/Sequence.hxx>
  28 #include <oox/dllapi.h>
  29 #include <rtl/ustring.hxx>
  30 #include <sal/types.h>
  31
  32 namespace com::sun::star {
  33     namespace container { class XNameAccess; }
  34     namespace container { class XNameContainer; }
  35     namespace uno { class Any; }
  36 }
  37
  38 namespace oox {
  39
  40
  41 /** A range of signed 32-bit integer values. */
  42 struct ValueRange
  43 {
  44     sal_Int32           mnFirst;
  45     sal_Int32           mnLast;
  46
  47     explicit     ValueRange( sal_Int32 nValue ) : mnFirst( nValue ), mnLast( nValue ) {}
  48     explicit     ValueRange( sal_Int32 nFirst, sal_Int32 nLast ) : mnFirst( nFirst ), mnLast( nLast ) {}
  49
  50     bool         operator==( const ValueRange& rRange ) const { return (mnFirst == rRange.mnFirst) && (mnLast == rRange.mnLast); }
  51     bool         operator!=( const ValueRange& rRange ) const { return !(*this == rRange); }
  52     bool         contains( const ValueRange& rRange ) const { return (mnFirst <= rRange.mnFirst) && (rRange.mnLast <= mnLast); }
  53     bool         intersects( const ValueRange& rRange ) const { return (mnFirst <= rRange.mnLast) && (rRange.mnFirst <= mnLast); }
  54 };
  55
  56
  57 typedef ::std::vector< ValueRange > ValueRangeVector;
  58
  59
  60 /** An ordered list of value ranges. The insertion operation will merge
  61     consecutive value ranges.
  62  */
  63 class OOX_DLLPUBLIC ValueRangeSet
  64 {
  65 public:
  66                         ValueRangeSet() {}
  67
  68     /** Inserts the passed value range into the range list. */
  69     void                insert( const ValueRange& rRange );
  70
  71     /** Returns the ordered list of all value ranges. */
  72     const ValueRangeVector& getRanges() const { return maRanges; }
  73
  74 private:
  75     ValueRangeVector    maRanges;
  76 };
  77
  78
  79 /** Template for a 2-dimensional array of objects.
  80
  81     This class template provides a similar interface to the ::std::vector
  82     template.
  83  */
  84 template< typename Type >
  85 class Matrix
  86 {
  87 public:
  88     typedef ::std::vector< Type >                       container_type;
  89     typedef typename container_type::value_type         value_type;
  90     typedef typename container_type::pointer            pointer;
  91     typedef typename container_type::reference          reference;
  92     typedef typename container_type::const_reference    const_reference;
  93     typedef typename container_type::size_type          size_type;
  94     typedef typename container_type::iterator           iterator;
  95     typedef typename container_type::const_iterator     const_iterator;
  96
  97                  Matrix() : mnWidth( 0 ) {}
  98     explicit     Matrix( size_type nWidth, size_type nHeight ) { resize( nWidth, nHeight ); }
  99     explicit     Matrix( size_type nWidth, size_type nHeight, const_reference rData ) { resize( nWidth, nHeight, rData ); }
 100
 101     bool         empty() const { return maData.empty(); }
 102     size_type    size() const { return maData.size(); }
 103     size_type    width() const { return mnWidth; }
 104     size_type    height() const { return empty() ? 0 : (size() / width()); }
 105
 106     void         clear() { resize( 0, 0 ); }
 107     void         resize( size_type nWidth, size_type nHeight ) { mnWidth = nWidth; maData.resize( nWidth * nHeight ); }
 108     void         resize( size_type nWidth, size_type nHeight, const_reference rData ) { mnWidth = nWidth; maData.resize( nWidth * nHeight, rData ); }
 109
 110     iterator     at( size_type nX, size_type nY ) { return maData.begin() + mnWidth * nY + nX; }
 111     const_iterator at( size_type nX, size_type nY ) const { return maData.begin() + mnWidth * nY + nX; }
 112
 113     reference    operator()( size_type nX, size_type nY ) { return *at( nX, nY ); }
 114     const_reference operator()( size_type nX, size_type nY ) const { return *at( nX, nY ); }
 115
 116     iterator     begin() { return maData.begin(); }
 117     const_iterator begin() const { return maData.begin(); }
 118     iterator     end() { return maData.end(); }
 119     const_iterator end() const { return maData.end(); }
 120
 121     iterator     row_begin( size_type nY ) { return at( 0, nY ); }
 122     const_iterator row_begin( size_type nY ) const { return at( 0, nY ); }
 123     iterator     row_end( size_type nY ) { return at( mnWidth, nY ); }
 124     const_iterator row_end( size_type nY ) const { return at( mnWidth, nY ); }
 125
 126     reference    row_front( size_type nY ) { return (*this)( 0, nY ); }
 127     const_reference row_front( size_type nY ) const { return (*this)( 0, nY ); }
 128
 129 private:
 130     container_type      maData;
 131     size_type           mnWidth;
 132 };
 133
 134
 135 /** Static helper functions for improved API container handling. */
 136 class OOX_DLLPUBLIC ContainerHelper
 137 {
 138 public:
 139
 140     /** Returns a name that is not used in the passed name container.
 141
 142         @param rxNameAccess  com.sun.star.container.XNameAccess interface of
 143             the name container.
 144
 145         @param rSuggestedName  Suggested name for the object.
 146
 147         @return  An unused name. Will be equal to the suggested name, if not
 148             contained, otherwise a numerical index will be appended.
 149      */
 150     static OUString getUnusedName(
 151                             const css::uno::Reference< css::container::XNameAccess >& rxNameAccess,
 152                             const OUString& rSuggestedName,
 153                             sal_Unicode cSeparator );
 154
 155     /** Inserts an object into a name container.
 156
 157         @param rxNameContainer  com.sun.star.container.XNameContainer interface
 158             of the name container.
 159
 160         @param rName  Exact name for the object.
 161
 162         @param rObject  The object to be inserted.
 163
 164         @return  True = object successfully inserted.
 165      */
 166     static bool         insertByName(
 167                             const css::uno::Reference< css::container::XNameContainer >& rxNameContainer,
 168                             const OUString& rName,
 169                             const css::uno::Any& rObject );
 170
 171     /** Inserts an object into a name container.
 172
 173         The function will use an unused name to insert the object, based on the
 174         suggested object name. It is possible to specify whether the existing
 175         object or the new inserted object will be renamed, if the container
 176         already has an object with the name suggested for the new object.
 177
 178         @param rxNameContainer  com.sun.star.container.XNameContainer interface
 179             of the name container.
 180
 181         @param rSuggestedName  Suggested name for the object.
 182
 183         @param rObject  The object to be inserted.
 184
 185         The new object
 186         will be inserted with a name not yet extant in the container (this
 187         is done by appending a numerical index to the suggested name).
 188
 189         @return  The final name the object is inserted with. Will always be
 190             equal to the suggested name, if parameter bRenameOldExisting is
 191             true.
 192      */
 193     static OUString insertByUnusedName(
 194                             const css::uno::Reference< css::container::XNameContainer >& rxNameContainer,
 195                             const OUString& rSuggestedName,
 196                             sal_Unicode cSeparator,
 197                             const css::uno::Any& rObject );
 198
 199     // std::vector and std::map element access --------------------------------
 200
 201     /** Returns the pointer to an existing element of the passed vector, or a
 202         null pointer, if the passed index is out of bounds. */
 203     template< typename VectorType >
 204     static const typename VectorType::value_type*
 205                         getVectorElement( const VectorType& rVector, sal_Int32 nIndex );
 206
 207     /** Returns the pointer to an existing element of the passed vector, or a
 208         null pointer, if the passed index is out of bounds. */
 209     template< typename VectorType >
 210     static typename VectorType::value_type*
 211                         getVectorElementAccess( VectorType& rVector, sal_Int32 nIndex );
 212
 213     /** Returns the reference to an existing element of the passed vector, or
 214         the passed default value, if the passed index is out of bounds. */
 215     template< typename VectorType >
 216     static const typename VectorType::value_type&
 217                         getVectorElement( const VectorType& rVector, sal_Int32 nIndex, const typename VectorType::value_type& rDefault );
 218
 219     /** Returns the pointer to an existing element of the passed map, or a null
 220         pointer, if an element with the passed key does not exist. */
 221     template< typename MapType >
 222     static const typename MapType::mapped_type*
 223                         getMapElement( const MapType& rMap, const typename MapType::key_type& rKey );
 224
 225     /** Returns the reference to an existing element of the passed map, or the
 226         passed default value, if an element with the passed key does not exist. */
 227     template< typename MapType >
 228     static const typename MapType::mapped_type&
 229                         getMapElement( const MapType& rMap, const typename MapType::key_type& rKey, const typename MapType::mapped_type& rDefault );
 230
 231     /** Creates a UNO sequence of sequences from a matrix with copies of all elements.
 232
 233         @param rMatrix  The matrix to be converted to a sequence of sequences.
 234
 235         @return  A com.sun.star.uno.Sequence object containing
 236             com.sun.star.uno.Sequence objects with copies of all objects
 237             contained in the passed matrix.
 238      */
 239     template< typename MatrixType >
 240     static css::uno::Sequence< css::uno::Sequence< typename MatrixType::value_type > >
 241                             matrixToSequenceSequence( const MatrixType& rMatrix );
 242 };
 243
 244
 245 template< typename VectorType >
 246 /*static*/ const typename VectorType::value_type* ContainerHelper::getVectorElement( const VectorType& rVector, sal_Int32 nIndex )
 247 {
 248     return ((0 <= nIndex) && (static_cast< size_t >( nIndex ) < rVector.size())) ? &rVector[ static_cast< size_t >( nIndex ) ] : nullptr;
 249 }
 250
 251 template< typename VectorType >
 252 /*static*/ typename VectorType::value_type* ContainerHelper::getVectorElementAccess( VectorType& rVector, sal_Int32 nIndex )
 253 {
 254     return ((0 <= nIndex) && (static_cast< size_t >( nIndex ) < rVector.size())) ? &rVector[ static_cast< size_t >( nIndex ) ] : nullptr;
 255 }
 256
 257 template< typename VectorType >
 258 /*static*/ const typename VectorType::value_type& ContainerHelper::getVectorElement( const VectorType& rVector, sal_Int32 nIndex, const typename VectorType::value_type& rDefault )
 259 {
 260     return ((0 <= nIndex) && (static_cast< size_t >( nIndex ) < rVector.size())) ? rVector[ static_cast< size_t >( nIndex ) ] : rDefault;
 261 }
 262
 263 template< typename MapType >
 264 /*static*/ const typename MapType::mapped_type* ContainerHelper::getMapElement( const MapType& rMap, const typename MapType::key_type& rKey )
 265 {
 266     typename MapType::const_iterator aIt = rMap.find( rKey );
 267     return (aIt == rMap.end()) ? nullptr : &aIt->second;
 268 }
 269
 270 template< typename MapType >
 271 /*static*/ const typename MapType::mapped_type& ContainerHelper::getMapElement( const MapType& rMap, const typename MapType::key_type& rKey, const typename MapType::mapped_type& rDefault )
 272 {
 273     typename MapType::const_iterator aIt = rMap.find( rKey );
 274     return (aIt == rMap.end()) ? rDefault : aIt->second;
 275 }
 276
 277 template< typename MatrixType >
 278 /*static*/ css::uno::Sequence< css::uno::Sequence< typename MatrixType::value_type > > ContainerHelper::matrixToSequenceSequence( const MatrixType& rMatrix )
 279 {
 280     typedef typename MatrixType::value_type ValueType;
 281     css::uno::Sequence< css::uno::Sequence< ValueType > > aSeq;
 282     if( !rMatrix.empty() )
 283     {
 284         aSeq.realloc( static_cast< sal_Int32 >( rMatrix.height() ) );
 285         auto pSeq = aSeq.getArray();
 286         for( size_t nRow = 0, nHeight = rMatrix.height(); nRow < nHeight; ++nRow )
 287             pSeq[ static_cast< sal_Int32 >( nRow ) ] =
 288                 css::uno::Sequence< ValueType >( &rMatrix.row_front( nRow ), static_cast< sal_Int32 >( rMatrix.width() ) );
 289     }
 290     return aSeq;
 291 }
 292
 293
 294 } // namespace oox
 295
 296 #endif
 297
 298 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */