diff --git a/rust/flatbuffers/src/vector.rs b/rust/flatbuffers/src/vector.rs index 17a3a1698e..075fa6e95c 100644 --- a/rust/flatbuffers/src/vector.rs +++ b/rust/flatbuffers/src/vector.rs @@ -65,6 +65,24 @@ impl<'a, T: 'a> Vector<'a, T> { /// /// - UOffsetT element count /// - Consecutive list of `T` elements + /// + /// # Examples + /// + /// Constructing a vector requires the caller to establish the safety + /// conditions, even when the buffer happens to contain an empty vector: + /// + /// ```compile_fail + /// let bytes = [0_u8; 4]; + /// let _vector = flatbuffers::Vector::::new(&bytes, 0); + /// ``` + /// + /// ``` + /// let bytes = [0_u8; 4]; + /// // SAFETY: The four bytes encode a zero element count, so no element + /// // storage is required after the count. + /// let vector = unsafe { flatbuffers::Vector::::new(&bytes, 0) }; + /// assert!(vector.is_empty()); + /// ``` #[inline(always)] pub unsafe fn new(buf: &'a [u8], loc: usize) -> Self { Vector(buf, loc, PhantomData) @@ -155,6 +173,23 @@ impl<'a, T: Follow<'a> + 'a> Vector<'a, T> { /// # Safety /// /// `buf` must contain a value of T at `loc` and have alignment of 1 +/// +/// # Examples +/// +/// The caller must establish the safety conditions before forming a reference: +/// +/// ```compile_fail +/// let bytes = [1_u8, 2, 3, 4]; +/// let _value: &[u8; 4] = flatbuffers::follow_cast_ref(&bytes, 0); +/// ``` +/// +/// ``` +/// let bytes = [1_u8, 2, 3, 4]; +/// // SAFETY: [u8; 4] has alignment one, all its bit patterns are valid, and +/// // the buffer contains all four bytes for the lifetime of the reference. +/// let value: &[u8; 4] = unsafe { flatbuffers::follow_cast_ref(&bytes, 0) }; +/// assert_eq!(value, &bytes); +/// ``` pub unsafe fn follow_cast_ref<'a, T: Sized + 'a>(buf: &'a [u8], loc: usize) -> &'a T { assert_eq!(align_of::(), 1); let sz = size_of::(); @@ -219,6 +254,23 @@ impl<'a, T: 'a> VectorIter<'a, T> { /// /// buf must contain a contiguous sequence of `items_num` values of `T` /// + /// # Examples + /// + /// A raw-slice iterator also requires an explicit unsafe call: + /// + /// ```compile_fail + /// let bytes = [1_u8, 2, 3]; + /// let _iter = flatbuffers::VectorIter::::from_slice(&bytes, bytes.len()); + /// ``` + /// + /// ``` + /// let bytes = [1_u8, 2, 3]; + /// // SAFETY: The slice contains exactly three contiguous u8 values. + /// let iter = unsafe { + /// flatbuffers::VectorIter::::from_slice(&bytes, bytes.len()) + /// }; + /// assert!(iter.eq(bytes.iter().copied())); + /// ``` #[inline] pub unsafe fn from_slice(buf: &'a [u8], items_num: usize) -> Self { VectorIter { buf, loc: 0, remaining: items_num, phantom: PhantomData }