From 895d450366539b10aa6994f01a41c3178d3b471f Mon Sep 17 00:00:00 2001 From: bluss Date: Thu, 26 Oct 2017 19:15:11 +0200 Subject: [PATCH] DOC: Promise debug assertions for unsafe methods Instead of being vague about it, we can promise it. We continue to be a bit vague in ArrayString::set_len. I don't see how to add a char boundary check in ArrayString::set_len unfortunately. It's a tricky issue, checking char boundaries requires reading the memory of the string, and we don't even know if the user of set_len has initialized that area of memory yet (but they hopefully did). --- src/array_string.rs | 5 +++-- src/lib.rs | 10 +++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/array_string.rs b/src/array_string.rs index c4f5115..de63ee2 100644 --- a/src/array_string.rs +++ b/src/array_string.rs @@ -322,10 +322,11 @@ impl> ArrayString { /// Set the strings's length. /// - /// May panic if `length` is greater than the capacity. - /// /// This function is `unsafe` because it changes the notion of the /// number of “valid” bytes in the string. Use with care. + /// + /// This method uses *debug assertions* to check the validity of `length` + /// and may use other debug assertions. #[inline] pub unsafe fn set_len(&mut self, length: usize) { debug_assert!(length <= self.capacity()); diff --git a/src/lib.rs b/src/lib.rs index b751077..bc9d97d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -226,7 +226,7 @@ impl ArrayVec { /// It is up to the caller to ensure the capacity of the vector is /// sufficiently large. /// - /// This method *may* use debug assertions to check that the arrayvec is not full. + /// This method uses *debug assertions* to check that the arrayvec is not full. /// /// ``` /// use arrayvec::ArrayVec; @@ -502,11 +502,11 @@ impl ArrayVec { /// Set the vector's length without dropping or moving out elements /// - /// May use debug assertions to check that `length` is not greater than the - /// capacity. - /// - /// This function is `unsafe` because it changes the notion of the + /// This method is `unsafe` because it changes the notion of the /// number of “valid” elements in the vector. Use with care. + /// + /// This method uses *debug assertions* to check that check that `length` is + /// not greater than the capacity. #[inline] pub unsafe fn set_len(&mut self, length: usize) { debug_assert!(length <= self.capacity());