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.
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.
11 use borrow::{Borrow, Cow};
15 use hash::{Hash, Hasher};
19 use sys::os_str::{Buf, Slice};
20 use sys_common::{AsInner, IntoInner, FromInner};
22 /// A type that can represent owned, mutable platform-native strings, but is
23 /// cheaply inter-convertible with Rust strings.
25 /// The need for this type arises from the fact that:
27 /// * On Unix systems, strings are often arbitrary sequences of non-zero
28 /// bytes, in many cases interpreted as UTF-8.
30 /// * On Windows, strings are often arbitrary sequences of non-zero 16-bit
31 /// values, interpreted as UTF-16 when it is valid to do so.
33 /// * In Rust, strings are always valid UTF-8, which may contain zeros.
35 /// `OsString` and [`OsStr`] bridge this gap by simultaneously representing Rust
36 /// and platform-native string values, and in particular allowing a Rust string
37 /// to be converted into an "OS" string with no cost if possible.
39 /// `OsString` is to [`&OsStr`] as [`String`] is to [`&str`]: the former
40 /// in each pair are owned strings; the latter are borrowed
43 /// # Creating an `OsString`
45 /// **From a Rust string**: `OsString` implements
46 /// [`From`]`<`[`String`]`>`, so you can use `my_string.from` to
47 /// create an `OsString` from a normal Rust string.
49 /// **From slices:** Just like you can start with an empty Rust
50 /// [`String`] and then [`push_str`][String.push_str] `&str`
51 /// sub-string slices into it, you can create an empty `OsString` with
52 /// the [`new`] method and then push string slices into it with the
55 /// # Extracting a borrowed reference to the whole OS string
57 /// You can use the [`as_os_str`] method to get an `&`[`OsStr`] from
58 /// an `OsString`; this is effectively a borrowed reference to the
63 /// See the [module's toplevel documentation about conversions][conversions] for a discussion on
64 /// the traits which `OsString` implements for [conversions] from/to native representations.
66 /// [`OsStr`]: struct.OsStr.html
67 /// [`&OsStr`]: struct.OsStr.html
68 /// [`From`]: ../convert/trait.From.html
69 /// [`String`]: ../string/struct.String.html
70 /// [`&str`]: ../primitive.str.html
71 /// [`u8`]: ../primitive.u8.html
72 /// [`u16`]: ../primitive.u16.html
73 /// [String.push_str]: ../string/struct.String.html#method.push_str
74 /// [`new`]: #method.new
75 /// [`push`]: #method.push
76 /// [`as_os_str`]: #method.as_os_str
77 /// [conversions]: index.html#conversions
79 #[stable(feature = "rust1", since = "1.0.0")]
84 /// Borrowed reference to an OS string (see [`OsString`]).
86 /// This type represents a borrowed reference to a string in the operating system's preferred
89 /// `&OsStr` is to [`OsString`] as [`&str`] is to [`String`]: the former in each pair are borrowed
90 /// references; the latter are owned strings.
92 /// See the [module's toplevel documentation about conversions][conversions] for a discussion on
93 /// the traits which `OsStr` implements for [conversions] from/to native representations.
95 /// [`OsString`]: struct.OsString.html
96 /// [`&str`]: ../primitive.str.html
97 /// [`String`]: ../string/struct.String.html
98 /// [conversions]: index.html#conversions
99 #[stable(feature = "rust1", since = "1.0.0")]
105 /// Constructs a new empty `OsString`.
110 /// use std::ffi::OsString;
112 /// let os_string = OsString::new();
114 #[stable(feature = "rust1", since = "1.0.0")]
115 pub fn new() -> OsString {
116 OsString { inner: Buf::from_string(String::new()) }
119 /// Converts to an [`OsStr`] slice.
121 /// [`OsStr`]: struct.OsStr.html
126 /// use std::ffi::{OsString, OsStr};
128 /// let os_string = OsString::from("foo");
129 /// let os_str = OsStr::new("foo");
130 /// assert_eq!(os_string.as_os_str(), os_str);
132 #[stable(feature = "rust1", since = "1.0.0")]
133 pub fn as_os_str(&self) -> &OsStr {
137 /// Converts the `OsString` into a [`String`] if it contains valid Unicode data.
139 /// On failure, ownership of the original `OsString` is returned.
141 /// [`String`]: ../../std/string/struct.String.html
146 /// use std::ffi::OsString;
148 /// let os_string = OsString::from("foo");
149 /// let string = os_string.into_string();
150 /// assert_eq!(string, Ok(String::from("foo")));
152 #[stable(feature = "rust1", since = "1.0.0")]
153 pub fn into_string(self) -> Result<String, OsString> {
154 self.inner.into_string().map_err(|buf| OsString { inner: buf} )
157 /// Extends the string with the given [`&OsStr`] slice.
159 /// [`&OsStr`]: struct.OsStr.html
164 /// use std::ffi::OsString;
166 /// let mut os_string = OsString::from("foo");
167 /// os_string.push("bar");
168 /// assert_eq!(&os_string, "foobar");
170 #[stable(feature = "rust1", since = "1.0.0")]
171 pub fn push<T: AsRef<OsStr>>(&mut self, s: T) {
172 self.inner.push_slice(&s.as_ref().inner)
175 /// Creates a new `OsString` with the given capacity.
177 /// The string will be able to hold exactly `capacity` length units of other
178 /// OS strings without reallocating. If `capacity` is 0, the string will not
181 /// See main `OsString` documentation information about encoding.
186 /// use std::ffi::OsString;
188 /// let mut os_string = OsString::with_capacity(10);
189 /// let capacity = os_string.capacity();
191 /// // This push is done without reallocating
192 /// os_string.push("foo");
194 /// assert_eq!(capacity, os_string.capacity());
196 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
197 pub fn with_capacity(capacity: usize) -> OsString {
199 inner: Buf::with_capacity(capacity)
203 /// Truncates the `OsString` to zero length.
208 /// use std::ffi::OsString;
210 /// let mut os_string = OsString::from("foo");
211 /// assert_eq!(&os_string, "foo");
213 /// os_string.clear();
214 /// assert_eq!(&os_string, "");
216 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
217 pub fn clear(&mut self) {
221 /// Returns the capacity this `OsString` can hold without reallocating.
223 /// See `OsString` introduction for information about encoding.
228 /// use std::ffi::OsString;
230 /// let mut os_string = OsString::with_capacity(10);
231 /// assert!(os_string.capacity() >= 10);
233 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
234 pub fn capacity(&self) -> usize {
235 self.inner.capacity()
238 /// Reserves capacity for at least `additional` more capacity to be inserted
239 /// in the given `OsString`.
241 /// The collection may reserve more space to avoid frequent reallocations.
246 /// use std::ffi::OsString;
248 /// let mut s = OsString::new();
250 /// assert!(s.capacity() >= 10);
252 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
253 pub fn reserve(&mut self, additional: usize) {
254 self.inner.reserve(additional)
257 /// Reserves the minimum capacity for exactly `additional` more capacity to
258 /// be inserted in the given `OsString`. Does nothing if the capacity is
259 /// already sufficient.
261 /// Note that the allocator may give the collection more space than it
262 /// requests. Therefore capacity can not be relied upon to be precisely
263 /// minimal. Prefer reserve if future insertions are expected.
268 /// use std::ffi::OsString;
270 /// let mut s = OsString::new();
271 /// s.reserve_exact(10);
272 /// assert!(s.capacity() >= 10);
274 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
275 pub fn reserve_exact(&mut self, additional: usize) {
276 self.inner.reserve_exact(additional)
279 /// Shrinks the capacity of the `OsString` to match its length.
284 /// use std::ffi::OsString;
286 /// let mut s = OsString::from("foo");
289 /// assert!(s.capacity() >= 100);
291 /// s.shrink_to_fit();
292 /// assert_eq!(3, s.capacity());
294 #[stable(feature = "osstring_shrink_to_fit", since = "1.19.0")]
295 pub fn shrink_to_fit(&mut self) {
296 self.inner.shrink_to_fit()
299 /// Shrinks the capacity of the `OsString` with a lower bound.
301 /// The capacity will remain at least as large as both the length
302 /// and the supplied value.
304 /// Panics if the current capacity is smaller than the supplied
305 /// minimum capacity.
310 /// #![feature(shrink_to)]
311 /// use std::ffi::OsString;
313 /// let mut s = OsString::from("foo");
316 /// assert!(s.capacity() >= 100);
319 /// assert!(s.capacity() >= 10);
321 /// assert!(s.capacity() >= 3);
324 #[unstable(feature = "shrink_to", reason = "new API", issue="0")]
325 pub fn shrink_to(&mut self, min_capacity: usize) {
326 self.inner.shrink_to(min_capacity)
329 /// Converts this `OsString` into a boxed [`OsStr`].
331 /// [`OsStr`]: struct.OsStr.html
336 /// use std::ffi::{OsString, OsStr};
338 /// let s = OsString::from("hello");
340 /// let b: Box<OsStr> = s.into_boxed_os_str();
342 #[stable(feature = "into_boxed_os_str", since = "1.20.0")]
343 pub fn into_boxed_os_str(self) -> Box<OsStr> {
344 let rw = Box::into_raw(self.inner.into_box()) as *mut OsStr;
345 unsafe { Box::from_raw(rw) }
349 #[stable(feature = "rust1", since = "1.0.0")]
350 impl From<String> for OsString {
351 /// Converts a [`String`] into a [`OsString`].
353 /// The conversion copies the data, and includes an allocation on the heap.
354 fn from(s: String) -> OsString {
355 OsString { inner: Buf::from_string(s) }
359 #[stable(feature = "rust1", since = "1.0.0")]
360 impl<'a, T: ?Sized + AsRef<OsStr>> From<&'a T> for OsString {
361 fn from(s: &'a T) -> OsString {
362 s.as_ref().to_os_string()
366 #[stable(feature = "rust1", since = "1.0.0")]
367 impl ops::Index<ops::RangeFull> for OsString {
371 fn index(&self, _index: ops::RangeFull) -> &OsStr {
372 OsStr::from_inner(self.inner.as_slice())
376 #[stable(feature = "rust1", since = "1.0.0")]
377 impl ops::Deref for OsString {
381 fn deref(&self) -> &OsStr {
386 #[stable(feature = "osstring_default", since = "1.9.0")]
387 impl Default for OsString {
388 /// Constructs an empty `OsString`.
390 fn default() -> OsString {
395 #[stable(feature = "rust1", since = "1.0.0")]
396 impl fmt::Debug for OsString {
397 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
398 fmt::Debug::fmt(&**self, formatter)
402 #[stable(feature = "rust1", since = "1.0.0")]
403 impl PartialEq for OsString {
404 fn eq(&self, other: &OsString) -> bool {
409 #[stable(feature = "rust1", since = "1.0.0")]
410 impl PartialEq<str> for OsString {
411 fn eq(&self, other: &str) -> bool {
416 #[stable(feature = "rust1", since = "1.0.0")]
417 impl PartialEq<OsString> for str {
418 fn eq(&self, other: &OsString) -> bool {
423 #[stable(feature = "os_str_str_ref_eq", since = "1.29.0")]
424 impl<'a> PartialEq<&'a str> for OsString {
425 fn eq(&self, other: &&'a str) -> bool {
430 #[stable(feature = "os_str_str_ref_eq", since = "1.29.0")]
431 impl<'a> PartialEq<OsString> for &'a str {
432 fn eq(&self, other: &OsString) -> bool {
437 #[stable(feature = "rust1", since = "1.0.0")]
438 impl Eq for OsString {}
440 #[stable(feature = "rust1", since = "1.0.0")]
441 impl PartialOrd for OsString {
443 fn partial_cmp(&self, other: &OsString) -> Option<cmp::Ordering> {
444 (&**self).partial_cmp(&**other)
447 fn lt(&self, other: &OsString) -> bool { &**self < &**other }
449 fn le(&self, other: &OsString) -> bool { &**self <= &**other }
451 fn gt(&self, other: &OsString) -> bool { &**self > &**other }
453 fn ge(&self, other: &OsString) -> bool { &**self >= &**other }
456 #[stable(feature = "rust1", since = "1.0.0")]
457 impl PartialOrd<str> for OsString {
459 fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
460 (&**self).partial_cmp(other)
464 #[stable(feature = "rust1", since = "1.0.0")]
465 impl Ord for OsString {
467 fn cmp(&self, other: &OsString) -> cmp::Ordering {
468 (&**self).cmp(&**other)
472 #[stable(feature = "rust1", since = "1.0.0")]
473 impl Hash for OsString {
475 fn hash<H: Hasher>(&self, state: &mut H) {
476 (&**self).hash(state)
481 /// Coerces into an `OsStr` slice.
486 /// use std::ffi::OsStr;
488 /// let os_str = OsStr::new("foo");
490 #[stable(feature = "rust1", since = "1.0.0")]
491 pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr {
495 fn from_inner(inner: &Slice) -> &OsStr {
496 unsafe { &*(inner as *const Slice as *const OsStr) }
499 /// Yields a [`&str`] slice if the `OsStr` is valid Unicode.
501 /// This conversion may entail doing a check for UTF-8 validity.
503 /// [`&str`]: ../../std/primitive.str.html
508 /// use std::ffi::OsStr;
510 /// let os_str = OsStr::new("foo");
511 /// assert_eq!(os_str.to_str(), Some("foo"));
513 #[stable(feature = "rust1", since = "1.0.0")]
514 pub fn to_str(&self) -> Option<&str> {
518 /// Converts an `OsStr` to a [`Cow`]`<`[`str`]`>`.
520 /// Any non-Unicode sequences are replaced with
521 /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD].
523 /// [`Cow`]: ../../std/borrow/enum.Cow.html
524 /// [`str`]: ../../std/primitive.str.html
525 /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
529 /// Calling `to_string_lossy` on an `OsStr` with valid unicode:
532 /// use std::ffi::OsStr;
534 /// let os_str = OsStr::new("foo");
535 /// assert_eq!(os_str.to_string_lossy(), "foo");
538 /// Had `os_str` contained invalid unicode, the `to_string_lossy` call might
539 /// have returned `"fo�"`.
540 #[stable(feature = "rust1", since = "1.0.0")]
541 pub fn to_string_lossy(&self) -> Cow<str> {
542 self.inner.to_string_lossy()
545 /// Copies the slice into an owned [`OsString`].
547 /// [`OsString`]: struct.OsString.html
552 /// use std::ffi::{OsStr, OsString};
554 /// let os_str = OsStr::new("foo");
555 /// let os_string = os_str.to_os_string();
556 /// assert_eq!(os_string, OsString::from("foo"));
558 #[stable(feature = "rust1", since = "1.0.0")]
559 pub fn to_os_string(&self) -> OsString {
560 OsString { inner: self.inner.to_owned() }
563 /// Checks whether the `OsStr` is empty.
568 /// use std::ffi::OsStr;
570 /// let os_str = OsStr::new("");
571 /// assert!(os_str.is_empty());
573 /// let os_str = OsStr::new("foo");
574 /// assert!(!os_str.is_empty());
576 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
577 pub fn is_empty(&self) -> bool {
578 self.inner.inner.is_empty()
581 /// Returns the length of this `OsStr`.
583 /// Note that this does **not** return the number of bytes in this string
584 /// as, for example, OS strings on Windows are encoded as a list of [`u16`]
585 /// rather than a list of bytes. This number is simply useful for passing to
586 /// other methods like [`OsString::with_capacity`] to avoid reallocations.
588 /// See `OsStr` introduction for more information about encoding.
590 /// [`u16`]: ../primitive.u16.html
591 /// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity
596 /// use std::ffi::OsStr;
598 /// let os_str = OsStr::new("");
599 /// assert_eq!(os_str.len(), 0);
601 /// let os_str = OsStr::new("foo");
602 /// assert_eq!(os_str.len(), 3);
604 #[stable(feature = "osstring_simple_functions", since = "1.9.0")]
605 pub fn len(&self) -> usize {
606 self.inner.inner.len()
609 /// Converts a [`Box`]`<OsStr>` into an [`OsString`] without copying or allocating.
611 /// [`Box`]: ../boxed/struct.Box.html
612 /// [`OsString`]: struct.OsString.html
613 #[stable(feature = "into_boxed_os_str", since = "1.20.0")]
614 pub fn into_os_string(self: Box<OsStr>) -> OsString {
615 let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut Slice) };
616 OsString { inner: Buf::from_box(boxed) }
619 /// Gets the underlying byte representation.
621 /// Note: it is *crucial* that this API is private, to avoid
622 /// revealing the internal, platform-specific encodings.
623 fn bytes(&self) -> &[u8] {
624 unsafe { &*(&self.inner as *const _ as *const [u8]) }
628 #[stable(feature = "box_from_os_str", since = "1.17.0")]
629 impl<'a> From<&'a OsStr> for Box<OsStr> {
630 fn from(s: &'a OsStr) -> Box<OsStr> {
631 let rw = Box::into_raw(s.inner.into_box()) as *mut OsStr;
632 unsafe { Box::from_raw(rw) }
636 #[stable(feature = "os_string_from_box", since = "1.18.0")]
637 impl From<Box<OsStr>> for OsString {
638 /// Converts a `Box<OsStr>` into a `OsString` without copying or allocating.
640 /// [`Box`]: ../boxed/struct.Box.html
641 /// [`OsString`]: ../ffi/struct.OsString.html
642 fn from(boxed: Box<OsStr>) -> OsString {
643 boxed.into_os_string()
647 #[stable(feature = "box_from_os_string", since = "1.20.0")]
648 impl From<OsString> for Box<OsStr> {
649 /// Converts a [`OsString`] into a [`Box`]`<OsStr>` without copying or allocating.
651 /// [`Box`]: ../boxed/struct.Box.html
652 /// [`OsString`]: ../ffi/struct.OsString.html
653 fn from(s: OsString) -> Box<OsStr> {
654 s.into_boxed_os_str()
658 #[stable(feature = "more_box_slice_clone", since = "1.29.0")]
659 impl Clone for Box<OsStr> {
661 fn clone(&self) -> Self {
662 self.to_os_string().into_boxed_os_str()
666 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
667 impl From<OsString> for Arc<OsStr> {
668 /// Converts a [`OsString`] into a [`Arc`]`<OsStr>` without copying or allocating.
670 /// [`Arc`]: ../sync/struct.Arc.html
671 /// [`OsString`]: ../ffi/struct.OsString.html
673 fn from(s: OsString) -> Arc<OsStr> {
674 let arc = s.inner.into_arc();
675 unsafe { Arc::from_raw(Arc::into_raw(arc) as *const OsStr) }
679 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
680 impl<'a> From<&'a OsStr> for Arc<OsStr> {
682 fn from(s: &OsStr) -> Arc<OsStr> {
683 let arc = s.inner.into_arc();
684 unsafe { Arc::from_raw(Arc::into_raw(arc) as *const OsStr) }
688 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
689 impl From<OsString> for Rc<OsStr> {
690 /// Converts a [`OsString`] into a [`Rc`]`<OsStr>` without copying or allocating.
692 /// [`Rc`]: ../rc/struct.Rc.html
693 /// [`OsString`]: ../ffi/struct.OsString.html
695 fn from(s: OsString) -> Rc<OsStr> {
696 let rc = s.inner.into_rc();
697 unsafe { Rc::from_raw(Rc::into_raw(rc) as *const OsStr) }
701 #[stable(feature = "shared_from_slice2", since = "1.24.0")]
702 impl<'a> From<&'a OsStr> for Rc<OsStr> {
704 fn from(s: &OsStr) -> Rc<OsStr> {
705 let rc = s.inner.into_rc();
706 unsafe { Rc::from_raw(Rc::into_raw(rc) as *const OsStr) }
710 #[stable(feature = "cow_from_osstr", since = "1.28.0")]
711 impl<'a> From<OsString> for Cow<'a, OsStr> {
713 fn from(s: OsString) -> Cow<'a, OsStr> {
718 #[stable(feature = "cow_from_osstr", since = "1.28.0")]
719 impl<'a> From<&'a OsStr> for Cow<'a, OsStr> {
721 fn from(s: &'a OsStr) -> Cow<'a, OsStr> {
726 #[stable(feature = "cow_from_osstr", since = "1.28.0")]
727 impl<'a> From<&'a OsString> for Cow<'a, OsStr> {
729 fn from(s: &'a OsString) -> Cow<'a, OsStr> {
730 Cow::Borrowed(s.as_os_str())
734 #[stable(feature = "osstring_from_cow_osstr", since = "1.28.0")]
735 impl<'a> From<Cow<'a, OsStr>> for OsString {
737 fn from(s: Cow<'a, OsStr>) -> Self {
742 #[stable(feature = "box_default_extra", since = "1.17.0")]
743 impl Default for Box<OsStr> {
744 fn default() -> Box<OsStr> {
745 let rw = Box::into_raw(Slice::empty_box()) as *mut OsStr;
746 unsafe { Box::from_raw(rw) }
750 #[stable(feature = "osstring_default", since = "1.9.0")]
751 impl<'a> Default for &'a OsStr {
752 /// Creates an empty `OsStr`.
754 fn default() -> &'a OsStr {
759 #[stable(feature = "rust1", since = "1.0.0")]
760 impl PartialEq for OsStr {
761 fn eq(&self, other: &OsStr) -> bool {
762 self.bytes().eq(other.bytes())
766 #[stable(feature = "rust1", since = "1.0.0")]
767 impl PartialEq<str> for OsStr {
768 fn eq(&self, other: &str) -> bool {
769 *self == *OsStr::new(other)
773 #[stable(feature = "rust1", since = "1.0.0")]
774 impl PartialEq<OsStr> for str {
775 fn eq(&self, other: &OsStr) -> bool {
776 *other == *OsStr::new(self)
780 #[stable(feature = "rust1", since = "1.0.0")]
783 #[stable(feature = "rust1", since = "1.0.0")]
784 impl PartialOrd for OsStr {
786 fn partial_cmp(&self, other: &OsStr) -> Option<cmp::Ordering> {
787 self.bytes().partial_cmp(other.bytes())
790 fn lt(&self, other: &OsStr) -> bool { self.bytes().lt(other.bytes()) }
792 fn le(&self, other: &OsStr) -> bool { self.bytes().le(other.bytes()) }
794 fn gt(&self, other: &OsStr) -> bool { self.bytes().gt(other.bytes()) }
796 fn ge(&self, other: &OsStr) -> bool { self.bytes().ge(other.bytes()) }
799 #[stable(feature = "rust1", since = "1.0.0")]
800 impl PartialOrd<str> for OsStr {
802 fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
803 self.partial_cmp(OsStr::new(other))
807 // FIXME (#19470): cannot provide PartialOrd<OsStr> for str until we
808 // have more flexible coherence rules.
810 #[stable(feature = "rust1", since = "1.0.0")]
813 fn cmp(&self, other: &OsStr) -> cmp::Ordering { self.bytes().cmp(other.bytes()) }
816 macro_rules! impl_cmp {
817 ($lhs:ty, $rhs: ty) => {
818 #[stable(feature = "cmp_os_str", since = "1.8.0")]
819 impl<'a, 'b> PartialEq<$rhs> for $lhs {
821 fn eq(&self, other: &$rhs) -> bool { <OsStr as PartialEq>::eq(self, other) }
824 #[stable(feature = "cmp_os_str", since = "1.8.0")]
825 impl<'a, 'b> PartialEq<$lhs> for $rhs {
827 fn eq(&self, other: &$lhs) -> bool { <OsStr as PartialEq>::eq(self, other) }
830 #[stable(feature = "cmp_os_str", since = "1.8.0")]
831 impl<'a, 'b> PartialOrd<$rhs> for $lhs {
833 fn partial_cmp(&self, other: &$rhs) -> Option<cmp::Ordering> {
834 <OsStr as PartialOrd>::partial_cmp(self, other)
838 #[stable(feature = "cmp_os_str", since = "1.8.0")]
839 impl<'a, 'b> PartialOrd<$lhs> for $rhs {
841 fn partial_cmp(&self, other: &$lhs) -> Option<cmp::Ordering> {
842 <OsStr as PartialOrd>::partial_cmp(self, other)
848 impl_cmp!(OsString, OsStr);
849 impl_cmp!(OsString, &'a OsStr);
850 impl_cmp!(Cow<'a, OsStr>, OsStr);
851 impl_cmp!(Cow<'a, OsStr>, &'b OsStr);
852 impl_cmp!(Cow<'a, OsStr>, OsString);
854 #[stable(feature = "rust1", since = "1.0.0")]
855 impl Hash for OsStr {
857 fn hash<H: Hasher>(&self, state: &mut H) {
858 self.bytes().hash(state)
862 #[stable(feature = "rust1", since = "1.0.0")]
863 impl fmt::Debug for OsStr {
864 fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
865 fmt::Debug::fmt(&self.inner, formatter)
870 pub(crate) fn display(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
871 fmt::Display::fmt(&self.inner, formatter)
875 #[stable(feature = "rust1", since = "1.0.0")]
876 impl Borrow<OsStr> for OsString {
877 fn borrow(&self) -> &OsStr { &self[..] }
880 #[stable(feature = "rust1", since = "1.0.0")]
881 impl ToOwned for OsStr {
882 type Owned = OsString;
883 fn to_owned(&self) -> OsString {
886 fn clone_into(&self, target: &mut OsString) {
892 #[stable(feature = "rust1", since = "1.0.0")]
893 impl AsRef<OsStr> for OsStr {
894 fn as_ref(&self) -> &OsStr {
899 #[stable(feature = "rust1", since = "1.0.0")]
900 impl AsRef<OsStr> for OsString {
901 fn as_ref(&self) -> &OsStr {
906 #[stable(feature = "rust1", since = "1.0.0")]
907 impl AsRef<OsStr> for str {
908 fn as_ref(&self) -> &OsStr {
909 OsStr::from_inner(Slice::from_str(self))
913 #[stable(feature = "rust1", since = "1.0.0")]
914 impl AsRef<OsStr> for String {
915 fn as_ref(&self) -> &OsStr {
920 impl FromInner<Buf> for OsString {
921 fn from_inner(buf: Buf) -> OsString {
922 OsString { inner: buf }
926 impl IntoInner<Buf> for OsString {
927 fn into_inner(self) -> Buf {
932 impl AsInner<Slice> for OsStr {
933 fn as_inner(&self) -> &Slice {
941 use sys_common::{AsInner, IntoInner};
947 fn test_os_string_with_capacity() {
948 let os_string = OsString::with_capacity(0);
949 assert_eq!(0, os_string.inner.into_inner().capacity());
951 let os_string = OsString::with_capacity(10);
952 assert_eq!(10, os_string.inner.into_inner().capacity());
954 let mut os_string = OsString::with_capacity(0);
955 os_string.push("abc");
956 assert!(os_string.inner.into_inner().capacity() >= 3);
960 fn test_os_string_clear() {
961 let mut os_string = OsString::from("abc");
962 assert_eq!(3, os_string.inner.as_inner().len());
965 assert_eq!(&os_string, "");
966 assert_eq!(0, os_string.inner.as_inner().len());
970 fn test_os_string_capacity() {
971 let os_string = OsString::with_capacity(0);
972 assert_eq!(0, os_string.capacity());
974 let os_string = OsString::with_capacity(10);
975 assert_eq!(10, os_string.capacity());
977 let mut os_string = OsString::with_capacity(0);
978 os_string.push("abc");
979 assert!(os_string.capacity() >= 3);
983 fn test_os_string_reserve() {
984 let mut os_string = OsString::new();
985 assert_eq!(os_string.capacity(), 0);
987 os_string.reserve(2);
988 assert!(os_string.capacity() >= 2);
994 assert!(os_string.capacity() >= 16);
995 os_string.reserve(16);
996 assert!(os_string.capacity() >= 32);
1000 os_string.reserve(16);
1001 assert!(os_string.capacity() >= 33)
1005 fn test_os_string_reserve_exact() {
1006 let mut os_string = OsString::new();
1007 assert_eq!(os_string.capacity(), 0);
1009 os_string.reserve_exact(2);
1010 assert!(os_string.capacity() >= 2);
1013 os_string.push("a");
1016 assert!(os_string.capacity() >= 16);
1017 os_string.reserve_exact(16);
1018 assert!(os_string.capacity() >= 32);
1020 os_string.push("a");
1022 os_string.reserve_exact(16);
1023 assert!(os_string.capacity() >= 33)
1027 fn test_os_string_default() {
1028 let os_string: OsString = Default::default();
1029 assert_eq!("", &os_string);
1033 fn test_os_str_is_empty() {
1034 let mut os_string = OsString::new();
1035 assert!(os_string.is_empty());
1037 os_string.push("abc");
1038 assert!(!os_string.is_empty());
1041 assert!(os_string.is_empty());
1045 fn test_os_str_len() {
1046 let mut os_string = OsString::new();
1047 assert_eq!(0, os_string.len());
1049 os_string.push("abc");
1050 assert_eq!(3, os_string.len());
1053 assert_eq!(0, os_string.len());
1057 fn test_os_str_default() {
1058 let os_str: &OsStr = Default::default();
1059 assert_eq!("", os_str);
1064 let orig = "Hello, world!";
1065 let os_str = OsStr::new(orig);
1066 let boxed: Box<OsStr> = Box::from(os_str);
1067 let os_string = os_str.to_owned().into_boxed_os_str().into_os_string();
1068 assert_eq!(os_str, &*boxed);
1069 assert_eq!(&*boxed, &*os_string);
1070 assert_eq!(&*os_string, os_str);
1074 fn boxed_default() {
1075 let boxed = <Box<OsStr>>::default();
1076 assert!(boxed.is_empty());
1080 fn test_os_str_clone_into() {
1081 let mut os_string = OsString::with_capacity(123);
1082 os_string.push("hello");
1083 let os_str = OsStr::new("bonjour");
1084 os_str.clone_into(&mut os_string);
1085 assert_eq!(os_str, os_string);
1086 assert!(os_string.capacity() >= 123);
1091 let orig = "Hello, world!";
1092 let os_str = OsStr::new(orig);
1093 let rc: Rc<OsStr> = Rc::from(os_str);
1094 let arc: Arc<OsStr> = Arc::from(os_str);
1096 assert_eq!(&*rc, os_str);
1097 assert_eq!(&*arc, os_str);
1099 let rc2: Rc<OsStr> = Rc::from(os_str.to_owned());
1100 let arc2: Arc<OsStr> = Arc::from(os_str.to_owned());
1102 assert_eq!(&*rc2, os_str);
1103 assert_eq!(&*arc2, os_str);