pub struct ProtoStr(/* private fields */);Expand description
A shared immutable view of a protobuf string field’s contents.
Like a str, it can be cheaply accessed as bytes and
is dynamically sized, requiring it be accessed through a pointer.
§UTF-8 and &str access
Protobuf docs state that a string field contains UTF-8 encoded text.
However, not every runtime enforces this, and the Rust runtime is designed
to integrate with other runtimes with FFI, like C++.
Because of this, in order to access the contents as a &str, users must
call ProtoStr::to_str to perform a (possibly runtime-elided) UTF-8
validation check. However, the Rust API only allows set()ting a string
field with data should be valid UTF-8 like a &str or a
&ProtoStr. This means that this check should rarely fail, but is necessary
to prevent UB when interacting with C++, which has looser restrictions.
Most of the time, users should not perform direct &str access to the
contents - this type implements Display and comparison with str,
so it’s best to avoid a UTF-8 check by working directly with &ProtoStr
or converting to &[u8].
§Display and ToString
ProtoStr is ordinarily UTF-8 and so implements Display. If there are
any invalid UTF-8 sequences, they are replaced with U+FFFD REPLACEMENT CHARACTER. Because anything implementing Display also implements
ToString, proto_str.to_string() is equivalent to
String::from_utf8_lossy(proto_str.as_bytes()).into_owned().
Implementations§
Source§impl ProtoStr
impl ProtoStr
Sourcepub fn as_bytes(&self) -> &[u8] ⓘ
pub fn as_bytes(&self) -> &[u8] ⓘ
Converts self to a byte slice.
Note: this type does not implement Deref; you must call as_bytes()
or AsRef<[u8]> to get access to bytes.
Sourcepub fn to_str(&self) -> Result<&str, Utf8Error>
pub fn to_str(&self) -> Result<&str, Utf8Error>
Yields a &str slice if self contains valid UTF-8.
This may perform a runtime check, dependent on runtime.
String::from_utf8_lossy(proto_str.as_bytes()) can be used to
infallibly construct a string, replacing invalid UTF-8 with
U+FFFD REPLACEMENT CHARACTER.
Sourcepub fn to_cow_lossy(&self) -> Cow<'_, str>
pub fn to_cow_lossy(&self) -> Cow<'_, str>
Converts self to a string, including invalid characters.
Invalid UTF-8 sequences are replaced with
U+FFFD REPLACEMENT CHARACTER.
Users should be prefer this to .to_string() provided by Display.
.to_cow_lossy() is the same operation, but it may avoid an
allocation if the string is already UTF-8.
Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the length of self.
Like &str, this is a length in bytes, not chars or graphemes.
Sourcepub fn chars(&self) -> impl Iterator<Item = char> + '_ + Debug
pub fn chars(&self) -> impl Iterator<Item = char> + '_ + Debug
Iterates over the chars in this protobuf string.
Invalid UTF-8 sequences are replaced with
U+FFFD REPLACEMENT CHARACTER.
Sourcepub fn utf8_chunks(&self) -> impl Iterator<Item = Result<&str, &[u8]>> + '_
pub fn utf8_chunks(&self) -> impl Iterator<Item = Result<&str, &[u8]>> + '_
Returns an iterator over chunks of UTF-8 data in the string.
An Ok(&str) is yielded for every valid UTF-8 chunk, and an
Err(&[u8]) for each non-UTF-8 chunk. An Err will be emitted
multiple times in a row for contiguous invalid chunks. Each invalid
chunk in an Err has a maximum length of 3 bytes.
Sourcepub unsafe fn from_utf8_unchecked(bytes: &[u8]) -> &Self
pub unsafe fn from_utf8_unchecked(bytes: &[u8]) -> &Self
Converts known-UTF-8 bytes to a ProtoStr without a check.
§Safety
bytes must be valid UTF-8 if the current runtime requires it.