DwText Man Page

## NAME

DwText -- Class representing text in a RFC-822 header field-body

## SYNOPSIS

    class DW_CORE_EXPORT DwText : public DwFieldBody {

    public:

        DwText();
        DwText(const DwText& aText);
        DwText(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwText();
        const DwText& operator = (const DwText& aText);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        int NumEncodedWords() const;
        void AddEncodedWord(DwEncodedWord* aWord);
        void DeleteAllEncodedWords();
        DwEncodedWord& EncodedWordAt(int aIndex) const;
        void InsertEncodedWordAt(int aIndex, DwEncodedWord* aWord);
        DwEncodedWord* RemoveEncodedWordAt(int aIndex);
        static DwText* NewText(const DwString& aStr, DwMessageComponent* aParent);
        static DwText* (*sNewText)(const DwString&, DwMessageComponent*);

    public:

        virtual void PrintDebugInfo(DW_STD ostream& aStrm, int aDepth=0) const;
        virtual void CheckInvariants() const;

    protected:

        void _PrintDebugInfo(DW_STD ostream& aStrm) const;
    };

## DESCRIPTION

`DwText` represents an unstructured field body in a header field. It roughly corresponds to the text element of the BNF grammar defined in RFC-822.

If non-ASCII text is not a concern, you can get or set the entire text of the `DwText` object by using the inherited member functions `DwMessageComponent::AsString()` and `DwMessageComponent::FromString()`. However, `DwText` also supports non-ASCII text via the encoded words specified in RFC 2047. The encoded words are represented by objects of the class `DwEncodedWord`. `DwText` contains a list of `DwEncodedWord` objects and provides member functions to manage the list.

To create a text field body that contains encoded words, create one or more `DwEncodedWord` objects and add them, in order, to the `DwText` object. When the `Assemble()` method is called, the text field body is built from the contained `DwEncodedWord` objects. (Note that the `Assemble()` member function is normally not called directly, but is called by the parent `DwMessageComponent` object.) To create a text field body that contains no encoded words (it must contain only US-ASCII characters), use the inherited `DwMessageComponent::FromString()` member function.

Note: In the examples directory you can find code that demonstrates how to use `DwText` and `DwEncodedWord` classes to set non-ASCII text into the Subject header field of a message.

## Public Member Functions

DwText()
DwText(const DwText& aText)
DwText(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the `DwText` object's string representation to the empty string and sets its parent to NULL.

The second constructor is the copy constructor, which copies the string representation from `aText`. The parent of the new `DwText` object is set to NULL.

The third constructor copies `aStr` to the `DwText` object's string representation and sets `aParent` as its parent. The virtual member function `Parse()` should be called immediately after this constructor in order to parse the string representation. Unless it is NULL, `aParent` should point to an object of a class derived from `DwField`.

const DwText& operator = (const DwText& aText)

This is the assignment operator.

virtual void Parse()

This virtual member function is inherited from `DwMessageComponent`, where it is declared a pure virtual function. For a `DwText` object, this member function does nothing, since `DwText` represents an unstructured field body (like the Subject header field) that does not have a broken-down form.

Note, however, that this function should still be called consistently, since a subclass of `DwText` may implement a parse method.

This function clears the is-modified flag.

virtual void Assemble()

This virtual member function is inherited from `DwMessageComponent`, where it is declared a pure virtual function. For a `DwText` object, this member function does nothing, since `DwText` represents an unstructured field body (like the Subject header field) that does not have a broken-down form.

Note, however, that this function should still be called consistently, since a subclass of `DwText` may implement an assemble method.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

This virtual function, inherited from `DwMessageComponent`, creates a new `DwText` on the free store that has the same value as this `DwText` object. The basic idea is that of a ``virtual copy constructor.''

int NumEncodedWords() const

Returns the number of `DwEncodedWord` objects contained in this `DwText` object.

void AddEncodedWord(DwEncodedWord* aWord)

Appends a `DwEncodedWord` object to the list managed by this `DwText` object.

Any `DwEncodedWord` objects contained in a `DwText` object's list will be deleted by the `DwText` object's destructor.

void DeleteAllEncodedWords()

Removes and deletes all `DwEncodedWord` objects contained in this `DwText` object.

DwEncodedWord& EncodedWordAt(int aIndex) const

Returns the `DwEncodedWord` object at position `aIndex` in this `DwText` object's list.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumEncodedWords()`.

void InsertEncodedWordAt(int aIndex, DwEncodedWord* aWord)

Inserts `aWord` into the list of `DwEncodedWord` objects at the position given by `aIndex`. A value of zero for `aIndex` will insert `aWord` as the first one in the list; a value of `NumEncodedWords()` will insert it as the last one in the list. If `aIndex` is less than `NumEncodedWords()`, the `DwEncodedWord` objects at position `aIndex` or greater will be shifted down the list to make room to insert `aWord`.

Any `DwEncodedWord` objects contained in a `DwText` object's list will be deleted by the `DwText` object's destructor.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` <= `NumEncodedWords()`.

DwEncodedWord* RemoveEncodedWordAt(int aIndex)

Removes the `DwEncodedWord` object at position `aIndex` from the list and returns it. If `aIndex` is less than `NumEncodedWords()-1`, then any `DwEncodedWord` objects at a position greater than `aIndex` will be shifted up in the list after the requested `DwEncodedWord` is removed.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumEncodedWords()`.

static DwText* NewText(const DwString& aStr, DwMessageComponent* aParent)

Creates a new `DwText` object on the free store. If the static data member `sNewText` is NULL, this member function will create a new `DwText` and return it. Otherwise, `NewText()` will call the user-supplied function pointed to by `sNewText`, which is assumed to return an object from a class derived from `DwText`, and return that object.

virtual void PrintDebugInfo(DW_STD ostream& aStrm, int aDepth=0) const

This virtual function, inherited from `DwMessageComponent`, prints debugging information about this object to `aStrm`. It will also call `PrintDebugInfo()` for any of its child components down to a level of `aDepth`.

This member function is available only in the debug version of the library.

virtual void CheckInvariants() const

Aborts if one of the invariants of the object fails. Use this member function to track down bugs.

This member function is available only in the debug version of the library.

## Public Data Members

static DwText* (*sNewText)(const DwString&, DwMessageComponent*)

If `sNewText` is not NULL, it is assumed to point to a user-supplied function that returns an object from a class derived from `DwText`.