sc/source/filter/inc/xestring.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: xestring.hxx,v $
  10  * $Revision: 1.11.32.2 $
  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 SC_XESTRING_HXX
  32 #define SC_XESTRING_HXX
  33
  34 #include "xlstring.hxx"
  35
  36 // ============================================================================
  37
  38 class ScEditCell;
  39 class ScPatternAttr;
  40 class EditTextObject;
  41 class XclExpStream;
  42 class XclExpXmlStream;
  43
  44 /** This class stores an unformatted or formatted string for Excel export.
  45
  46     The class supports two completely different types of Excel strings:
  47     1)  BIFF2-BIFF7 byte strings: The text is encoded as a 8-bit character
  48         array. The strings cannot contain any character formatting.
  49     2)  BIFF8 Unicode strings: The text may be stored as UCS-2 character array,
  50         or compressed to an 8-bit array, if all characters are less than
  51         U+0100. Unicode strings may contain a formatting array, that specifies
  52         the used FONT record for different ranges of characters.
  53
  54     The class provides full support for NUL characters in strings. On
  55     construction or assignment the passed flags specify the behaviour of the
  56     string while it is written to a stream (the 'Write' functions and
  57     'operator<<').
  58  */
  59 class XclExpString
  60 {
  61 public:
  62     // constructors -----------------------------------------------------------
  63
  64     /** Constructs an empty BIFF8 Unicode string.
  65         @param nFlags  Modifiers for string export.
  66         @param nMaxLen  The maximum number of characters to store in this string. */
  67     explicit            XclExpString(
  68                             XclStrFlags nFlags = EXC_STR_DEFAULT,
  69                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  70
  71     /** Constructs an unformatted BIFF8 Unicode string.
  72         @param nFlags  Modifiers for string export.
  73         @param nMaxLen  The maximum number of characters to store in this string. */
  74     explicit            XclExpString(
  75                             const String& rString,
  76                             XclStrFlags nFlags = EXC_STR_DEFAULT,
  77                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  78     /** Constructs an unformatted BIFF8 Unicode string.
  79         @param nFlags  Modifiers for string export.
  80         @param nMaxLen  The maximum number of characters to store in this string. */
  81     explicit            XclExpString(
  82                             const ::rtl::OUString& rString,
  83                             XclStrFlags nFlags = EXC_STR_DEFAULT,
  84                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  85 //UNUSED2008-05  /** Constructs a formatted BIFF8 Unicode string.
  86 //UNUSED2008-05      @param rFormats  The formatting runs.
  87 //UNUSED2008-05      @param nFlags  Modifiers for string export.
  88 //UNUSED2008-05      @param nMaxLen  The maximum number of characters to store in this string. */
  89 //UNUSED2008-05  explicit            XclExpString(
  90 //UNUSED2008-05                          const String& rString,
  91 //UNUSED2008-05                          const XclFormatRunVec& rFormats,
  92 //UNUSED2008-05                          XclStrFlags nFlags = EXC_STR_DEFAULT,
  93 //UNUSED2008-05                          sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
  94 //UNUSED2008-05
  95 //UNUSED2008-05  /** Constructs a formatted BIFF8 Unicode string.
  96 //UNUSED2008-05      @param rFormats  The formatting runs.
  97 //UNUSED2008-05      @param nFlags  Modifiers for string export.
  98 //UNUSED2008-05      @param nMaxLen  The maximum number of characters to store in this string. */
  99 //UNUSED2008-05  explicit            XclExpString(
 100 //UNUSED2008-05                          const ::rtl::OUString& rString,
 101 //UNUSED2008-05                          const XclFormatRunVec& rFormats,
 102 //UNUSED2008-05                          XclStrFlags nFlags = EXC_STR_DEFAULT,
 103 //UNUSED2008-05                          sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 104
 105     // assign -----------------------------------------------------------------
 106
 107     /** Assigns an unformatted string, converts this object to a BIFF8 Unicode string.
 108         @param nFlags  Modifiers for string export.
 109         @param nMaxLen  The maximum number of characters to store in this string. */
 110     void                Assign(
 111                             const String& rString,
 112                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 113                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 114     /** Assigns a formatted string, converts this object to a BIFF8 Unicode string.
 115         @param rFormats  The formatting runs.
 116         @param nFlags  Modifiers for string export.
 117         @param nMaxLen  The maximum number of characters to store in this string. */
 118     void                Assign(
 119                             const String& rString,
 120                             const XclFormatRunVec& rFormats,
 121                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 122                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 123     /** Assigns an unformatted string, converts this object to a BIFF8 Unicode string.
 124         @param nFlags  Modifiers for string export.
 125         @param nMaxLen  The maximum number of characters to store in this string. */
 126     void                Assign(
 127                             const ::rtl::OUString& rString,
 128                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 129                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 130     /** Assigns a formatted string, converts this object to a BIFF8 Unicode string.
 131         @param rFormats  The formatting runs.
 132         @param nFlags  Modifiers for string export.
 133         @param nMaxLen  The maximum number of characters to store in this string. */
 134     void                Assign(
 135                             const ::rtl::OUString& rString,
 136                             const XclFormatRunVec& rFormats,
 137                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 138                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 139     /** Assigns a Unicode character, converts this object to a BIFF8 Unicode string.
 140         @param nFlags  Modifiers for string export.
 141         @param nMaxLen  The maximum number of characters to store in this string (for appending). */
 142     void                Assign(
 143                             sal_Unicode cChar,
 144                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 145                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 146
 147     /** Assigns an unformatted string, converts this object to a BIFF2-BIFF7 byte string.
 148         @param nFlags  Modifiers for string export.
 149         @param nMaxLen  The maximum number of characters to store in this string. */
 150     void                AssignByte(
 151                             const String& rString,
 152                             rtl_TextEncoding eTextEnc,
 153                             XclStrFlags nFlags = EXC_STR_DEFAULT,
 154                             sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 155
 156 //UNUSED2008-05  /** Assigns a character, converts this object to a BIFF2-BIFF7 byte string.
 157 //UNUSED2008-05      @param nFlags  Modifiers for string export.
 158 //UNUSED2008-05      @param nMaxLen  The maximum number of characters to store in this string (for appending). */
 159 //UNUSED2008-05  void                AssignByte(
 160 //UNUSED2008-05                          sal_Unicode cChar,
 161 //UNUSED2008-05                          rtl_TextEncoding eTextEnc,
 162 //UNUSED2008-05                          XclStrFlags nFlags = EXC_STR_DEFAULT,
 163 //UNUSED2008-05                          sal_uInt16 nMaxLen = EXC_STR_MAXLEN );
 164
 165     // append -----------------------------------------------------------------
 166
 167     /** Appends a string. Uses the string flags used in constructor or last Assign().
 168         @descr  This object must be a BIFF8 Unicode string. */
 169     void                Append( const String& rString );
 170
 171 //UNUSED2008-05  /** Appends a string. Uses the string flags used in constructor or last Assign().
 172 //UNUSED2008-05      @descr  This object must be a BIFF8 Unicode string. */
 173 //UNUSED2008-05  void                Append( const ::rtl::OUString& rString );
 174 //UNUSED2008-05  /** Appends a character. Uses the string flags used in constructor or last Assign().
 175 //UNUSED2008-05      @descr  This object must be a BIFF8 Unicode string. */
 176 //UNUSED2008-05  void                Append( sal_Unicode cChar );
 177
 178     /** Appends a string. Uses the string flags used in constructor or last Assign().
 179         @descr  This object must be a BIFF2-BIFF7 byte string. */
 180     void                AppendByte( const String& rString, rtl_TextEncoding eTextEnc );
 181     /** Appends a character. Uses the string flags used in constructor or last Assign().
 182         @descr  This object must be a BIFF2-BIFF7 byte string. */
 183     void                AppendByte( sal_Unicode cChar, rtl_TextEncoding eTextEnc );
 184
 185     // formatting runs --------------------------------------------------------
 186
 187     /** Sets new formatting runs for the current text. */
 188     void                SetFormats( const XclFormatRunVec& rFormats );
 189     /** Appends a formatting run. nChar must be greater than last contained character index. */
 190     void                AppendFormat( sal_uInt16 nChar, sal_uInt16 nFontIdx, bool bDropDuplicate = true );
 191     /** Appends a trailing formatting run with the passed font index. */
 192     void                AppendTrailingFormat( sal_uInt16 nFontIdx );
 193     /** Removes formatting runs at the end, if the string contains too much. */
 194     void                LimitFormatCount( sal_uInt16 nMaxCount );
 195     /** Removes and returns the font index for the first char from the formatting runs, otherwise EXC_FONT_NOTFOUND. */
 196     sal_uInt16          RemoveLeadingFont();
 197
 198     // get data ---------------------------------------------------------------
 199
 200     /** Returns the character count of the string. */
 201     inline sal_uInt16   Len() const { return mnLen; }
 202     /** Returns true, if the string is empty. */
 203     inline bool         IsEmpty() const { return mnLen == 0; }
 204     /** Returns true, if the string contains line breaks. */
 205     inline bool         IsWrapped() const { return mbWrapped; }
 206     /** Returns true, if this string is equal to the passed string. */
 207     bool                IsEqual( const XclExpString& rCmp ) const;
 208     /** Returns true, if this string is less than the passed string. */
 209     bool                IsLessThan( const XclExpString& rCmp ) const;
 210
 211     /** Returns true, if the string contains formatting information. */
 212     inline bool         IsRich() const { return !maFormats.empty(); }
 213     /** Returns the current count of formatting runs for rich strings. */
 214     sal_uInt16          GetFormatsCount() const;
 215     /** Returns the vector with all formatting runs. */
 216     inline const XclFormatRunVec& GetFormats() const { return maFormats; }
 217
 218     /** Returns the current string flags field to export. */
 219     sal_uInt8           GetFlagField() const;
 220     /** Returns the byte count the header will take on export. */
 221     sal_uInt16          GetHeaderSize() const;
 222     /** Returns the byte count the character buffer will take on export. */
 223     sal_Size            GetBufferSize() const;
 224     /** Returns the byte count the whole string will take on export. */
 225     sal_Size            GetSize() const;
 226
 227     /** Returns the specified character from the (already encoded) string. */
 228     sal_uInt16          GetChar( sal_uInt16 nCharIdx ) const;
 229     /** Returns a hash value for the string. */
 230     sal_uInt16          GetHash() const;
 231
 232     const ScfUInt16Vec& GetUnicodeBuffer() const { return maUniBuffer; }
 233
 234     // streaming --------------------------------------------------------------
 235
 236     /** Writes the string length field (1 byte or 2 bytes). */
 237     void                WriteLenField( XclExpStream& rStrm ) const;
 238     /** Writes the string flags field (1 byte). */
 239     void                WriteFlagField( XclExpStream& rStrm ) const;
 240     /** Writes 8-bit or 16-bit length field and string flags field. */
 241     void                WriteHeader( XclExpStream& rStrm ) const;
 242     /** Writes the raw character buffer. */
 243     void                WriteBuffer( XclExpStream& rStrm ) const;
 244     /** Writes the raw formatting run buffer. */
 245     void                WriteFormats( XclExpStream& rStrm, bool bWriteSize = false ) const;
 246     /** Writes the complete Unicode string. */
 247     void                Write( XclExpStream& rStrm ) const;
 248
 249     /** Writes the string header to memory. */
 250     void                WriteHeaderToMem( sal_uInt8* pnMem ) const;
 251     /** Writes the raw character buffer to memory (8-bit or 16-bit little-endian). */
 252     void                WriteBufferToMem( sal_uInt8* pnMem ) const;
 253     /** Writes the entire string to memory. */
 254     void                WriteToMem( sal_uInt8* pnMem ) const;
 255
 256     void                WriteXml( XclExpXmlStream& rStrm ) const;
 257
 258     // ------------------------------------------------------------------------
 259 private:
 260     /** Returns true, if the flag field should be written. */
 261     bool                IsWriteFlags() const;
 262     /** Returns true, if the formatting run vector should be written. */
 263     bool                IsWriteFormats() const;
 264
 265     /** Sets the string length but regards the limit given in mnMaxLen. */
 266     void                SetStrLen( sal_Int32 nNewLen );
 267     /** Inserts the passed character array into the internal character buffer.
 268         @param nBegin  First index in internal buffer to fill.
 269         @param nLen  Number of characters to insert. */
 270     void                CharsToBuffer( const sal_Unicode* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 271     /** Inserts the passed character array into the internal character buffer.
 272         @param nBegin  First index in internal buffer to fill.
 273         @param nLen  Number of characters to insert. */
 274     void                CharsToBuffer( const sal_Char* pcSource, sal_Int32 nBegin, sal_Int32 nLen );
 275
 276     /** Initializes flags, string length, and resizes character buffer.
 277         @param nFlags  Modifiers for string export.
 278         @param nCurrLen  The requested number of characters for the string.
 279         @param nMaxLen  The maximum length allowed of the resulting string.
 280         @param bBiff8  true = BIFF8 Unicode string; false = BIFF2-BIFF7 byte string. */
 281     void                Init( sal_Int32 nCurrLen, XclStrFlags nFlags, sal_uInt16 nMaxLen, bool bBiff8 );
 282     /** Creates the character buffer from the given Unicode array.
 283         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 284         @param nFlags  Modifiers for string export.
 285         @param nCurrLen  The real count of characters contained in the passed buffer.
 286         @param nMaxLen  The maximum length allowed of the resulting string. */
 287     void                Build(
 288                             const sal_Unicode* pcSource, sal_Int32 nCurrLen,
 289                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 290     /** Creates the character buffer from the given character array.
 291         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 292         @param nFlags  Modifiers for string export.
 293         @param nCurrLen  The real count of characters contained in the passed buffer.
 294         @param nMaxLen  The maximum length allowed of the resulting string. */
 295     void                Build(
 296                             const sal_Char* pcSource, sal_Int32 nCurrLen,
 297                             XclStrFlags nFlags, sal_uInt16 nMaxLen );
 298
 299     /** Initializes string length and resizes character buffers for appending operation.
 300         @param nAddLen  The number of characters to be appended. */
 301     void                InitAppend( sal_Int32 nAddLen );
 302     /** Appends the given Unicode array to the character buffer.
 303         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 304         @param nAddLen  The real count of characters contained in the passed buffer. */
 305     void                BuildAppend( const sal_Unicode* pcSource, sal_Int32 nAddLen );
 306     /** Appends the given character array to the character buffer.
 307         @param pcSource  The source character buffer. Trailing NUL character is not necessary.
 308         @param nAddLen  The real count of characters contained in the passed buffer. */
 309     void                BuildAppend( const sal_Char* pcSource, sal_Int32 nAddLen );
 310
 311     /** Initializes write process on stream. */
 312     void                PrepareWrite( XclExpStream& rStrm, sal_uInt16 nBytes ) const;
 313
 314 private:
 315     ScfUInt16Vec        maUniBuffer;    /// The Unicode character buffer.
 316     ScfUInt8Vec         maCharBuffer;   /// The byte character buffer.
 317     XclFormatRunVec     maFormats;      /// All formatting runs.
 318     sal_uInt16          mnLen;          /// Character count to export.
 319     sal_uInt16          mnMaxLen;       /// Maximum allowed number of characters.
 320     bool                mbIsBiff8;      /// true = BIFF8 Unicode string, false = BIFF2-7 bytestring.
 321     bool                mbIsUnicode;    /// true, if at least one character is >0xFF.
 322     bool                mb8BitLen;      /// true = write 8-bit string length; false = 16-bit.
 323     bool                mbSmartFlags;   /// true = omit flags on empty string; false = always write flags.
 324     bool                mbSkipFormats;  /// true = skip formats on export; false = write complete formatted string.
 325     bool                mbWrapped;      /// true = text contains several paragraphs.
 326     bool                mbSkipHeader;   /// ture = skip length and flags when writing string bytes.
 327 };
 328
 329 inline bool operator==( const XclExpString& rLeft, const XclExpString& rRight )
 330 {
 331     return rLeft.IsEqual( rRight );
 332 }
 333
 334 inline bool operator!=( const XclExpString& rLeft, const XclExpString& rRight )
 335 {
 336     return !(rLeft == rRight);
 337 }
 338
 339 inline bool operator<( const XclExpString& rLeft, const XclExpString& rRight )
 340 {
 341     return rLeft.IsLessThan( rRight );
 342 }
 343
 344 inline XclExpStream& operator<<( XclExpStream& rStrm, const XclExpString& rString )
 345 {
 346     rString.Write( rStrm );
 347     return rStrm;
 348 }
 349
 350 // ============================================================================
 351
 352 #endif
 353