2014-11-25 13:28:35 -08:00
|
|
|
// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
|
|
|
|
// file at the top-level directory of this distribution and at
|
|
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
|
|
//
|
|
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
|
|
// option. This file may not be copied, modified, or distributed
|
|
|
|
// except according to those terms.
|
|
|
|
|
|
|
|
use fmt;
|
|
|
|
use iter::IteratorExt;
|
|
|
|
use libc;
|
|
|
|
use mem;
|
|
|
|
use ops::Deref;
|
|
|
|
use slice::{self, SliceExt, AsSlice};
|
|
|
|
use string::String;
|
|
|
|
use vec::Vec;
|
|
|
|
|
|
|
|
/// A type representing a C-compatible string
|
|
|
|
///
|
|
|
|
/// This type serves the primary purpose of being able to generate a
|
|
|
|
/// C-compatible string from a Rust byte slice or vector. An instance of this
|
|
|
|
/// type is a static guarantee that the underlying bytes contain no interior 0
|
|
|
|
/// bytes and the final byte is 0.
|
|
|
|
///
|
|
|
|
/// A `CString` is created from either a byte slice or a byte vector. After
|
|
|
|
/// being created, a `CString` predominately inherits all of its methods from
|
|
|
|
/// the `Deref` implementation to `[libc::c_char]`. Note that the underlying
|
|
|
|
/// array is represented as an array of `libc::c_char` as opposed to `u8`. A
|
|
|
|
/// `u8` slice can be obtained with the `as_bytes` method. Slices produced from
|
|
|
|
/// a `CString` do *not* contain the trailing nul terminator unless otherwise
|
|
|
|
/// specified.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```no_run
|
|
|
|
/// # extern crate libc;
|
|
|
|
/// # fn main() {
|
|
|
|
/// use std::ffi::CString;
|
|
|
|
/// use libc;
|
|
|
|
///
|
|
|
|
/// extern {
|
|
|
|
/// fn my_printer(s: *const libc::c_char);
|
|
|
|
/// }
|
|
|
|
///
|
|
|
|
/// let to_print = "Hello, world!";
|
|
|
|
/// let c_to_print = CString::from_slice(to_print.as_bytes());
|
|
|
|
/// unsafe {
|
|
|
|
/// my_printer(c_to_print.as_ptr());
|
|
|
|
/// }
|
|
|
|
/// # }
|
|
|
|
/// ```
|
|
|
|
#[derive(Clone, PartialEq, PartialOrd, Eq, Ord, Hash)]
|
|
|
|
pub struct CString {
|
|
|
|
inner: Vec<libc::c_char>,
|
|
|
|
}
|
|
|
|
|
|
|
|
impl CString {
|
|
|
|
/// Create a new C-compatible string from a byte slice.
|
|
|
|
///
|
|
|
|
/// This method will copy the data of the slice provided into a new
|
|
|
|
/// allocation, ensuring that there is a trailing 0 byte.
|
|
|
|
///
|
|
|
|
/// # Panics
|
|
|
|
///
|
|
|
|
/// This function will panic if there are any 0 bytes already in the slice
|
|
|
|
/// provided.
|
|
|
|
pub fn from_slice(v: &[u8]) -> CString {
|
|
|
|
CString::from_vec(v.to_vec())
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Create a C-compatible string from a byte vector.
|
|
|
|
///
|
|
|
|
/// This method will consume ownership of the provided vector, appending a 0
|
|
|
|
/// byte to the end after verifying that there are no interior 0 bytes.
|
|
|
|
///
|
|
|
|
/// # Panics
|
|
|
|
///
|
|
|
|
/// This function will panic if there are any 0 bytes already in the vector
|
|
|
|
/// provided.
|
|
|
|
pub fn from_vec(v: Vec<u8>) -> CString {
|
|
|
|
assert!(!v.iter().any(|&x| x == 0));
|
|
|
|
unsafe { CString::from_vec_unchecked(v) }
|
|
|
|
}
|
|
|
|
|
2015-01-07 21:47:15 -08:00
|
|
|
/// Create a C-compatible string from a byte vector without checking for
|
2014-11-25 13:28:35 -08:00
|
|
|
/// interior 0 bytes.
|
|
|
|
///
|
|
|
|
/// This method is equivalent to `from_vec` except that no runtime assertion
|
|
|
|
/// is made that `v` contains no 0 bytes.
|
|
|
|
pub unsafe fn from_vec_unchecked(mut v: Vec<u8>) -> CString {
|
|
|
|
v.push(0);
|
|
|
|
CString { inner: mem::transmute(v) }
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Create a view into this C string which includes the trailing nul
|
|
|
|
/// terminator at the end of the string.
|
|
|
|
pub fn as_slice_with_nul(&self) -> &[libc::c_char] { self.inner.as_slice() }
|
|
|
|
|
|
|
|
/// Similar to the `as_slice` method, but returns a `u8` slice instead of a
|
|
|
|
/// `libc::c_char` slice.
|
|
|
|
pub fn as_bytes(&self) -> &[u8] {
|
|
|
|
unsafe { mem::transmute(self.as_slice()) }
|
|
|
|
}
|
|
|
|
|
2015-01-06 20:53:18 -05:00
|
|
|
/// Equivalent to `as_slice_with_nul` except that the type returned is a
|
2014-11-25 13:28:35 -08:00
|
|
|
/// `u8` slice instead of a `libc::c_char` slice.
|
|
|
|
pub fn as_bytes_with_nul(&self) -> &[u8] {
|
|
|
|
unsafe { mem::transmute(self.as_slice_with_nul()) }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl Deref for CString {
|
|
|
|
type Target = [libc::c_char];
|
|
|
|
|
|
|
|
fn deref(&self) -> &[libc::c_char] {
|
2015-01-17 16:15:52 -08:00
|
|
|
&self.inner[..(self.inner.len() - 1)]
|
2014-11-25 13:28:35 -08:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2015-01-24 09:15:42 -08:00
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
2015-01-20 15:45:07 -08:00
|
|
|
impl fmt::Debug for CString {
|
2014-11-25 13:28:35 -08:00
|
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
std: Stabilize the std::fmt module
This commit performs a final stabilization pass over the std::fmt module,
marking all necessary APIs as stable. One of the more interesting aspects of
this module is that it exposes a good deal of its runtime representation to the
outside world in order for `format_args!` to be able to construct the format
strings. Instead of hacking the compiler to assume that these items are stable,
this commit instead lays out a story for the stabilization and evolution of
these APIs.
There are three primary details used by the `format_args!` macro:
1. `Arguments` - an opaque package of a "compiled format string". This structure
is passed around and the `write` function is the source of truth for
transforming a compiled format string into a string at runtime. This must be
able to be constructed in stable code.
2. `Argument` - an opaque structure representing an argument to a format string.
This is *almost* a trait object as it's just a pointer/function pair, but due
to the function originating from one of many traits, it's not actually a
trait object. Like `Arguments`, this must be constructed from stable code.
3. `fmt::rt` - this module contains the runtime type definitions primarily for
the `rt::Argument` structure. Whenever an argument is formatted with
nonstandard flags, a corresponding `rt::Argument` is generated describing how
the argument is being formatted. This can be used to construct an
`Arguments`.
The primary interface to `std::fmt` is the `Arguments` structure, and as such
this type name is stabilize as-is today. It is expected for libraries to pass
around an `Arguments` structure to represent a pending formatted computation.
The remaining portions are largely "cruft" which would rather not be stabilized,
but due to the stability checks they must be. As a result, almost all pieces
have been renamed to represent that they are "version 1" of the formatting
representation. The theory is that at a later date if we change the
representation of these types we can add new definitions called "version 2" and
corresponding constructors for `Arguments`.
One of the other remaining large questions about the fmt module were how the
pending I/O reform would affect the signatures of methods in the module. Due to
[RFC 526][rfc], however, the writers of fmt are now incompatible with the
writers of io, so this question has largely been solved. As a result the
interfaces are largely stabilized as-is today.
[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0526-fmt-text-writer.md
Specifically, the following changes were made:
* The contents of `fmt::rt` were all moved under `fmt::rt::v1`
* `fmt::rt` is stable
* `fmt::rt::v1` is stable
* `Error` is stable
* `Writer` is stable
* `Writer::write_str` is stable
* `Writer::write_fmt` is stable
* `Formatter` is stable
* `Argument` has been renamed to `ArgumentV1` and is stable
* `ArgumentV1::new` is stable
* `ArgumentV1::from_uint` is stable
* `Arguments::new_v1` is stable (renamed from `new`)
* `Arguments::new_v1_formatted` is stable (renamed from `with_placeholders`)
* All formatting traits are now stable, as well as the `fmt` method.
* `fmt::write` is stable
* `fmt::format` is stable
* `Formatter::pad_integral` is stable
* `Formatter::pad` is stable
* `Formatter::write_str` is stable
* `Formatter::write_fmt` is stable
* Some assorted top level items which were only used by `format_args!` were
removed in favor of static functions on `ArgumentV1` as well.
* The formatting-flag-accessing methods remain unstable
Within the contents of the `fmt::rt::v1` module, the following actions were
taken:
* Reexports of all enum variants were removed
* All prefixes on enum variants were removed
* A few miscellaneous enum variants were renamed
* Otherwise all structs, fields, and variants were marked stable.
In addition to these actions in the `std::fmt` module, many implementations of
`Show` and `String` were stabilized as well.
In some other modules:
* `ToString` is now stable
* `ToString::to_string` is now stable
* `Vec` no longer implements `fmt::Writer` (this has moved to `String`)
This is a breaking change due to all of the changes to the `fmt::rt` module, but
this likely will not have much impact on existing programs.
Closes #20661
[breaking-change]
2015-01-13 15:42:53 -08:00
|
|
|
fmt::Debug::fmt(&String::from_utf8_lossy(self.as_bytes()), f)
|
2014-11-25 13:28:35 -08:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Interpret a C string as a byte slice.
|
|
|
|
///
|
|
|
|
/// This function will calculate the length of the C string provided, and it
|
|
|
|
/// will then return a corresponding slice for the contents of the C string not
|
|
|
|
/// including the nul terminator.
|
|
|
|
///
|
|
|
|
/// This function will tie the lifetime of the returned slice to the lifetime of
|
|
|
|
/// the pointer provided. This is done to help prevent the slice from escaping
|
|
|
|
/// the lifetime of the pointer itself. If a longer lifetime is needed, then
|
|
|
|
/// `mem::copy_lifetime` should be used.
|
|
|
|
///
|
|
|
|
/// This function is unsafe because there is no guarantee of the validity of the
|
|
|
|
/// pointer `raw` or a guarantee that a nul terminator will be found.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// ```no_run
|
|
|
|
/// # extern crate libc;
|
|
|
|
/// # fn main() {
|
|
|
|
/// use std::ffi;
|
|
|
|
/// use std::str;
|
|
|
|
/// use libc;
|
|
|
|
///
|
|
|
|
/// extern {
|
|
|
|
/// fn my_string() -> *const libc::c_char;
|
|
|
|
/// }
|
|
|
|
///
|
|
|
|
/// unsafe {
|
|
|
|
/// let to_print = my_string();
|
|
|
|
/// let slice = ffi::c_str_to_bytes(&to_print);
|
|
|
|
/// println!("string returned: {}", str::from_utf8(slice).unwrap());
|
|
|
|
/// }
|
|
|
|
/// # }
|
|
|
|
/// ```
|
|
|
|
pub unsafe fn c_str_to_bytes<'a>(raw: &'a *const libc::c_char) -> &'a [u8] {
|
|
|
|
let len = libc::strlen(*raw);
|
|
|
|
slice::from_raw_buf(&*(raw as *const _ as *const *const u8), len as uint)
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Interpret a C string as a byte slice with the nul terminator.
|
|
|
|
///
|
|
|
|
/// This function is identical to `from_raw_buf` except that the returned slice
|
|
|
|
/// will include the nul terminator of the string.
|
|
|
|
pub unsafe fn c_str_to_bytes_with_nul<'a>(raw: &'a *const libc::c_char) -> &'a [u8] {
|
|
|
|
let len = libc::strlen(*raw) + 1;
|
|
|
|
slice::from_raw_buf(&*(raw as *const _ as *const *const u8), len as uint)
|
|
|
|
}
|
|
|
|
|
|
|
|
#[cfg(test)]
|
|
|
|
mod tests {
|
|
|
|
use prelude::v1::*;
|
|
|
|
use super::*;
|
|
|
|
use libc;
|
|
|
|
use mem;
|
|
|
|
|
|
|
|
#[test]
|
|
|
|
fn c_to_rust() {
|
|
|
|
let data = b"123\0";
|
|
|
|
let ptr = data.as_ptr() as *const libc::c_char;
|
|
|
|
unsafe {
|
|
|
|
assert_eq!(c_str_to_bytes(&ptr), b"123");
|
|
|
|
assert_eq!(c_str_to_bytes_with_nul(&ptr), b"123\0");
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
#[test]
|
|
|
|
fn simple() {
|
|
|
|
let s = CString::from_slice(b"1234");
|
|
|
|
assert_eq!(s.as_bytes(), b"1234");
|
|
|
|
assert_eq!(s.as_bytes_with_nul(), b"1234\0");
|
|
|
|
unsafe {
|
|
|
|
assert_eq!(s.as_slice(),
|
|
|
|
mem::transmute::<_, &[libc::c_char]>(b"1234"));
|
|
|
|
assert_eq!(s.as_slice_with_nul(),
|
|
|
|
mem::transmute::<_, &[libc::c_char]>(b"1234\0"));
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
#[should_fail] #[test]
|
|
|
|
fn build_with_zero1() { CString::from_slice(b"\0"); }
|
|
|
|
#[should_fail] #[test]
|
|
|
|
fn build_with_zero2() { CString::from_vec(vec![0]); }
|
|
|
|
|
|
|
|
#[test]
|
|
|
|
fn build_with_zero3() {
|
|
|
|
unsafe {
|
|
|
|
let s = CString::from_vec_unchecked(vec![0]);
|
|
|
|
assert_eq!(s.as_bytes(), b"\0");
|
|
|
|
}
|
|
|
|
}
|
2015-01-20 15:45:07 -08:00
|
|
|
|
|
|
|
#[test]
|
|
|
|
fn formatted() {
|
|
|
|
let s = CString::from_slice(b"12");
|
|
|
|
assert_eq!(format!("{:?}", s), "\"12\"");
|
|
|
|
}
|
2014-11-25 13:28:35 -08:00
|
|
|
}
|