sc/source/filter/inc/xestring.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 #pragma once
  21
  22 #include <sal/config.h>
  23
  24 #include <string_view>
  25
  26 #include "xlstring.hxx"
  27 #include "ftools.hxx"
  28
  29 class XclExpStream;
  30 class XclExpXmlStream;
  31
  32 /** This class stores an unformatted or formatted string for Excel export.
  33
  34     The class supports two completely different types of Excel strings:
  35     1)  BIFF2-BIFF7 byte strings: The text is encoded as a 8-bit character
  36         array. The strings cannot contain any character formatting.
  37     2)  BIFF8 Unicode strings: The text may be stored as UCS-2 character array,
  38         or compressed to an 8-bit array, if all characters are less than
  39         U+0100. Unicode strings may contain a formatting array, that specifies
  40         the used FONT record for different ranges of characters.
  41
  42     The class provides full support for NUL characters in strings. On
  43     construction or assignment the passed flags specify the behaviour of the
  44     string while it is written to a stream (the 'Write' functions and
  45     'operator<<').
  46  */
  47 class XclExpString
  48 {
  49 public:
  50     // constructors -----------------------------------------------------------
  51
  52     /** Constructs an empty BIFF8 Unicode string.
  53         @param nFlags  Modifiers for string export.
  54         @param nMaxLen  The maximum number of characters to store in this string. */
  55     explicit            XclExpString(
  56                             XclStrFlags nFlags = XclStrFlags::NONE,
  57                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  58
  59     /** Constructs an unformatted BIFF8 Unicode string.
  60         @param nFlags  Modifiers for string export.
  61         @param nMaxLen  The maximum number of characters to store in this string. */
  62     explicit            XclExpString(
  63                             const OUString& rString,
  64                             XclStrFlags nFlags = XclStrFlags::NONE,
  65                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  66
  67     // assign -----------------------------------------------------------------
  68
  69     /** Assigns an unformatted string, converts this object to a BIFF8 Unicode string.
  70         @param nFlags  Modifiers for string export.
  71         @param nMaxLen  The maximum number of characters to store in this string. */
  72     void                Assign(
  73                             const OUString& rString,
  74                             XclStrFlags nFlags = XclStrFlags::NONE,
  75                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  76
  77     /** Assigns a Unicode character, converts this object to a BIFF8 Unicode string. */
  78     void                Assign( sal_Unicode cChar );
  79
  80     /** Assigns an unformatted string, converts this object to a BIFF2-BIFF7 byte string.
  81         @param nFlags  Modifiers for string export.
  82         @param nMaxLen  The maximum number of characters to store in this string. */
  83     void                AssignByte(
  84                             std::u16string_view rString,
  85                             rtl_TextEncoding eTextEnc,
  86                             XclStrFlags nFlags = XclStrFlags::NONE,
  87                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  88
  89     // append -----------------------------------------------------------------
  90
  91     /** Appends a string. Uses the string flags used in constructor or last Assign().
  92         @descr  This object must be a BIFF8 Unicode string. */
  93     void                Append( std::u16string_view rString );
  94
  95     /** Appends a string. Uses the string flags used in constructor or last Assign().
  96         @descr  This object must be a BIFF2-BIFF7 byte string. */
  97     void                AppendByte( std::u16string_view rString, rtl_TextEncoding eTextEnc );
  98     /** Appends a character. Uses the string flags used in constructor or last Assign().
  99         @descr  This object must be a BIFF2-BIFF7 byte string. */
 100     void                AppendByte( sal_Unicode cChar, rtl_TextEncoding eTextEnc );
 101
 102     // formatting runs --------------------------------------------------------
 103
 104     /** Appends a formatting run. nChar must be greater than last contained character index. */
 105     void                AppendFormat( sal_uInt16 nChar, sal_uInt16 nFontIdx, bool bDropDuplicate = true );
 106     /** Appends a trailing formatting run with the passed font index. */
 107     void                AppendTrailingFormat( sal_uInt16 nFontIdx );
 108     /** Removes formatting runs at the end, if the string contains too much. */
 109     void                LimitFormatCount( sal_uInt16 nMaxCount );
 110     /** Returns the font index of the first char in the formatting run, or EXC_FONT_NOTFOUND. */
 111     sal_uInt16          GetLeadingFont();
 112     /** The same as above + additionally remove the given font from the formatting run*/
 113     sal_uInt16          RemoveLeadingFont();
 114
 115     // get data ---------------------------------------------------------------
 116
 117     /** Returns the character count of the string. */
 118     sal_uInt16   Len() const { return mnLen; }
 119     /** Returns true, if the string is empty. */
 120     bool         IsEmpty() const { return mnLen == 0; }
 121     /** Returns true, if the string contains line breaks. */
 122     bool         IsWrapped() const { return mbWrapped; }
 123     /** Returns true, if this string is equal to the passed string. */
 124     bool                IsEqual( const XclExpString& rCmp ) const;
 125     /** Returns true, if this string is less than the passed string. */
 126     bool                IsLessThan( const XclExpString& rCmp ) const;
 127
 128     /** Returns true, if the string contains formatting information. */
 129     bool         IsRich() const { return !maFormats.empty(); }
 130     /** Returns the current count of formatting runs for rich strings. */
 131     sal_uInt16          GetFormatsCount() const;
 132     /** Returns the vector with all formatting runs. */
 133     const XclFormatRunVec& GetFormats() const { return maFormats; }
 134
 135     /** Returns the current string flags field to export. */
 136     sal_uInt8           GetFlagField() const;
 137     /** Returns the byte count the header will take on export. */
 138     sal_uInt16          GetHeaderSize() const;
 139     /** Returns the byte count the character buffer will take on export. */
 140     std::size_t         GetBufferSize() const;
 141     /** Returns the byte count the whole string will take on export. */
 142     std::size_t         GetSize() const;
 143
 144     /** Returns the specified character from the (already encoded) string. */
 145     sal_uInt16          GetChar( sal_uInt16 nCharIdx ) const;
 146     /** Returns a hash value for the string. */
 147     sal_uInt16          GetHash() const;
 148
 149     const ScfUInt16Vec& GetUnicodeBuffer() const { return maUniBuffer; }
 150
 151     // streaming --------------------------------------------------------------
 152
 153     /** Writes the string length field (1 byte or 2 bytes). */
 154     void                WriteLenField( XclExpStream& rStrm ) const;
 155     /** Writes the string flags field (1 byte). */
 156     void                WriteFlagField( XclExpStream& rStrm ) const;
 157     /** Writes 8-bit or 16-bit length field and string flags field. */
 158     void                WriteHeader( XclExpStream& rStrm ) const;
 159     /** Writes the raw character buffer. */
 160     void                WriteBuffer( XclExpStream& rStrm ) const;
 161     /** Writes the raw formatting run buffer. */
 162     void                WriteFormats( XclExpStream& rStrm, bool bWriteSize = false ) const;
 163     /** Writes the complete Unicode string. */
 164     void                Write( XclExpStream& rStrm ) const;
 165
 166     /** Writes the string header to memory. */
 167     void                WriteHeaderToMem( sal_uInt8* pnMem ) const;
 168     /** Writes the raw character buffer to memory (8-bit or 16-bit little-endian). */
 169     void                WriteBufferToMem( sal_uInt8* pnMem ) const;
 170     /** Writes the entire string to memory. */
 171     void                WriteToMem( sal_uInt8* pnMem ) const;
 172
 173     void                WriteXml( XclExpXmlStream& rStrm ) const;
 174
 175 private:
 176     /** Returns true, if the flag field should be written. */
 177     bool                IsWriteFlags() const;
 178     /** Returns true, if the formatting run vector should be written. */
 179     bool                IsWriteFormats() const;
 180
 181     /** Sets the string length but regards the limit given in mnMaxLen. */
 182     void                SetStrLen( sal_Int32 nNewLen );
 183     /** Inserts the passed character array into the internal character buffer.
 184         @param nBegin  First index in internal buffer to fill.
 185         @param nLen  Number of characters to insert. */
 186     void                CharsToBuffer( const sal_Unicode* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 187     /** Inserts the passed character array into the internal character buffer.
 188         @param nBegin  First index in internal buffer to fill.
 189         @param nLen  Number of characters to insert. */
 190     void                CharsToBuffer( const char* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 191
 192     /** Initializes flags, string length, and resizes character buffer.
 193         @param nFlags  Modifiers for string export.
 194         @param nCurrLen  The requested number of characters for the string.
 195         @param nMaxLen  The maximum length allowed of the resulting string.
 196         @param bBiff8  true = BIFF8 Unicode string; false = BIFF2-BIFF7 byte string. */
 197     void                Init( sal_Int32 nCurrLen, XclStrFlags nFlags, sal_uInt16 nMaxLen, bool bBiff8 );
 198     /** Creates the character buffer from the given Unicode array.
 199         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 200         @param nFlags  Modifiers for string export.
 201         @param nCurrLen  The real count of characters contained in the passed buffer.
 202         @param nMaxLen  The maximum length allowed of the resulting string. */
 203     void                Build(
 204                             const sal_Unicode* pcSource, sal_Int32 nCurrLen,
 205                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 206     /** Creates the character buffer from the given character array.
 207         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 208         @param nFlags  Modifiers for string export.
 209         @param nCurrLen  The real count of characters contained in the passed buffer.
 210         @param nMaxLen  The maximum length allowed of the resulting string. */
 211     void                Build(
 212                             const char* pcSource, sal_Int32 nCurrLen,
 213                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 214
 215     /** Initializes string length and resizes character buffers for appending operation.
 216         @param nAddLen  The number of characters to be appended. */
 217     void                InitAppend( sal_Int32 nAddLen );
 218     /** Appends the given Unicode array to the character buffer.
 219         @param pcSource  The source character buffer. Trailing NUL character is not necessary. */
 220     void                BuildAppend( std::u16string_view );
 221     /** Appends the given character array to the character buffer.
 222         @param pcSource  The source character buffer. Trailing NUL character is not necessary. */
 223     void                BuildAppend( std::string_view );
 224
 225     /** Initializes write process on stream. */
 226     void                PrepareWrite( XclExpStream& rStrm, sal_uInt16 nBytes ) const;
 227
 228 private:
 229     ScfUInt16Vec        maUniBuffer;    /// The Unicode character buffer.
 230     ScfUInt8Vec         maCharBuffer;   /// The byte character buffer.
 231     XclFormatRunVec     maFormats;      /// All formatting runs.
 232     sal_uInt16          mnLen;          /// Character count to export.
 233     sal_uInt16          mnMaxLen;       /// Maximum allowed number of characters.
 234     bool                mbIsBiff8;      /// true = BIFF8 Unicode string, false = BIFF2-7 bytestring.
 235     bool                mbIsUnicode;    /// true, if at least one character is >0xFF.
 236     bool                mb8BitLen;      /// true = write 8-bit string length; false = 16-bit.
 237     bool                mbSmartFlags;   /// true = omit flags on empty string; false = always write flags.
 238     bool                mbSkipFormats;  /// true = skip formats on export; false = write complete formatted string.
 239     bool                mbWrapped;      /// true = text contains several paragraphs.
 240     bool                mbSkipHeader;   /// true = skip length and flags when writing string bytes.
 241 };
 242
 243 inline bool operator==( const XclExpString& rLeft, const XclExpString& rRight )
 244 {
 245     return rLeft.IsEqual( rRight );
 246 }
 247
 248 inline bool operator!=( const XclExpString& rLeft, const XclExpString& rRight )
 249 {
 250     return !(rLeft == rRight);
 251 }
 252
 253 inline bool operator<( const XclExpString& rLeft, const XclExpString& rRight )
 254 {
 255     return rLeft.IsLessThan( rRight );
 256 }
 257
 258 inline XclExpStream& operator<<( XclExpStream& rStrm, const XclExpString& rString )
 259 {
 260     rString.Write( rStrm );
 261     return rStrm;
 262 }
 263
 264 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */