src/librustrt/c_str.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! C-string manipulation and management
  12 //!
  13 //! This modules provides the basic methods for creating and manipulating
  14 //! null-terminated strings for use with FFI calls (back to C). Most C APIs require
  15 //! that the string being passed to them is null-terminated, and by default rust's
  16 //! string types are *not* null terminated.
  17 //!
  18 //! The other problem with translating Rust strings to C strings is that Rust
  19 //! strings can validly contain a null-byte in the middle of the string (0 is a
  20 //! valid Unicode codepoint). This means that not all Rust strings can actually be
  21 //! translated to C strings.
  22 //!
  23 //! # Creation of a C string
  24 //!
  25 //! A C string is managed through the `CString` type defined in this module. It
  26 //! "owns" the internal buffer of characters and will automatically deallocate the
  27 //! buffer when the string is dropped. The `ToCStr` trait is implemented for `&str`
  28 //! and `&[u8]`, but the conversions can fail due to some of the limitations
  29 //! explained above.
  30 //!
  31 //! This also means that currently whenever a C string is created, an allocation
  32 //! must be performed to place the data elsewhere (the lifetime of the C string is
  33 //! not tied to the lifetime of the original string/data buffer). If C strings are
  34 //! heavily used in applications, then caching may be advisable to prevent
  35 //! unnecessary amounts of allocations.
  36 //!
  37 //! Be carefull to remember that the memory is managed by C allocator API and not
  38 //! by Rust allocator API.
  39 //! That means that the CString pointers should be freed with C allocator API
  40 //! if you intend to do that on your own, as the behaviour if you free them with
  41 //! Rust's allocator API is not well defined
  42 //!
  43 //! An example of creating and using a C string would be:
  44 //!
  45 //! ```rust
  46 //! extern crate libc;
  47 //!
  48 //! extern {
  49 //!     fn puts(s: *const libc::c_char);
  50 //! }
  51 //!
  52 //! fn main() {
  53 //!     let my_string = "Hello, world!";
  54 //!
  55 //!     // Allocate the C string with an explicit local that owns the string. The
  56 //!     // `c_buffer` pointer will be deallocated when `my_c_string` goes out of scope.
  57 //!     let my_c_string = my_string.to_c_str();
  58 //!     unsafe {
  59 //!         puts(my_c_string.as_ptr());
  60 //!     }
  61 //!
  62 //!     // Don't save/return the pointer to the C string, the `c_buffer` will be
  63 //!     // deallocated when this block returns!
  64 //!     my_string.with_c_str(|c_buffer| {
  65 //!         unsafe { puts(c_buffer); }
  66 //!     });
  67 //! }
  68 //! ```
  69
  70 use collections::string::String;
  71 use collections::hash;
  72 use core::fmt;
  73 use core::kinds::{Sized, marker};
  74 use core::mem;
  75 use core::prelude::{Clone, Drop, Eq, Iterator};
  76 use core::prelude::{SlicePrelude, None, Option, Ordering, PartialEq};
  77 use core::prelude::{PartialOrd, RawPtr, Some, StrPrelude, range};
  78 use core::ptr;
  79 use core::raw::Slice;
  80 use core::slice;
  81 use core::str;
  82 use libc;
  83
  84 /// The representation of a C String.
  85 ///
  86 /// This structure wraps a `*libc::c_char`, and will automatically free the
  87 /// memory it is pointing to when it goes out of scope.
  88 pub struct CString {
  89     buf: *const libc::c_char,
  90     owns_buffer_: bool,
  91 }
  92
  93 impl Clone for CString {
  94     /// Clone this CString into a new, uniquely owned CString. For safety
  95     /// reasons, this is always a deep clone with the memory allocated
  96     /// with C's allocator API, rather than the usual shallow clone.
  97     fn clone(&self) -> CString {
  98         let len = self.len() + 1;
  99         let buf = unsafe { libc::malloc(len as libc::size_t) } as *mut libc::c_char;
 100         if buf.is_null() { ::alloc::oom() }
 101         unsafe { ptr::copy_nonoverlapping_memory(buf, self.buf, len); }
 102         CString { buf: buf as *const libc::c_char, owns_buffer_: true }
 103     }
 104 }
 105
 106 impl PartialEq for CString {
 107     fn eq(&self, other: &CString) -> bool {
 108         // Check if the two strings share the same buffer
 109         if self.buf as uint == other.buf as uint {
 110             true
 111         } else {
 112             unsafe {
 113                 libc::strcmp(self.buf, other.buf) == 0
 114             }
 115         }
 116     }
 117 }
 118
 119 impl PartialOrd for CString {
 120     #[inline]
 121     fn partial_cmp(&self, other: &CString) -> Option<Ordering> {
 122         self.as_bytes().partial_cmp(other.as_bytes())
 123     }
 124 }
 125
 126 impl Eq for CString {}
 127
 128 impl<S: hash::Writer> hash::Hash<S> for CString {
 129     #[inline]
 130     fn hash(&self, state: &mut S) {
 131         self.as_bytes().hash(state)
 132     }
 133 }
 134
 135 impl CString {
 136     /// Create a C String from a pointer, with memory managed by C's allocator
 137     /// API, so avoid calling it with a pointer to memory managed by Rust's
 138     /// allocator API, as the behaviour would not be well defined.
 139     ///
 140     ///# Panics
 141     ///
 142     /// Panics if `buf` is null
 143     pub unsafe fn new(buf: *const libc::c_char, owns_buffer: bool) -> CString {
 144         assert!(!buf.is_null());
 145         CString { buf: buf, owns_buffer_: owns_buffer }
 146     }
 147
 148     /// Return a pointer to the NUL-terminated string data.
 149     ///
 150     /// `.as_ptr` returns an internal pointer into the `CString`, and
 151     /// may be invalidated when the `CString` falls out of scope (the
 152     /// destructor will run, freeing the allocation if there is
 153     /// one).
 154     ///
 155     /// ```rust
 156     /// let foo = "some string";
 157     ///
 158     /// // right
 159     /// let x = foo.to_c_str();
 160     /// let p = x.as_ptr();
 161     ///
 162     /// // wrong (the CString will be freed, invalidating `p`)
 163     /// let p = foo.to_c_str().as_ptr();
 164     /// ```
 165     ///
 166     /// # Example
 167     ///
 168     /// ```rust
 169     /// extern crate libc;
 170     ///
 171     /// fn main() {
 172     ///     let c_str = "foo bar".to_c_str();
 173     ///     unsafe {
 174     ///         libc::puts(c_str.as_ptr());
 175     ///     }
 176     /// }
 177     /// ```
 178     pub fn as_ptr(&self) -> *const libc::c_char {
 179         self.buf
 180     }
 181
 182     /// Return a mutable pointer to the NUL-terminated string data.
 183     ///
 184     /// `.as_mut_ptr` returns an internal pointer into the `CString`, and
 185     /// may be invalidated when the `CString` falls out of scope (the
 186     /// destructor will run, freeing the allocation if there is
 187     /// one).
 188     ///
 189     /// ```rust
 190     /// let foo = "some string";
 191     ///
 192     /// // right
 193     /// let mut x = foo.to_c_str();
 194     /// let p = x.as_mut_ptr();
 195     ///
 196     /// // wrong (the CString will be freed, invalidating `p`)
 197     /// let p = foo.to_c_str().as_mut_ptr();
 198     /// ```
 199     pub fn as_mut_ptr(&mut self) -> *mut libc::c_char {
 200         self.buf as *mut _
 201     }
 202
 203     /// Returns whether or not the `CString` owns the buffer.
 204     pub fn owns_buffer(&self) -> bool {
 205         self.owns_buffer_
 206     }
 207
 208     /// Converts the CString into a `&[u8]` without copying.
 209     /// Includes the terminating NUL byte.
 210     #[inline]
 211     pub fn as_bytes<'a>(&'a self) -> &'a [u8] {
 212         unsafe {
 213             mem::transmute(Slice { data: self.buf, len: self.len() + 1 })
 214         }
 215     }
 216
 217     /// Converts the CString into a `&[u8]` without copying.
 218     /// Does not include the terminating NUL byte.
 219     #[inline]
 220     pub fn as_bytes_no_nul<'a>(&'a self) -> &'a [u8] {
 221         unsafe {
 222             mem::transmute(Slice { data: self.buf, len: self.len() })
 223         }
 224     }
 225
 226     /// Converts the CString into a `&str` without copying.
 227     /// Returns None if the CString is not UTF-8.
 228     #[inline]
 229     pub fn as_str<'a>(&'a self) -> Option<&'a str> {
 230         let buf = self.as_bytes_no_nul();
 231         str::from_utf8(buf)
 232     }
 233
 234     /// Return a CString iterator.
 235     pub fn iter<'a>(&'a self) -> CChars<'a> {
 236         CChars {
 237             ptr: self.buf,
 238             marker: marker::ContravariantLifetime,
 239         }
 240     }
 241
 242     /// Unwraps the wrapped `*libc::c_char` from the `CString` wrapper.
 243     ///
 244     /// Any ownership of the buffer by the `CString` wrapper is
 245     /// forgotten, meaning that the backing allocation of this
 246     /// `CString` is not automatically freed if it owns the
 247     /// allocation. In this case, a user of `.unwrap()` should ensure
 248     /// the allocation is freed, to avoid leaking memory. You should
 249     /// use libc's memory allocator in this case.
 250     ///
 251     /// Prefer `.as_ptr()` when just retrieving a pointer to the
 252     /// string data, as that does not relinquish ownership.
 253     pub unsafe fn into_inner(mut self) -> *const libc::c_char {
 254         self.owns_buffer_ = false;
 255         self.buf
 256     }
 257
 258     /// Deprecated, use into_inner() instead
 259     #[deprecated = "renamed to into_inner()"]
 260     pub unsafe fn unwrap(self) -> *const libc::c_char { self.into_inner() }
 261
 262     /// Return the number of bytes in the CString (not including the NUL
 263     /// terminator).
 264     #[inline]
 265     pub fn len(&self) -> uint {
 266         unsafe { libc::strlen(self.buf) as uint }
 267     }
 268
 269     /// Returns if there are no bytes in this string
 270     #[inline]
 271     pub fn is_empty(&self) -> bool { self.len() == 0 }
 272 }
 273
 274 impl Drop for CString {
 275     fn drop(&mut self) {
 276         if self.owns_buffer_ {
 277             unsafe {
 278                 libc::free(self.buf as *mut libc::c_void)
 279             }
 280         }
 281     }
 282 }
 283
 284 impl fmt::Show for CString {
 285     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 286         String::from_utf8_lossy(self.as_bytes_no_nul()).fmt(f)
 287     }
 288 }
 289
 290 /// A generic trait for converting a value to a CString.
 291 pub trait ToCStr for Sized? {
 292     /// Copy the receiver into a CString.
 293     ///
 294     /// # Panics
 295     ///
 296     /// Panics the task if the receiver has an interior null.
 297     fn to_c_str(&self) -> CString;
 298
 299     /// Unsafe variant of `to_c_str()` that doesn't check for nulls.
 300     unsafe fn to_c_str_unchecked(&self) -> CString;
 301
 302     /// Work with a temporary CString constructed from the receiver.
 303     /// The provided `*libc::c_char` will be freed immediately upon return.
 304     ///
 305     /// # Example
 306     ///
 307     /// ```rust
 308     /// extern crate libc;
 309     ///
 310     /// fn main() {
 311     ///     let s = "PATH".with_c_str(|path| unsafe {
 312     ///         libc::getenv(path)
 313     ///     });
 314     /// }
 315     /// ```
 316     ///
 317     /// # Panics
 318     ///
 319     /// Panics the task if the receiver has an interior null.
 320     #[inline]
 321     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
 322         let c_str = self.to_c_str();
 323         f(c_str.as_ptr())
 324     }
 325
 326     /// Unsafe variant of `with_c_str()` that doesn't check for nulls.
 327     #[inline]
 328     unsafe fn with_c_str_unchecked<T>(&self, f: |*const libc::c_char| -> T) -> T {
 329         let c_str = self.to_c_str_unchecked();
 330         f(c_str.as_ptr())
 331     }
 332 }
 333
 334 impl ToCStr for str {
 335     #[inline]
 336     fn to_c_str(&self) -> CString {
 337         self.as_bytes().to_c_str()
 338     }
 339
 340     #[inline]
 341     unsafe fn to_c_str_unchecked(&self) -> CString {
 342         self.as_bytes().to_c_str_unchecked()
 343     }
 344
 345     #[inline]
 346     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
 347         self.as_bytes().with_c_str(f)
 348     }
 349
 350     #[inline]
 351     unsafe fn with_c_str_unchecked<T>(&self, f: |*const libc::c_char| -> T) -> T {
 352         self.as_bytes().with_c_str_unchecked(f)
 353     }
 354 }
 355
 356 impl ToCStr for String {
 357     #[inline]
 358     fn to_c_str(&self) -> CString {
 359         self.as_bytes().to_c_str()
 360     }
 361
 362     #[inline]
 363     unsafe fn to_c_str_unchecked(&self) -> CString {
 364         self.as_bytes().to_c_str_unchecked()
 365     }
 366
 367     #[inline]
 368     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
 369         self.as_bytes().with_c_str(f)
 370     }
 371
 372     #[inline]
 373     unsafe fn with_c_str_unchecked<T>(&self, f: |*const libc::c_char| -> T) -> T {
 374         self.as_bytes().with_c_str_unchecked(f)
 375     }
 376 }
 377
 378 // The length of the stack allocated buffer for `vec.with_c_str()`
 379 const BUF_LEN: uint = 128;
 380
 381 impl ToCStr for [u8] {
 382     fn to_c_str(&self) -> CString {
 383         let mut cs = unsafe { self.to_c_str_unchecked() };
 384         check_for_null(self, cs.as_mut_ptr());
 385         cs
 386     }
 387
 388     unsafe fn to_c_str_unchecked(&self) -> CString {
 389         let self_len = self.len();
 390         let buf = libc::malloc(self_len as libc::size_t + 1) as *mut u8;
 391         if buf.is_null() { ::alloc::oom() }
 392
 393         ptr::copy_memory(buf, self.as_ptr(), self_len);
 394         *buf.offset(self_len as int) = 0;
 395
 396         CString::new(buf as *const libc::c_char, true)
 397     }
 398
 399     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
 400         unsafe { with_c_str(self, true, f) }
 401     }
 402
 403     unsafe fn with_c_str_unchecked<T>(&self, f: |*const libc::c_char| -> T) -> T {
 404         with_c_str(self, false, f)
 405     }
 406 }
 407
 408 impl<'a, Sized? T: ToCStr> ToCStr for &'a T {
 409     #[inline]
 410     fn to_c_str(&self) -> CString {
 411         (**self).to_c_str()
 412     }
 413
 414     #[inline]
 415     unsafe fn to_c_str_unchecked(&self) -> CString {
 416         (**self).to_c_str_unchecked()
 417     }
 418
 419     #[inline]
 420     fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
 421         (**self).with_c_str(f)
 422     }
 423
 424     #[inline]
 425     unsafe fn with_c_str_unchecked<T>(&self, f: |*const libc::c_char| -> T) -> T {
 426         (**self).with_c_str_unchecked(f)
 427     }
 428 }
 429
 430 // Unsafe function that handles possibly copying the &[u8] into a stack array.
 431 unsafe fn with_c_str<T>(v: &[u8], checked: bool,
 432                         f: |*const libc::c_char| -> T) -> T {
 433     let c_str = if v.len() < BUF_LEN {
 434         let mut buf: [u8, .. BUF_LEN] = mem::uninitialized();
 435         slice::bytes::copy_memory(&mut buf, v);
 436         buf[v.len()] = 0;
 437
 438         let buf = buf.as_mut_ptr();
 439         if checked {
 440             check_for_null(v, buf as *mut libc::c_char);
 441         }
 442
 443         return f(buf as *const libc::c_char)
 444     } else if checked {
 445         v.to_c_str()
 446     } else {
 447         v.to_c_str_unchecked()
 448     };
 449
 450     f(c_str.as_ptr())
 451 }
 452
 453 #[inline]
 454 fn check_for_null(v: &[u8], buf: *mut libc::c_char) {
 455     for i in range(0, v.len()) {
 456         unsafe {
 457             let p = buf.offset(i as int);
 458             assert!(*p != 0);
 459         }
 460     }
 461 }
 462
 463 /// External iterator for a CString's bytes.
 464 ///
 465 /// Use with the `std::iter` module.
 466 pub struct CChars<'a> {
 467     ptr: *const libc::c_char,
 468     marker: marker::ContravariantLifetime<'a>,
 469 }
 470
 471 impl<'a> Iterator<libc::c_char> for CChars<'a> {
 472     fn next(&mut self) -> Option<libc::c_char> {
 473         let ch = unsafe { *self.ptr };
 474         if ch == 0 {
 475             None
 476         } else {
 477             self.ptr = unsafe { self.ptr.offset(1) };
 478             Some(ch)
 479         }
 480     }
 481 }
 482
 483 /// Parses a C "multistring", eg windows env values or
 484 /// the req->ptr result in a uv_fs_readdir() call.
 485 ///
 486 /// Optionally, a `count` can be passed in, limiting the
 487 /// parsing to only being done `count`-times.
 488 ///
 489 /// The specified closure is invoked with each string that
 490 /// is found, and the number of strings found is returned.
 491 pub unsafe fn from_c_multistring(buf: *const libc::c_char,
 492                                  count: Option<uint>,
 493                                  f: |&CString|) -> uint {
 494
 495     let mut curr_ptr: uint = buf as uint;
 496     let mut ctr = 0;
 497     let (limited_count, limit) = match count {
 498         Some(limit) => (true, limit),
 499         None => (false, 0)
 500     };
 501     while ((limited_count && ctr < limit) || !limited_count)
 502           && *(curr_ptr as *const libc::c_char) != 0 as libc::c_char {
 503         let cstr = CString::new(curr_ptr as *const libc::c_char, false);
 504         f(&cstr);
 505         curr_ptr += cstr.len() + 1;
 506         ctr += 1;
 507     }
 508     return ctr;
 509 }
 510
 511 #[cfg(test)]
 512 mod tests {
 513     use std::prelude::*;
 514     use std::ptr;
 515     use std::task;
 516     use libc;
 517
 518     use super::*;
 519
 520     #[test]
 521     fn test_str_multistring_parsing() {
 522         unsafe {
 523             let input = b"zero\0one\0\0";
 524             let ptr = input.as_ptr();
 525             let expected = ["zero", "one"];
 526             let mut it = expected.iter();
 527             let result = from_c_multistring(ptr as *const libc::c_char, None, |c| {
 528                 let cbytes = c.as_bytes_no_nul();
 529                 assert_eq!(cbytes, it.next().unwrap().as_bytes());
 530             });
 531             assert_eq!(result, 2);
 532             assert!(it.next().is_none());
 533         }
 534     }
 535
 536     #[test]
 537     fn test_str_to_c_str() {
 538         let c_str = "".to_c_str();
 539         unsafe {
 540             assert_eq!(*c_str.as_ptr().offset(0), 0);
 541         }
 542
 543         let c_str = "hello".to_c_str();
 544         let buf = c_str.as_ptr();
 545         unsafe {
 546             assert_eq!(*buf.offset(0), 'h' as libc::c_char);
 547             assert_eq!(*buf.offset(1), 'e' as libc::c_char);
 548             assert_eq!(*buf.offset(2), 'l' as libc::c_char);
 549             assert_eq!(*buf.offset(3), 'l' as libc::c_char);
 550             assert_eq!(*buf.offset(4), 'o' as libc::c_char);
 551             assert_eq!(*buf.offset(5), 0);
 552         }
 553     }
 554
 555     #[test]
 556     fn test_vec_to_c_str() {
 557         let b: &[u8] = &[];
 558         let c_str = b.to_c_str();
 559         unsafe {
 560             assert_eq!(*c_str.as_ptr().offset(0), 0);
 561         }
 562
 563         let c_str = b"hello".to_c_str();
 564         let buf = c_str.as_ptr();
 565         unsafe {
 566             assert_eq!(*buf.offset(0), 'h' as libc::c_char);
 567             assert_eq!(*buf.offset(1), 'e' as libc::c_char);
 568             assert_eq!(*buf.offset(2), 'l' as libc::c_char);
 569             assert_eq!(*buf.offset(3), 'l' as libc::c_char);
 570             assert_eq!(*buf.offset(4), 'o' as libc::c_char);
 571             assert_eq!(*buf.offset(5), 0);
 572         }
 573
 574         let c_str = b"foo\xFF".to_c_str();
 575         let buf = c_str.as_ptr();
 576         unsafe {
 577             assert_eq!(*buf.offset(0), 'f' as libc::c_char);
 578             assert_eq!(*buf.offset(1), 'o' as libc::c_char);
 579             assert_eq!(*buf.offset(2), 'o' as libc::c_char);
 580             assert_eq!(*buf.offset(3), 0xffu8 as i8);
 581             assert_eq!(*buf.offset(4), 0);
 582         }
 583     }
 584
 585     #[test]
 586     fn test_unwrap() {
 587         let c_str = "hello".to_c_str();
 588         unsafe { libc::free(c_str.unwrap() as *mut libc::c_void) }
 589     }
 590
 591     #[test]
 592     fn test_as_ptr() {
 593         let c_str = "hello".to_c_str();
 594         let len = unsafe { libc::strlen(c_str.as_ptr()) };
 595         assert_eq!(len, 5);
 596     }
 597
 598     #[test]
 599     fn test_iterator() {
 600         let c_str = "".to_c_str();
 601         let mut iter = c_str.iter();
 602         assert_eq!(iter.next(), None);
 603
 604         let c_str = "hello".to_c_str();
 605         let mut iter = c_str.iter();
 606         assert_eq!(iter.next(), Some('h' as libc::c_char));
 607         assert_eq!(iter.next(), Some('e' as libc::c_char));
 608         assert_eq!(iter.next(), Some('l' as libc::c_char));
 609         assert_eq!(iter.next(), Some('l' as libc::c_char));
 610         assert_eq!(iter.next(), Some('o' as libc::c_char));
 611         assert_eq!(iter.next(), None);
 612     }
 613
 614     #[test]
 615     fn test_to_c_str_fail() {
 616         assert!(task::try(proc() { "he\x00llo".to_c_str() }).is_err());
 617     }
 618
 619     #[test]
 620     fn test_to_c_str_unchecked() {
 621         unsafe {
 622             let c_string = "he\x00llo".to_c_str_unchecked();
 623             let buf = c_string.as_ptr();
 624             assert_eq!(*buf.offset(0), 'h' as libc::c_char);
 625             assert_eq!(*buf.offset(1), 'e' as libc::c_char);
 626             assert_eq!(*buf.offset(2), 0);
 627             assert_eq!(*buf.offset(3), 'l' as libc::c_char);
 628             assert_eq!(*buf.offset(4), 'l' as libc::c_char);
 629             assert_eq!(*buf.offset(5), 'o' as libc::c_char);
 630             assert_eq!(*buf.offset(6), 0);
 631         }
 632     }
 633
 634     #[test]
 635     fn test_as_bytes() {
 636         let c_str = "hello".to_c_str();
 637         assert_eq!(c_str.as_bytes(), b"hello\0");
 638         let c_str = "".to_c_str();
 639         assert_eq!(c_str.as_bytes(), b"\0");
 640         let c_str = b"foo\xFF".to_c_str();
 641         assert_eq!(c_str.as_bytes(), b"foo\xFF\0");
 642     }
 643
 644     #[test]
 645     fn test_as_bytes_no_nul() {
 646         let c_str = "hello".to_c_str();
 647         assert_eq!(c_str.as_bytes_no_nul(), b"hello");
 648         let c_str = "".to_c_str();
 649         let exp: &[u8] = &[];
 650         assert_eq!(c_str.as_bytes_no_nul(), exp);
 651         let c_str = b"foo\xFF".to_c_str();
 652         assert_eq!(c_str.as_bytes_no_nul(), b"foo\xFF");
 653     }
 654
 655     #[test]
 656     fn test_as_str() {
 657         let c_str = "hello".to_c_str();
 658         assert_eq!(c_str.as_str(), Some("hello"));
 659         let c_str = "".to_c_str();
 660         assert_eq!(c_str.as_str(), Some(""));
 661         let c_str = b"foo\xFF".to_c_str();
 662         assert_eq!(c_str.as_str(), None);
 663     }
 664
 665     #[test]
 666     #[should_fail]
 667     fn test_new_fail() {
 668         let _c_str = unsafe { CString::new(ptr::null(), false) };
 669     }
 670
 671     #[test]
 672     fn test_clone() {
 673         let a = "hello".to_c_str();
 674         let b = a.clone();
 675         assert!(a == b);
 676     }
 677
 678     #[test]
 679     fn test_clone_noleak() {
 680         fn foo(f: |c: &CString|) {
 681             let s = "test".to_string();
 682             let c = s.to_c_str();
 683             // give the closure a non-owned CString
 684             let mut c_ = unsafe { CString::new(c.as_ptr(), false) };
 685             f(&c_);
 686             // muck with the buffer for later printing
 687             unsafe { *c_.as_mut_ptr() = 'X' as libc::c_char }
 688         }
 689
 690         let mut c_: Option<CString> = None;
 691         foo(|c| {
 692             c_ = Some(c.clone());
 693             c.clone();
 694             // force a copy, reading the memory
 695             c.as_bytes().to_vec();
 696         });
 697         let c_ = c_.unwrap();
 698         // force a copy, reading the memory
 699         c_.as_bytes().to_vec();
 700     }
 701 }
 702
 703 #[cfg(test)]
 704 mod bench {
 705     use test::Bencher;
 706     use libc;
 707     use std::prelude::*;
 708
 709     #[inline]
 710     fn check(s: &str, c_str: *const libc::c_char) {
 711         let s_buf = s.as_ptr();
 712         for i in range(0, s.len()) {
 713             unsafe {
 714                 assert_eq!(
 715                     *s_buf.offset(i as int) as libc::c_char,
 716                     *c_str.offset(i as int));
 717             }
 718         }
 719     }
 720
 721     static S_SHORT: &'static str = "Mary";
 722     static S_MEDIUM: &'static str = "Mary had a little lamb";
 723     static S_LONG: &'static str = "\
 724         Mary had a little lamb, Little lamb
 725         Mary had a little lamb, Little lamb
 726         Mary had a little lamb, Little lamb
 727         Mary had a little lamb, Little lamb
 728         Mary had a little lamb, Little lamb
 729         Mary had a little lamb, Little lamb";
 730
 731     fn bench_to_string(b: &mut Bencher, s: &str) {
 732         b.iter(|| {
 733             let c_str = s.to_c_str();
 734             check(s, c_str.as_ptr());
 735         })
 736     }
 737
 738     #[bench]
 739     fn bench_to_c_str_short(b: &mut Bencher) {
 740         bench_to_string(b, S_SHORT)
 741     }
 742
 743     #[bench]
 744     fn bench_to_c_str_medium(b: &mut Bencher) {
 745         bench_to_string(b, S_MEDIUM)
 746     }
 747
 748     #[bench]
 749     fn bench_to_c_str_long(b: &mut Bencher) {
 750         bench_to_string(b, S_LONG)
 751     }
 752
 753     fn bench_to_c_str_unchecked(b: &mut Bencher, s: &str) {
 754         b.iter(|| {
 755             let c_str = unsafe { s.to_c_str_unchecked() };
 756             check(s, c_str.as_ptr())
 757         })
 758     }
 759
 760     #[bench]
 761     fn bench_to_c_str_unchecked_short(b: &mut Bencher) {
 762         bench_to_c_str_unchecked(b, S_SHORT)
 763     }
 764
 765     #[bench]
 766     fn bench_to_c_str_unchecked_medium(b: &mut Bencher) {
 767         bench_to_c_str_unchecked(b, S_MEDIUM)
 768     }
 769
 770     #[bench]
 771     fn bench_to_c_str_unchecked_long(b: &mut Bencher) {
 772         bench_to_c_str_unchecked(b, S_LONG)
 773     }
 774
 775     fn bench_with_c_str(b: &mut Bencher, s: &str) {
 776         b.iter(|| {
 777             s.with_c_str(|c_str_buf| check(s, c_str_buf))
 778         })
 779     }
 780
 781     #[bench]
 782     fn bench_with_c_str_short(b: &mut Bencher) {
 783         bench_with_c_str(b, S_SHORT)
 784     }
 785
 786     #[bench]
 787     fn bench_with_c_str_medium(b: &mut Bencher) {
 788         bench_with_c_str(b, S_MEDIUM)
 789     }
 790
 791     #[bench]
 792     fn bench_with_c_str_long(b: &mut Bencher) {
 793         bench_with_c_str(b, S_LONG)
 794     }
 795
 796     fn bench_with_c_str_unchecked(b: &mut Bencher, s: &str) {
 797         b.iter(|| {
 798             unsafe {
 799                 s.with_c_str_unchecked(|c_str_buf| check(s, c_str_buf))
 800             }
 801         })
 802     }
 803
 804     #[bench]
 805     fn bench_with_c_str_unchecked_short(b: &mut Bencher) {
 806         bench_with_c_str_unchecked(b, S_SHORT)
 807     }
 808
 809     #[bench]
 810     fn bench_with_c_str_unchecked_medium(b: &mut Bencher) {
 811         bench_with_c_str_unchecked(b, S_MEDIUM)
 812     }
 813
 814     #[bench]
 815     fn bench_with_c_str_unchecked_long(b: &mut Bencher) {
 816         bench_with_c_str_unchecked(b, S_LONG)
 817     }
 818 }