Skip to content

Commit e9a8055

Browse files
authored
Rollup merge of rust-lang#56141 - jnqnfe:osstr_len_clarity, r=nagisa
[std] Osstr len clarity
2 parents 25c3754 + a1e9c7f commit e9a8055

File tree

1 file changed

+18
-6
lines changed

1 file changed

+18
-6
lines changed

src/libstd/ffi/os_str.rs

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ use sys_common::{AsInner, IntoInner, FromInner};
4242
/// in each pair are owned strings; the latter are borrowed
4343
/// references.
4444
///
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+
///
4552
/// # Creating an `OsString`
4653
///
4754
/// **From a Rust string**: `OsString` implements
@@ -583,14 +590,19 @@ impl OsStr {
583590

584591
/// Returns the length of this `OsStr`.
585592
///
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.
590601
///
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.
592604
///
593-
/// [`u16`]: ../primitive.u16.html
605+
/// [`OsString`]: struct.OsString.html
594606
/// [`OsString::with_capacity`]: struct.OsString.html#method.with_capacity
595607
///
596608
/// # Examples

0 commit comments

Comments
 (0)