[−][src]Struct mail::header_encoding::EncodingWriter
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)
Implementations
impl<'inner> EncodingWriter<'inner>
[src]
pub fn has_unfinished_parts(&self) -> bool
[src]
Returns true if this type thinks we are in the process of writing a header.
pub fn mail_type(&self) -> MailType
[src]
Returns the associated mail type.
pub fn line_has_content(&self) -> bool
[src]
Returns true if the current line has content, i.e. any non WS char.
pub fn current_line_byte_length(&self) -> usize
[src]
Returns the length of the current line in bytes.
pub fn mark_fws_pos(&mut self)
[src]
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>
[src]
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>
[src]
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 mut self,
s: &str
) -> ConditionalWriteResult<'short, 'inner>
[src]
&'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>
[src]
pub fn write_if_atext(
&'short mut self,
s: &str
) -> ConditionalWriteResult<'short, 'inner>
[src]
&'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 theatext
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<FN>(
&'short mut self,
s: &str,
cond: FN
) -> ConditionalWriteResult<'short, 'inner> where
FN: FnOnce(&str) -> bool,
[src]
&'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>
[src]
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)
[src]
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)
[src]
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 multipleEnd
tokens, just one
pub fn undo_header(&mut self)
[src]
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)
[src]
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).
Auto Trait Implementations
impl<'a> RefUnwindSafe for EncodingWriter<'a>
impl<'a> Send for EncodingWriter<'a>
impl<'a> Sync for EncodingWriter<'a>
impl<'a> Unpin for EncodingWriter<'a>
impl<'a> !UnwindSafe for EncodingWriter<'a>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Erased for T
impl<T> From<T> for T
[src]
impl<T> HeaderTryFrom<T> for T
[src]
fn try_from(val: T) -> Result<T, ComponentCreationError>
[src]
impl<F, T> HeaderTryInto<T> for F where
T: HeaderTryFrom<F>,
[src]
T: HeaderTryFrom<F>,
fn try_into(self) -> Result<T, ComponentCreationError>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,