mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rollup merge of #17355 : gamazeps/issue17210

Browse Source
This commit is contained in:
Alex Crichton 2014-09-19 10:00:35 -07:00
commit a116c7272b
1 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
src/librustrt/c_str.rs
View File

@ -36,6 +36,12 @@ not tied to the lifetime of the original string/data buffer). If C strings are
heavily used in applications, then caching may be advisable to prevent
unnecessary amounts of allocations.
Be carefull to remember that the memory is managed by C allocator API and not
by Rust allocator API.
That means that the CString pointers should be freed with C allocator API
if you intend to do that on your own, as the behaviour if you free them with
Rust's allocator API is not well defined
An example of creating and using a C string would be:
```rust
@ -91,8 +97,8 @@ pub struct CString {
impl Clone for CString {
/// Clone this CString into a new, uniquely owned CString. For safety
/// reasons, this is always a deep clone, rather than the usual shallow
/// clone.
/// reasons, this is always a deep clone with the memory allocated
/// with C's allocator API, rather than the usual shallow clone.
fn clone(&self) -> CString {
let len = self.len() + 1;
let buf = unsafe { malloc_raw(len) } as *mut libc::c_char;
@ -131,7 +137,9 @@ impl<S: hash::Writer> hash::Hash<S> for CString {
}
impl CString {
/// Create a C String from a pointer.
/// Create a C String from a pointer, with memory managed by C's allocator
/// API, so avoid calling it with a pointer to memory managed by Rust's
/// allocator API, as the behaviour would not be well defined.
///
///# Failure
///
@ -265,7 +273,8 @@ impl CString {
/// forgotten, meaning that the backing allocation of this
/// `CString` is not automatically freed if it owns the
/// allocation. In this case, a user of `.unwrap()` should ensure
/// the allocation is freed, to avoid leaking memory.
/// the allocation is freed, to avoid leaking memory. You should
/// use libc's memory allocator in this case.
///
/// Prefer `.as_ptr()` when just retrieving a pointer to the
/// string data, as that does not relinquish ownership.