Skip to content

Add doc examples for CString methods. #42470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 8, 2017
Merged

Add doc examples for CString methods. #42470

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4db8c9f
Add doc example for `CString::into_raw`.
frewsxcv Jun 6, 2017
3ec1f61
Add doc example for `CString::into_bytes`.
frewsxcv Jun 6, 2017
815c12a
Add doc example for `CString::into_bytes_with_nul`.
frewsxcv Jun 6, 2017
ae4832d
Add doc example for `CString::as_bytes_with_nul`.
frewsxcv Jun 6, 2017
06f63f5
Add doc example for `CString::as_bytes`.
frewsxcv Jun 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions src/libstd/ffi/c_str.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -288,6 +288,26 @@ impl CString {
/// Failure to call [`from_raw`] will lead to a memory leak.
///
/// [`from_raw`]: #method.from_raw
///
/// # Examples
///
/// ```
/// use std::ffi::CString;
///
/// let c_string = CString::new("foo").unwrap();
///
/// let ptr = c_string.into_raw();
///
/// unsafe {
/// assert_eq!(b'f', *ptr as u8);
/// assert_eq!(b'o', *ptr.offset(1) as u8);
/// assert_eq!(b'o', *ptr.offset(2) as u8);
/// assert_eq!(b'\0', *ptr.offset(3) as u8);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm less certain about this one. If people are used to working with raw pointers in Rust this is fine, but i wonder if we can do some other kind of comparison to not have to introduce offset in these docs. I don't anticipate people looking at CString with a solid understanding of Rust pointers. This is frequently an entry point into FFI, so readers may potentially only have a cursory understanding of pointers.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what else would fit here, let me know if you have any ideas. Or if you'd prefer the offset lines to be removed, I can do that too

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that I think back on it, this is probably good as-is. I was thinking of something like slice::from_raw_parts and comparing against a byte-string, but that risks losing focus from showing off the actual function being documented. If we come up with something better, we can always send another PR.

///
/// // retake pointer to free memory
/// let _ = CString::from_raw(ptr);
/// }
/// ```
#[stable(feature = "cstr_memory", since = "1.4.0")]
pub fn into_raw(self) -> *mut c_char {
Box::into_raw(self.into_inner()) as *mut c_char
Expand All @@ -311,6 +331,16 @@ impl CString {
///
/// The returned buffer does **not** contain the trailing nul separator and
/// it is guaranteed to not have any interior nul bytes.
///
/// # Examples
///
/// ```
/// use std::ffi::CString;
///
/// let c_string = CString::new("foo").unwrap();
/// let bytes = c_string.into_bytes();
/// assert_eq!(bytes, vec![b'f', b'o', b'o']);
/// ```
#[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_bytes(self) -> Vec<u8> {
let mut vec = self.into_inner().into_vec();
Expand All @@ -323,6 +353,16 @@ impl CString {
/// includes the trailing nul byte.
///
/// [`into_bytes`]: #method.into_bytes
///
/// # Examples
///
/// ```
/// use std::ffi::CString;
///
/// let c_string = CString::new("foo").unwrap();
/// let bytes = c_string.into_bytes_with_nul();
/// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']);
/// ```
#[stable(feature = "cstring_into", since = "1.7.0")]
pub fn into_bytes_with_nul(self) -> Vec<u8> {
self.into_inner().into_vec()
Expand All @@ -332,6 +372,16 @@ impl CString {
///
/// The returned slice does **not** contain the trailing nul separator and
/// it is guaranteed to not have any interior nul bytes.
///
/// # Examples
///
/// ```
/// use std::ffi::CString;
///
/// let c_string = CString::new("foo").unwrap();
/// let bytes = c_string.as_bytes();
/// assert_eq!(bytes, &[b'f', b'o', b'o']);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_bytes(&self) -> &[u8] {
&self.inner[..self.inner.len() - 1]
Expand All @@ -341,6 +391,16 @@ impl CString {
/// includes the trailing nul byte.
///
/// [`as_bytes`]: #method.as_bytes
///
/// # Examples
///
/// ```
/// use std::ffi::CString;
///
/// let c_string = CString::new("foo").unwrap();
/// let bytes = c_string.as_bytes_with_nul();
/// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_bytes_with_nul(&self) -> &[u8] {
&self.inner
Expand Down