Crate nsstring [−] [src]
This module provides rust bindings for the XPCOM string types.
TL;DR (what types should I use)
Use &{mut,} nsA[C]String for functions in rust which wish to take or
mutate XPCOM strings. The other string types Deref to this type.
Use ns[C]String (ns[C]String in C++) for string struct members, and as
an intermediate between rust string data structures (such as String or
Vec<u16>) and &{mut,} nsA[C]String (using ns[C]String::from(value)).
These conversions will attempt to re-use the passed-in buffer, appending a
null.
Use ns[C]Str (nsDependent[C]String in C++) as an intermediate between
borrowed rust data structures (such as &str and &[u16]) and &{mut,} nsA[C]String (using ns[C]Str::from(value)). These conversions should not
perform any allocations. This type is not safe to share with C++ as a
struct field, but passing the borrowed &{mut,} nsA[C]String over FFI is
safe.
Use *{const,mut} nsA[C]String ({const,} nsA[C]String* in C++) for
function arguments passed across the rust/C++ language boundary.
There is currently no Rust equivalent to nsAuto[C]String. Implementing a type that contains a pointer to an inline buffer is difficult in Rust due to its move semantics, which require that it be safe to move a value by copying its bits. If such a type is genuinely needed at some point, https://bugzilla.mozilla.org/show_bug.cgi?id=1403506#c6 has a sketch of how to emulate it via macros.
String Types
nsA[C]String
The core types in this module are nsAString and nsACString. These types
are zero-sized as far as rust is concerned, and are safe to pass around
behind both references (in rust code), and pointers (in C++ code). They
represent a handle to a XPCOM string which holds either u16 or u8
characters respectively. The backing character buffer is guaranteed to live
as long as the reference to the nsAString or nsACString.
These types in rust are simply used as dummy types. References to them
represent a pointer to the beginning of a variable-sized #[repr(C)] struct
which is common between both C++ and Rust implementations. In C++, their
corresponding types are also named nsAString or nsACString, and they are
defined within the nsTSubstring.{cpp,h} file.
Valid Operations
An &nsA[C]String acts like rust's &str, in that it is a borrowed
reference to the backing data. When used as an argument to other functions
on &mut nsA[C]String, optimizations can be performed to avoid copying
buffers, as information about the backing storage is preserved.
An &mut nsA[C]String acts like rust's &mut Cow<str>, in that it is a
mutable reference to a potentially borrowed string, which when modified will
ensure that it owns its own backing storage. This type can be appended to
with the methods .append, .append_utf{8,16}, and with the write!
macro, and can be assigned to with .assign.
ns[C]Str<'a>
This type is an maybe-owned string type. It acts similarially to a
Cow<[{u8,u16}]>. This type provides Deref and DerefMut implementations
to nsA[C]String, which provides the methods for manipulating this type.
This type's lifetime parameter, 'a, represents the lifetime of the backing
storage. When modified this type may re-allocate in order to ensure that it
does not mutate its backing storage.
ns[C]Strs can be constructed either with ns[C]Str::new(), which creates
an empty ns[C]Str<'static>, or through one of the provided From
implementations. Only nsCStr can be constructed From<'a str>, as
constructing a nsStr would require transcoding. Use ns[C]String instead.
When passing this type by reference, prefer passing a &nsA[C]String or
&mut nsA[C]String. to passing this type.
When passing this type across the language boundary, pass it as *const nsA[C]String for an immutable reference, or *mut nsA[C]String for a
mutable reference.
ns[C]String
This type is an owned, null-terminated string type. This type provides
Deref and DerefMut implementations to nsA[C]String, which provides the
methods for manipulating this type.
ns[C]Strings can be constructed either with ns[C]String::new(), which
creates an empty ns[C]String, or through one of the provided From
implementations, which will try to avoid reallocating when possible,
although a terminating null will be added.
When passing this type by reference, prefer passing a &nsA[C]String or
&mut nsA[C]String. to passing this type.
When passing this type across the language boundary, pass it as *const nsA[C]String for an immutable reference, or *mut nsA[C]String for a
mutable reference. This struct may also be included in #[repr(C)] structs
shared with C++.
ns[C]StringRepr
This crate also provides the type ns[C]StringRepr which acts conceptually
similar to an ns[C]String, however, it does not have a Drop
implementation.
If this type is dropped in rust, it will not free its backing storage. This
can be useful when implementing FFI types which contain ns[C]String members
which invoke their member's destructors through C++ code.
Modules
| test_helpers |
This module only exists to help with ensuring that the layout of the structs inside of rust and C++ are identical. |
Structs
| nsACString |
This type is the abstract type which is used for interacting with strings in rust. Each string type can derefence to an instance of this type, which provides the useful operations on strings. |
| nsAString |
This type is the abstract type which is used for interacting with strings in rust. Each string type can derefence to an instance of this type, which provides the useful operations on strings. |
| nsCStr | |
| nsCString | |
| nsCStringRepr |
The representation of a ns[C]String type in C++. This type is used internally by our definition of ns[C]String to ensure layout compatibility with the C++ ns[C]String type. |
| nsStr | |
| nsString | |
| nsStringRepr |
The representation of a ns[C]String type in C++. This type is used internally by our definition of ns[C]String to ensure layout compatibility with the C++ ns[C]String type. |
Enums
| nsCStringAdapter |
An adapter type to allow for passing both types which coerce to &[$char_type], and &$AString to a function, while still performing optimized operations when passed the $AString. |
| nsStringAdapter |
An adapter type to allow for passing both types which coerce to &[$char_type], and &$AString to a function, while still performing optimized operations when passed the $AString. |
Traits
| nsCStringLike |
This trait is implemented on types which are |
| nsStringLike |
This trait is implemented on types which are |