@@ -42,6 +42,13 @@ use sys_common::{AsInner, IntoInner, FromInner};
42
42
/// in each pair are owned strings; the latter are borrowed
43
43
/// references.
44
44
///
45
+ /// Note, `OsString` and `OsStr` internally do not necessarily hold strings in
46
+ /// the form native to the platform; While on Unix, strings are stored as a
47
+ /// sequence of 8-bit values, on Windows, where strings are 16-bit value based
48
+ /// as just discussed, strings are also actually stored as a sequence of 8-bit
49
+ /// values, encoded in a less-strict variant of UTF-8. This is useful to
50
+ /// understand when handling capacity and length values.
51
+ ///
45
52
/// # Creating an `OsString`
46
53
///
47
54
/// **From a Rust string**: `OsString` implements
@@ -583,14 +590,19 @@ impl OsStr {
583
590
584
591
/// Returns the length of this `OsStr`.
585
592
///
586
- /// Note that this does **not** return the number of bytes in this string
587
- /// as, for example, OS strings on Windows are encoded as a list of [`u16`]
588
- /// rather than a list of bytes. This number is simply useful for passing to
589
- /// other methods like [`OsString::with_capacity`] to avoid reallocations.
593
+ /// Note that this does **not** return the number of bytes in the string in
594
+ /// OS string form.
595
+ ///
596
+ /// The length returned is that of the underlying storage used by `OsStr`;
597
+ /// As discussed in the [`OsString`] introduction, [`OsString`] and `OsStr`
598
+ /// store strings in a form best suited for cheap inter-conversion between
599
+ /// native-platform and Rust string forms, which may differ significantly
600
+ /// from both of them, including in storage size and encoding.
590
601
///
591
- /// See `OsStr` introduction for more information about encoding.
602
+ /// This number is simply useful for passing to other methods, like
603
+ /// [`OsString::with_capacity`] to avoid reallocations.
592
604
///
593
- /// [`u16 `]: ../primitive.u16 .html
605
+ /// [`OsString `]: struct.OsString .html
594
606
/// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity
595
607
///
596
608
/// # Examples
0 commit comments