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         HasNewline() const { return mbHasNewline; }
 123
 124     /** Returns true, if multiple paragraphs are displayed without any wrapping **/
 125     bool IsSingleLineForMultipleParagraphs() const { return mbSingleLineForMultipleParagraphs; }
 126     void SetSingleLineForMultipleParagraphs(bool bSet) { mbSingleLineForMultipleParagraphs = bSet; }
 127
 128     /** Returns true, if this string is equal to the passed string. */
 129     bool                IsEqual( const XclExpString& rCmp ) const;
 130     /** Returns true, if this string is less than the passed string. */
 131     bool                IsLessThan( const XclExpString& rCmp ) const;
 132
 133     /** Returns true, if the string contains formatting information. */
 134     bool         IsRich() const { return !maFormats.empty(); }
 135     /** Returns the current count of formatting runs for rich strings. */
 136     sal_uInt16          GetFormatsCount() const;
 137     /** Returns the vector with all formatting runs. */
 138     const XclFormatRunVec& GetFormats() const { return maFormats; }
 139
 140     /** Returns the current string flags field to export. */
 141     sal_uInt8           GetFlagField() const;
 142     /** Returns the byte count the header will take on export. */
 143     sal_uInt16          GetHeaderSize() const;
 144     /** Returns the byte count the character buffer will take on export. */
 145     std::size_t         GetBufferSize() const;
 146     /** Returns the byte count the whole string will take on export. */
 147     std::size_t         GetSize() const;
 148
 149     /** Returns the specified character from the (already encoded) string. */
 150     sal_uInt16          GetChar( sal_uInt16 nCharIdx ) const;
 151     /** Returns a hash value for the string. */
 152     sal_uInt16          GetHash() const;
 153
 154     const ScfUInt16Vec& GetUnicodeBuffer() const { return maUniBuffer; }
 155
 156     // streaming --------------------------------------------------------------
 157
 158     /** Writes the string length field (1 byte or 2 bytes). */
 159     void                WriteLenField( XclExpStream& rStrm ) const;
 160     /** Writes the string flags field (1 byte). */
 161     void                WriteFlagField( XclExpStream& rStrm ) const;
 162     /** Writes 8-bit or 16-bit length field and string flags field. */
 163     void                WriteHeader( XclExpStream& rStrm ) const;
 164     /** Writes the raw character buffer. */
 165     void                WriteBuffer( XclExpStream& rStrm ) const;
 166     /** Writes the raw formatting run buffer. */
 167     void                WriteFormats( XclExpStream& rStrm, bool bWriteSize = false ) const;
 168     /** Writes the complete Unicode string. */
 169     void                Write( XclExpStream& rStrm ) const;
 170
 171     /** Writes the string header to memory. */
 172     void                WriteHeaderToMem( sal_uInt8* pnMem ) const;
 173     /** Writes the raw character buffer to memory (8-bit or 16-bit little-endian). */
 174     void                WriteBufferToMem( sal_uInt8* pnMem ) const;
 175     /** Writes the entire string to memory. */
 176     void                WriteToMem( sal_uInt8* pnMem ) const;
 177
 178     void                WriteXml( XclExpXmlStream& rStrm ) const;
 179
 180 private:
 181     /** Returns true, if the flag field should be written. */
 182     bool                IsWriteFlags() const;
 183     /** Returns true, if the formatting run vector should be written. */
 184     bool                IsWriteFormats() const;
 185
 186     /** Sets the string length but regards the limit given in mnMaxLen. */
 187     void                SetStrLen( sal_Int32 nNewLen );
 188     /** Inserts the passed character array into the internal character buffer.
 189         @param nBegin  First index in internal buffer to fill.
 190         @param nLen  Number of characters to insert. */
 191     void                CharsToBuffer( const sal_Unicode* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 192     /** Inserts the passed character array into the internal character buffer.
 193         @param nBegin  First index in internal buffer to fill.
 194         @param nLen  Number of characters to insert. */
 195     void                CharsToBuffer( const char* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 196
 197     /** Initializes flags, string length, and resizes character buffer.
 198         @param nFlags  Modifiers for string export.
 199         @param nCurrLen  The requested number of characters for the string.
 200         @param nMaxLen  The maximum length allowed of the resulting string.
 201         @param bBiff8  true = BIFF8 Unicode string; false = BIFF2-BIFF7 byte string. */
 202     void                Init( sal_Int32 nCurrLen, XclStrFlags nFlags, sal_uInt16 nMaxLen, bool bBiff8 );
 203     /** Creates the character buffer from the given Unicode array.
 204         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 205         @param nFlags  Modifiers for string export.
 206         @param nCurrLen  The real count of characters contained in the passed buffer.
 207         @param nMaxLen  The maximum length allowed of the resulting string. */
 208     void                Build(
 209                             const sal_Unicode* pcSource, sal_Int32 nCurrLen,
 210                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 211     /** Creates the character buffer from the given character array.
 212         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 213         @param nFlags  Modifiers for string export.
 214         @param nCurrLen  The real count of characters contained in the passed buffer.
 215         @param nMaxLen  The maximum length allowed of the resulting string. */
 216     void                Build(
 217                             const char* pcSource, sal_Int32 nCurrLen,
 218                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 219
 220     /** Initializes string length and resizes character buffers for appending operation.
 221         @param nAddLen  The number of characters to be appended. */
 222     void                InitAppend( sal_Int32 nAddLen );
 223     /** Appends the given Unicode array to the character buffer.
 224         @param pcSource  The source character buffer. Trailing NUL character is not necessary. */
 225     void                BuildAppend( std::u16string_view );
 226     /** Appends the given character array to the character buffer.
 227         @param pcSource  The source character buffer. Trailing NUL character is not necessary. */
 228     void                BuildAppend( std::string_view );
 229
 230     /** Initializes write process on stream. */
 231     void                PrepareWrite( XclExpStream& rStrm, sal_uInt16 nBytes ) const;
 232
 233 private:
 234     ScfUInt16Vec        maUniBuffer;    /// The Unicode character buffer.
 235     ScfUInt8Vec         maCharBuffer;   /// The byte character buffer.
 236     XclFormatRunVec     maFormats;      /// All formatting runs.
 237     sal_uInt16          mnLen;          /// Character count to export.
 238     sal_uInt16          mnMaxLen;       /// Maximum allowed number of characters.
 239     bool                mbIsBiff8;      /// true = BIFF8 Unicode string, false = BIFF2-7 bytestring.
 240     bool                mbIsUnicode;    /// true, if at least one character is >0xFF.
 241     bool                mb8BitLen;      /// true = write 8-bit string length; false = 16-bit.
 242     bool                mbSmartFlags;   /// true = omit flags on empty string; false = always write flags.
 243     bool                mbSkipFormats;  /// true = skip formats on export; false = write complete formatted string.
 244     bool                mbHasNewline;   /// true = text contains several paragraphs.
 245     bool                mbSingleLineForMultipleParagraphs; /// true = several paragraphs displayed all on one line
 246     bool                mbSkipHeader;   /// true = skip length and flags when writing string bytes.
 247 };
 248
 249 inline bool operator==( const XclExpString& rLeft, const XclExpString& rRight )
 250 {
 251     return rLeft.IsEqual( rRight );
 252 }
 253
 254 inline bool operator!=( const XclExpString& rLeft, const XclExpString& rRight )
 255 {
 256     return !(rLeft == rRight);
 257 }
 258
 259 inline bool operator<( const XclExpString& rLeft, const XclExpString& rRight )
 260 {
 261     return rLeft.IsLessThan( rRight );
 262 }
 263
 264 inline XclExpStream& operator<<( XclExpStream& rStrm, const XclExpString& rString )
 265 {
 266     rString.Write( rStrm );
 267     return rStrm;
 268 }
 269
 270 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */