Inheritance diagram for Text:
RFC 2822 divides all header fields into two categories: structured and unstructured. Structured header fields include fields such as "To", "From", and "Date", which have a specified syntax. Unstructured header fields include fields such as "Subject", which have no specified syntax. Hunny MIME++ provides the Text class to represent unstructured header field bodies that contain text.
Hunny MIME++ does not use the Text class for all unstructured header fields, because it is not necessary. The Text class actually parses the field body for encoded words, as discussed below, and decodes any transfer encoding and character encoding.
Header fields in messages that conform to RFC 2822 may contain only 7-bit ASCII characters. RFC 2047, part of the MIME standard, describes a method for encoding non-ASCII characters into 7-bit ASCII characters so that they may be inserted into message header fields. The method encodes text into encoded words. Each encoded word identifies a character encoding (that is, a charset) and a transfer encoding, and contains the text encoded into 7-bit ASCII characters.
In Hunny MIME++, Text is a container for EncodedWord objects, and it provides several member functions to manage the encoded words it contains.
If you are not interested in working with the encoded words, you may call getString() and setString() to get and set the literal text of the field body. Or, you may use the convenience functions utf8Text() and setUtf8Text() to get and set the text from a UTF-8 string. If you need to set text from a UTF-8 string and you require an external character encoding other than UTF-8, you may use the convenience function setUtf8Text(const String&,const String&).
To create a text field body that contains encoded words, create one or more EncodedWord objects and add them, in order, to the Text object. When you call the assemble() member function, MIME++ creates or updates the text field body string representation from the contained EncodedWord objects. (Note that you normally call the assemble() member function at the root of a tree of Node objects.)
Public Member Functions | |
| Text () | |
| Default constructor. | |
| Text (const Text &other) | |
| Copy constructor. | |
| Text (const String &str, Node *parent=0) | |
| Constructor that takes an initial string and parent node. | |
| virtual | ~Text () |
| Destructor. | |
| const Text & | operator= (const Text &other) |
| Assignment operator. | |
| virtual void | parse () |
| Parses the string representation. | |
| virtual void | assemble () |
| Assembles the string representation. | |
| virtual Node * | clone () const |
| Creates a copy of this object. | |
| const String & | utf8Text () const |
| Gets the text as a UTF-8 string. | |
| const String & | charset () const |
| Gets the charset identifier for the text content. | |
| void | setUtf8Text (const String &utf8str) |
| Sets the text from a UTF-8 string. | |
| void | setUtf8Text (const String &utf8str, const String &charset) |
| Sets the text from a UTF-8 string with charset hint. | |
| int | numEncodedWords () const |
| Gets the number of encoded words in the list. | |
| void | addEncodedWord (EncodedWord *word) |
| Adds an encoded word to the end of the list. | |
| void | deleteAllEncodedWords () |
| Deletes all encoded words in the list. | |
| EncodedWord & | encodedWordAt (int index) const |
| Gets the encoded word at the specified position in the list. | |
| void | insertEncodedWordAt (int index, EncodedWord *word) |
| Inserts an encoded word at the specified position in the list. | |
| EncodedWord * | removeEncodedWordAt (int index) |
| Removes the encoded word at the specified position in the list. | |
Static Public Member Functions | |
| Text * | newText () |
| Creates a new instance. | |
Static Public Attributes | |
| Text *(* | sNewText )() |
| Provides a class factory hook. | |
Protected Member Functions | |
| void | _copyEncodedWords (const Text &text) |
| Copies all encoded words from another list. | |
| void | _addEncodedWord (EncodedWord *word) |
| Adds an encoded word to the end of the list. | |
| void | _insertEncodedWordAt (int index, EncodedWord *word) |
| Inserts an encoded word at the specified position in the list. | |
| EncodedWord * | _removeEncodedWordAt (int index) |
| Removes the encoded word at the specified position in the list. | |
| void | _deleteAllEncodedWords () |
| Deletes all encoded words in the list. | |
|
|
This constructor sets the Text object's string representation to the empty string and sets its parent node to NULL. |
|
|
This constructor performs a deep copy of its argument. The parent node of the new Text object is set to NULL.
|
|
||||||||||||
|
This constructor sets the Text object's string representation to str and sets its parent node to parent. Normally, you call the virtual function parse() immediately after this constructor to create the broken-down representation.
|
|
|
Destructor |
|
|
Same as addEncodedWord(), but does not set the is-modified flag.
|
|
|
Copies the list of EncodedWord objects from other. Assumes the list in this Text object is emtpy. Does not set the is-modified flag.
|
|
|
Same as deleteAllEncodedWords(), but does not set the is-modified flag.
|
|
||||||||||||
|
Same as insertEncodedWordAt(), but does not set the is-modified flag.
|
|
|
Same as removeEncodedWordAt(), but does not set the is-modified flag.
|
|
|
Adds word to the end of the encoded word list. The Text destructor deletes the EncodedWord objects in the list.
|
|
|
This virtual function, inherited from Node, executes the assemble operation for Text objects. The assemble operation creates or updates the string representation from the broken-down representation. For Text objects, the assemble operation builds the string representation from the list of contained EncodedWord objects. Before it builds the string representation for the Text object, this function first calls the assemble() member function of each EncodedWord object in its list. You should call this member function after you set or modify any of the contained EncodedWord objects, and before you retrieve the string representation. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Gets the charset identifier for the text content. To find the charset identifier, this convenience function finds the first encoded word that specifies a charset other than US-ASCII, then gets the charset from that encoded word.
|
|
|
This virtual function, inherited from Node, creates a new Text object that has the same value as this Text object. The parent node of the new Text object is set to NULL.
Reimplemented from FieldBody. |
|
|
Removes and deletes all EncodedWord objects in the encoded word list. |
|
|
Gets the EncodedWord object at position index in the encoded word list. The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index < numEncodedWords().
|
|
||||||||||||
|
Inserts word into the encoded word list at position index. If index is zero, then the function inserts word into the first position in the list. If index equals numEncodedWords(), then the function inserts word into the last position in the list. If index is less than numEncodedWords(), then the function moves the EncodedWord objects at position index or greater to a higher position in the list. The Text destructor deletes the EncodedWord objects in the list. The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index <= numEncodedWords().
|
|
|
Creates a new Text object. If the static data member sNewText is NULL, this member function creates a new Text object and returns it. Otherwise, newText() calls the user-supplied function that sNewText points to and returns the object created by that function.
|
|
|
Gets the number of EncodedWord objects in the encoded word list.
|
|
|
Performs a deep copy of its argument. The parent node of this Text object is not changed.
|
|
|
This virtual function, inherited from Node, executes the parse operation for Text objects. The parse operation creates or updates the broken-down representation from the string representation. For Text objects, the parse operation parses the string representation to create a list of EncodedWord objects. This member function also calls the parse() member function of each EncodedWord object in its list. You should call this member function after you set or modify the string representation, and before you access any of the contained EncodedWord objects. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Removes the EncodedWord object at position index from the encoded word list and returns it. If index is less than numEncodedWords()-1, then the function moves the EncodedWord objects at position (index + 1) or greater to a lower position in the list. The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index < numEncodedWords().
|
|
||||||||||||
|
Sets the text from a UTF-8 string, with a charset hint. This convenience function sets the content of the Text object from a UTF-8 string. The function converts the Unicode characters to the specified character encoding (charset), then creates and adds encoded words using either the B transfer encoding (base64) or Q transfer encoding (a modified form of quoted-printable). As a special case, if all the characters in the string have code points less than 128 (that is, ASCII characters), then the function adds the string unchanged and does not create encoded words. The library uses the Q transfer encoding for all 8-bit character sets, and the B transfer encoding for all multi-byte character encodings. There are two exceptions: If the charset is UTF-8, then the library chooses between the Q and B transfer encodings, whichever yields the shortest length. If the charset is UTF-7, then the library uses the Q encoding. Reference: The encoding of unstructured text using encoded words is described in RFC 2047. This function sets the is-modified flag.
Note: You do not need to call
|
|
|
Sets the text from a UTF-8 string. This convenience function creates and adds encoded words to the Text object. If all the characters in the Unicode string have code points less than 128 (that is, ASCII characters), then the function adds the string unchanged -- no encoded words are created. Otherwise, if all the characters have code points less than 256, then the function creates encoded words that contain ISO-8859-1 characters encoded with the Q transfer encoding. If there are any characters that have code points greater than or equal to 256, then the function encodes the characters with the UTF-8 encoding and creates encoded words with either the B or Q transfer encoding, whichever yields the shortest length. If you require an external encoding other than ISO-8859-1 or UTF-8, then you may use the member function setUtf8Text(const String&,const String&), which allows you to specify a particular encoding. This function sets the is-modified flag.
Note: You do not need to call
|
|
|
Gets the text as a UTF-8 string. This convenience function decodes all the encoded words and converts all the characters to Unicode characters.
|
|
|
If sNewText is not NULL, it must point to a user-supplied function that returns a new instance of a subclass of Text.
|
Copyright © 2001-2007 Hunny Software, Inc. All rights reserved.