Type Alias mozjs::jsapi::JS::SelfHostedCache

pub type SelfHostedCache = [u64; 2];

Span - slices for C++

Span implements Rust’s slice concept for C++. It’s called “Span” instead of “Slice” to follow the naming used in C++ Core Guidelines.

A Span wraps a pointer and a length that identify a non-owning view to a contiguous block of memory of objects of the same type. Various types, including (pre-decay) C arrays, XPCOM strings, nsTArray, mozilla::Array, mozilla::Range and contiguous standard-library containers, auto-convert into Spans when attempting to pass them as arguments to methods that take Spans. (Span itself autoconverts into mozilla::Range.)

Like Rust’s slices, Span provides safety against out-of-bounds access by performing run-time bound checks. However, unlike Rust’s slices, Span cannot provide safety against use-after-free.

(Note: Span is like Rust’s slice only conceptually. Due to the lack of ABI guarantees, you should still decompose spans/slices to raw pointer and length parts when crossing the FFI. The Elements() and data() methods are guaranteed to return a non-null pointer even for zero-length spans, so the pointer can be used as a raw part of a Rust slice without further checks.)

In addition to having constructors (with the support of deduction guides) that take various well-known types, a Span for an arbitrary type can be constructed from a pointer and a length or a pointer and another pointer pointing just past the last element.

A Span or Span can be obtained for const char* or const char16_t pointing to a zero-terminated string using the MakeStringSpan() function (which treats a nullptr argument equivalently to the empty string). Corresponding implicit constructor does not exist in order to avoid accidental construction in cases where const char* or const char16_t* do not point to a zero-terminated string.

Span has methods that follow the Mozilla naming style and methods that don’t. The methods that follow the Mozilla naming style are meant to be used directly from Mozilla code. The methods that don’t are meant for integration with C++11 range-based loops and with meta-programming that expects the same methods that are found on the standard-library containers. For example, to decompose a Span into its parts in Mozilla code, use Elements() and Length() (as with nsTArray) instead of data() and size() (as with std::vector).

The pointer and length wrapped by a Span cannot be changed after a Span has been created. When new values are required, simply create a new Span. Span has a method called Subspan() that works analogously to the Substring() method of XPCOM strings taking a start index and an optional length. As a Mozilla extension (relative to Microsoft’s gsl::span that mozilla::Span is based on), Span has methods From(start), To(end) and FromTo(start, end) that correspond to Rust’s &slice[start..], &slice[..end] and &slice[start..end], respectively. (That is, the end index is the index of the first element not to be included in the new subspan.)

When indicating a Span that’s only read from, const goes inside the type parameter. Don’t put const in front of Span. That is: size_t ReadsFromOneSpanAndWritesToAnother(Span aReadFrom, Span<uint8_t> aWrittenTo);

Any Span can be viewed as Span using the function AsBytes(). Any Span can be viewed as Span<uint8_t> using the function AsWritableBytes().

Note that iterators from different Span instances are uncomparable, even if they refer to the same memory. This also applies to any spans derived via Subspan etc.