src/libstd/sys/unix/ext/ffi.rs

   1 // Copyright 2015 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 //! Unix-specific extension to the primitives in the `std::ffi` module
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use ffi::{OsStr, OsString};
  16 use mem;
  17 use sys::os_str::Buf;
  18 use sys_common::{FromInner, IntoInner, AsInner};
  19
  20 /// Unix-specific extensions to [`OsString`].
  21 ///
  22 /// [`OsString`]: ../../../../std/ffi/struct.OsString.html
  23 #[stable(feature = "rust1", since = "1.0.0")]
  24 pub trait OsStringExt {
  25     /// Creates an [`OsString`] from a byte vector.
  26     ///
  27     /// # Examples
  28     ///
  29     /// ```
  30     /// use std::ffi::OsString;
  31     /// use std::os::unix::ffi::OsStringExt;
  32     ///
  33     /// let bytes = b"foo".to_vec();
  34     /// let os_string = OsString::from_vec(bytes);
  35     /// assert_eq!(os_string.to_str(), Some("foo"));
  36     /// ```
  37     ///
  38     /// [`OsString`]: ../../../ffi/struct.OsString.html
  39     #[stable(feature = "rust1", since = "1.0.0")]
  40     fn from_vec(vec: Vec<u8>) -> Self;
  41
  42     /// Yields the underlying byte vector of this [`OsString`].
  43     ///
  44     /// # Examples
  45     ///
  46     /// ```
  47     /// use std::ffi::OsString;
  48     /// use std::os::unix::ffi::OsStringExt;
  49     ///
  50     /// let mut os_string = OsString::new();
  51     /// os_string.push("foo");
  52     /// let bytes = os_string.into_vec();
  53     /// assert_eq!(bytes, b"foo");
  54     /// ```
  55     ///
  56     /// [`OsString`]: ../../../ffi/struct.OsString.html
  57     #[stable(feature = "rust1", since = "1.0.0")]
  58     fn into_vec(self) -> Vec<u8>;
  59 }
  60
  61 #[stable(feature = "rust1", since = "1.0.0")]
  62 impl OsStringExt for OsString {
  63     fn from_vec(vec: Vec<u8>) -> OsString {
  64         FromInner::from_inner(Buf { inner: vec })
  65     }
  66     fn into_vec(self) -> Vec<u8> {
  67         self.into_inner().inner
  68     }
  69 }
  70
  71 /// Unix-specific extensions to [`OsStr`].
  72 ///
  73 /// [`OsStr`]: ../../../../std/ffi/struct.OsStr.html
  74 #[stable(feature = "rust1", since = "1.0.0")]
  75 pub trait OsStrExt {
  76     #[stable(feature = "rust1", since = "1.0.0")]
  77     /// Creates an [`OsStr`] from a byte slice.
  78     ///
  79     /// # Examples
  80     ///
  81     /// ```
  82     /// use std::ffi::OsStr;
  83     /// use std::os::unix::ffi::OsStrExt;
  84     ///
  85     /// let bytes = b"foo";
  86     /// let os_str = OsStr::from_bytes(bytes);
  87     /// assert_eq!(os_str.to_str(), Some("foo"));
  88     /// ```
  89     ///
  90     /// [`OsStr`]: ../../../ffi/struct.OsStr.html
  91     fn from_bytes(slice: &[u8]) -> &Self;
  92
  93     /// Gets the underlying byte view of the [`OsStr`] slice.
  94     ///
  95     /// # Examples
  96     ///
  97     /// ```
  98     /// use std::ffi::OsStr;
  99     /// use std::os::unix::ffi::OsStrExt;
 100     ///
 101     /// let mut os_str = OsStr::new("foo");
 102     /// let bytes = os_str.as_bytes();
 103     /// assert_eq!(bytes, b"foo");
 104     /// ```
 105     ///
 106     /// [`OsStr`]: ../../../ffi/struct.OsStr.html
 107     #[stable(feature = "rust1", since = "1.0.0")]
 108     fn as_bytes(&self) -> &[u8];
 109 }
 110
 111 #[stable(feature = "rust1", since = "1.0.0")]
 112 impl OsStrExt for OsStr {
 113     fn from_bytes(slice: &[u8]) -> &OsStr {
 114         unsafe { mem::transmute(slice) }
 115     }
 116     fn as_bytes(&self) -> &[u8] {
 117         &self.as_inner().inner
 118     }
 119 }