pub struct Charset { /* private fields */ }
Expand description
A character encoding suitable for decoding email.
This is either an encoding as defined in the Encoding Standard or UTF-7 as defined in RFC 2152.
Each Charset
has one or more labels that are used to identify
the Charset
in protocol text. In MIME/IANA terminology, these are
called names and aliases, but for consistency with the Encoding
Standard and the encoding_rs crate, they are called labels in this
crate. What this crate calls the name (again, for consistency
with the Encoding Standard and the encoding_rs crate) is known as
preferred name in MIME/IANA terminology.
Instances of Charset
can be compared with ==
. Charset
is
Copy
and is meant to be passed by value.
Note: It is wrong to use this for decoding Web content. Use
encoding_rs::Encoding
instead!
Implementations
sourceimpl Charset
impl Charset
sourcepub fn for_label(label: &[u8]) -> Option<Charset>
pub fn for_label(label: &[u8]) -> Option<Charset>
Implements the
get an encoding
algorithm with the label “UTF-7” added to the set of labels recognized.
GBK is unified with gb18030, since they decode the same and Charset
only supports decoding.
If, after ASCII-lowercasing and removing leading and trailing
whitespace, the argument matches a label defined in the Encoding
Standard or “utf-7”, Some(Charset)
representing the corresponding
encoding is returned. If there is no match, None
is returned.
This is the right method to use if the action upon the method returning
None
is to use a fallback encoding (e.g. WINDOWS_1252
) instead.
When the action upon the method returning None
is not to proceed with
a fallback but to refuse processing, for_label_no_replacement()
is more
appropriate.
The argument is of type &[u8]
instead of &str
to save callers
that are extracting the label from a non-UTF-8 protocol the trouble
of conversion to UTF-8. (If you have a &str
, just call .as_bytes()
on it.)
sourcepub fn for_label_no_replacement(label: &[u8]) -> Option<Charset>
pub fn for_label_no_replacement(label: &[u8]) -> Option<Charset>
This method behaves the same as for_label()
, except when for_label()
would return Some(Charset::for_encoding(encoding_rs::REPLACEMENT))
,
this method returns None
instead.
This method is useful in scenarios where a fatal error is required upon invalid label, because in those cases the caller typically wishes to treat the labels that map to the replacement encoding as fatal errors, too.
It is not OK to use this method when the action upon the method returning
None
is to use a fallback encoding (e.g. WINDOWS_1252
) with text/html
email. In such a case, the for_label()
method should be used instead in
order to avoid unsafe fallback for labels that for_label()
maps to
Some(REPLACEMENT)
. Such fallback might be safe, though not particularly
useful for text/plain
email, though.
sourcepub fn for_encoding(encoding: &'static Encoding) -> Charset
pub fn for_encoding(encoding: &'static Encoding) -> Charset
Returns the Charset
corresponding to an &'static Encoding
.
GBK
is unified with GB18030
, since those two decode the same
and Charset
only supports decoding.
sourcepub fn for_bom(buffer: &[u8]) -> Option<(Charset, usize)>
pub fn for_bom(buffer: &[u8]) -> Option<(Charset, usize)>
Performs non-incremental BOM sniffing.
The argument must either be a buffer representing the entire input stream (non-streaming case) or a buffer representing at least the first three bytes of the input stream (streaming case).
Returns Some((Charset::for_encoding(encoding_rs::UTF_8), 3))
,
Some((Charset::for_encoding(encoding_rs::UTF_16LE), 2))
or
Some((Charset::for_encoding(encoding_rs::UTF_16BE), 2))
if the
argument starts with the UTF-8, UTF-16LE or UTF-16BE BOM or None
otherwise.
sourcepub fn name(self) -> &'static str
pub fn name(self) -> &'static str
Returns the name of this encoding.
Mostly useful for debugging
sourcepub fn is_ascii_compatible(self) -> bool
pub fn is_ascii_compatible(self) -> bool
Checks whether the bytes 0x00…0x7F map exclusively to the characters U+0000…U+007F and vice versa.
sourcepub fn decode<'a>(self, bytes: &'a [u8]) -> (Cow<'a, str>, Charset, bool)
pub fn decode<'a>(self, bytes: &'a [u8]) -> (Cow<'a, str>, Charset, bool)
Decode complete input to Cow<'a, str>
with BOM sniffing and with
malformed sequences replaced with the REPLACEMENT CHARACTER when the
entire input is available as a single buffer (i.e. the end of the
buffer marks the end of the stream).
This method implements the (non-streaming version of) the decode spec concept.
The second item in the returned tuple is the encoding that was actually used (which may differ from this encoding thanks to BOM sniffing).
The third item in the returned tuple indicates whether there were malformed sequences (that were replaced with the REPLACEMENT CHARACTER).
Note: It is wrong to use this when the input buffer represents only a segment of the input instead of the whole input.
Panics
If the size calculation for a heap-allocated backing buffer overflows
usize
.
sourcepub fn decode_with_bom_removal<'a>(self, bytes: &'a [u8]) -> (Cow<'a, str>, bool)
pub fn decode_with_bom_removal<'a>(self, bytes: &'a [u8]) -> (Cow<'a, str>, bool)
Decode complete input to Cow<'a, str>
with BOM removal and with
malformed sequences replaced with the REPLACEMENT CHARACTER when the
entire input is available as a single buffer (i.e. the end of the
buffer marks the end of the stream).
When invoked on UTF_8
, this method implements the (non-streaming
version of) the
UTF-8 decode spec
concept.
The second item in the returned pair indicates whether there were malformed sequences (that were replaced with the REPLACEMENT CHARACTER).
Note: It is wrong to use this when the input buffer represents only a segment of the input instead of the whole input.
Panics
If the size calculation for a heap-allocated backing buffer overflows
usize
.
sourcepub fn decode_without_bom_handling<'a>(
self,
bytes: &'a [u8]
) -> (Cow<'a, str>, bool)
pub fn decode_without_bom_handling<'a>(
self,
bytes: &'a [u8]
) -> (Cow<'a, str>, bool)
Decode complete input to Cow<'a, str>
without BOM handling and
with malformed sequences replaced with the REPLACEMENT CHARACTER when
the entire input is available as a single buffer (i.e. the end of the
buffer marks the end of the stream).
When invoked on UTF_8
, this method implements the (non-streaming
version of) the
UTF-8 decode without BOM
spec concept.
The second item in the returned pair indicates whether there were malformed sequences (that were replaced with the REPLACEMENT CHARACTER).
Note: It is wrong to use this when the input buffer represents only a segment of the input instead of the whole input.
Panics
If the size calculation for a heap-allocated backing buffer overflows
usize
.