Struct mail_internals::encoder::EncodingWriter

pub struct EncodingWriter<'a> { /* fields omitted */ }

A handle providing method to write to the underlying buffer keeping track of newlines the current line length and places where the line can be broken so that the soft line length limit (78) and the hard length limit (998) can be kept.

It's basically a string buffer which know how to brake lines at the right place.

Note any act of writing a header through EncodingWriter has to be concluded by either calling finish_header or undo_header. If not this handle will panic in test builds when being dropped (and the thread is not already panicing) as writes through the handle are directly writes to the underlying buffer which now contains malformed/incomplete data. (Note that this Handle does not own any Drop types so if needed forget-ing it won't leak any memory)

Methods

impl<'inner> EncodingWriter<'inner>

pub fn has_unfinished_parts(&self) -> bool

Returns true if this type thinks we are in the process of writing a header.

pub fn mail_type(&self) -> MailType

Returns the associated mail type.

pub fn line_has_content(&self) -> bool

Returns true if the current line has content, i.e. any non WS char.

pub fn current_line_byte_length(&self) -> usize

Returns the length of the current line in bytes.

pub fn mark_fws_pos(&mut self)

marks the current position a a place where a soft line break (i.e. "\r\n ") can be inserted

Trace (test build only)

does push a MarkFWS Token

pub fn write_char(&mut self, ch: SoftAsciiChar) -> Result<(), EncodingError>

writes a ascii char to the underlying buffer

Error

• fails if the hard line length limit is breached and the line can not be broken with soft line breaks
• buffer would contain a orphan '\r' or '\n' after the write

Trace (test build only)

does push NowChar and then can push Text,CRLF

pub fn write_str(&mut self, s: &SoftAsciiStr) -> Result<(), EncodingError>

writes a ascii str to the underlying buffer

Error

• fails if the hard line length limit is breached and the line can not be broken with soft line breaks
• buffer would contain a orphan '\r' or '\n' after the write

Note that in case of an error part of the content might already have been written to the buffer, therefore it is recommended to call undo_header after an error (especially if the handle is doped after this!)

Trace (test build only)

does push NowStr and then can push Text,CRLF

pub fn write_if_utf8<'short>(
    &'short mut self,
    s: &str
) -> ConditionalWriteResult<'short, 'inner>

writes a utf8 str into a buffer for an internationalized mail

Error (ConditionalWriteResult)

• fails with ConditionFailure if the underlying MailType is not Internationalized
• fails with GeneralFailure if the hard line length limit is reached
• or if the buffer would contain a orphan '\r' or '\n' after the write

Note that in case of an error part of the content might already have been written to the buffer, therefore it is recommended to call undo_header after an error (especially if the handle is droped after this!)

Trace (test build only)

does push NowUtf8 and then can push Text,CRLF

pub fn write_utf8(&mut self, s: &str) -> Result<(), EncodingError>

pub fn write_if_atext<'short>(
    &'short mut self,
    s: &str
) -> ConditionalWriteResult<'short, 'inner>

Writes a str assumed to be atext if it is atext given the mail type

This method is mainly an optimization as the "is atext" and is "is ascii if MailType is Ascii" aspects are checked at the same time resulting in a str which you know is ascii if the mail type is Ascii and which might be non-us-ascii if the mail type is Internationalized.

Error (ConditionalWriteResult)

• fails with ConditionFailure if the text is not valid atext, this indirectly also includes the utf8/Internationalization check as the atext grammar differs between normal and internationalized mail.
• fails with GeneralFailure if the hard line length limit is reached and the line can't be broken with soft line breaks
• or if buffer would contain a orphan '\r' or '\n' after the write (excluding a tailing '\r' as it is still valid if followed by an '\n')

Note that in case of an error part of the content might already have been written to the buffer, therefore it is recommended to call undo_header after an error (especially if the handle is doped after this!)

Trace (test build only)

does push NowAText and then can push Text

pub fn write_if<'short, FN>(
    &'short mut self,
    s: &str,
    cond: FN
) -> ConditionalWriteResult<'short, 'inner> where
    FN: FnOnce(&str) -> bool, 

passes the input s to the condition evaluation function cond and then writes it without additional checks to the buffer if cond returned true

pub fn write_str_unchecked(&mut self, s: &str) -> Result<(), EncodingError>

writes a string to the encoder without checking if it is compatible with the mail type, if not used correctly this can write Utf8 to an Ascii Mail, which is incorrect but has to be safe wrt. rust's safety.

Use it as a replacement for cases similar to following:

check_if_text_if_valid(text)?;
if mail_type.is_internationalized() {
    handle.write_utf8(text)?;
} else {
    handle.write_str(SoftAsciiStr::from_unchecked(text))?;
}

==> instead ==>

check_if_text_if_valid(text)?;
handle.write_str_unchecked(text)?;

through is gives a different tracing its roughly equivalent.

pub fn commit_partial_header(&mut self)

like finish_header, but won't start a new line

This is meant to be used when miss-using the writer to write a "think", which is not a full header. E.g. for testing if a header component is written correctly. So you normally should not use it.

pub fn finish_header(&mut self)

finishes the writing of a header

It makes sure the header ends in "\r\n". If the header ends in a orphan '\r' this method will just "use" it for the "\r\n".

If the header ends in a CRLF/start of buffer followed by only WS (' ' or '\t' ) the valid header ending is reached by truncating away the WS padding. This is needed as "blank" lines are not allowed.

Trace (test build only)

• can push 0-1 of [CRLF, TruncateToCRLF]
• then does push End
• calling finish_current() multiple times in a row will not generate multiple End tokens, just one

pub fn undo_header(&mut self)

undoes all writes to the internal buffer since the last finish_header or undo_header or creation of this handle

Trace (test build only)

also removes tokens pushed since the last finish_header or undo_header or creation of this handle

pub fn write_fws(&mut self)

calls mark_fws_pos and then writes a space

This method exists for convenience.

Note that it can not fail a you just pushed a place to brake the line before writing a space.

Note that currently soft line breaks will not collapse whitespace. As such if you use write_fws and then the line is broken at that position it will start with two spaces (one from \r\n and one which had been there before).