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