It is a frequent pattern among I/O functions to take `P: AsPath + ?Sized` or
`AsOsStr` instead of `AsPath`. Most of these functions do not need to take
ownership of their argument, but for libraries in general it's much more
ergonomic to not deal with `?Sized` at all and simply require an argument `P`
instead of `&P`.
This change is aimed at removing unsightly `?Sized` bounds while retaining the
same level of usability as before. All affected functions now take ownership of
their arguments instead of taking them by reference, but due to the forwarding
implementations of `AsOsStr` and `AsPath` all code should continue to work as it
did before.
This is strictly speaking a breaking change due to the signatures of these
functions changing, but normal idiomatic usage of these APIs should not break in
practice.
[breaking-change]
at least that's what the docs say: http://doc.rust-lang.org/std/slice/fn.from_raw_parts.html
A few situations got prettier. In some situations the mutability of the resulting and source pointers differed (and was cast away by transmute), the mutability matches now.
The new `std::io` module has had some time to bake now, and this commit
stabilizes its functionality. There are still portions of the module which
remain unstable, and below contains a summart of the actions taken.
This commit also deprecates the entire contents of the `old_io` module in a
blanket fashion. All APIs should now have a reasonable replacement in the
new I/O modules.
Stable APIs:
* `std::io` (the name)
* `std::io::prelude` (the name)
* `Read`
* `Read::read`
* `Read::{read_to_end, read_to_string}` after being modified to return a `usize`
for the number of bytes read.
* `Write`
* `Write::write`
* `Write::{write_all, write_fmt}`
* `BufRead`
* `BufRead::{fill_buf, consume}`
* `BufRead::{read_line, read_until}` after being modified to return a `usize`
for the number of bytes read.
* `BufReader`
* `BufReader::{new, with_capacity}`
* `BufReader::{get_ref, get_mut, into_inner}`
* `{Read,BufRead} for BufReader`
* `BufWriter`
* `BufWriter::{new, with_capacity}`
* `BufWriter::{get_ref, get_mut, into_inner}`
* `Write for BufWriter`
* `IntoInnerError`
* `IntoInnerError::{error, into_inner}`
* `{Error,Display} for IntoInnerError`
* `LineWriter`
* `LineWriter::{new, with_capacity}` - `with_capacity` was added
* `LineWriter::{get_ref, get_mut, into_inner}` - `get_mut` was added)
* `Write for LineWriter`
* `BufStream`
* `BufStream::{new, with_capacities}`
* `BufStream::{get_ref, get_mut, into_inner}`
* `{BufRead,Read,Write} for BufStream`
* `stdin`
* `Stdin`
* `Stdin::lock`
* `Stdin::read_line` - added method
* `StdinLock`
* `Read for Stdin`
* `{Read,BufRead} for StdinLock`
* `stdout`
* `Stdout`
* `Stdout::lock`
* `StdoutLock`
* `Write for Stdout`
* `Write for StdoutLock`
* `stderr`
* `Stderr`
* `Stderr::lock`
* `StderrLock`
* `Write for Stderr`
* `Write for StderrLock`
* `io::Result`
* `io::Error`
* `io::Error::last_os_error`
* `{Display, Error} for Error`
Unstable APIs:
(reasons can be found in the commit itself)
* `Write::flush`
* `Seek`
* `ErrorKind`
* `Error::new`
* `Error::from_os_error`
* `Error::kind`
Deprecated APIs
* `Error::description` - available via the `Error` trait
* `Error::detail` - available via the `Display` implementation
* `thread::Builder::{stdout, stderr}`
Changes in functionality:
* `old_io::stdio::set_stderr` is now a noop as the infrastructure for printing
backtraces has migrated to `std::io`.
* The `ReadExt`, `WriteExt`, and `BufReadExt` extension traits were all removed
by folding functionality into the corresponding trait.
[breaking-change]
This commit stabilizes essentially all of the new `std::path` API. The
API itself is changed in a couple of ways (which brings it in closer
alignment with the RFC):
* `.` components are now normalized away, unless they appear at the
start of a path. This in turn effects the semantics of e.g. asking for
the file name of `foo/` or `foo/.`, both of which yield `Some("foo")`
now. This semantics is what the original RFC specified, and is also
desirable given early experience rolling out the new API.
* The `parent` method is now `without_file` and succeeds if, and only
if, `file_name` is `Some(_)`. That means, in particular, that it fails
for a path like `foo/../`. This change affects `pop` as well.
In addition, the `old_path` module is now deprecated.
[breaking-change]
r? @alexcrichton
This commit stabilizes essentially all of the new `std::path` API. The
API itself is changed in a couple of ways (which brings it in closer
alignment with the RFC):
* `.` components are now normalized away, unless they appear at the
start of a path. This in turn effects the semantics of e.g. asking for
the file name of `foo/` or `foo/.`, both of which yield `Some("foo")`
now. This semantics is what the original RFC specified, and is also
desirable given early experience rolling out the new API.
* The `parent` function now succeeds if, and only if, the path has at
least one non-root/prefix component. This change affects `pop` as
well.
* The `Prefix` component now involves a separate `PrefixComponent`
struct, to better allow for keeping both parsed and unparsed prefix data.
In addition, the `old_path` module is now deprecated.
Closes#23264
[breaking-change]
This commit performs another pass over the `std::char` module for stabilization.
Some minor cleanup is performed such as migrating documentation from libcore to
libunicode (where the `std`-facing trait resides) as well as a slight
reorganiation in libunicode itself. Otherwise, the stability modifications made
are:
* `char::from_digit` is now stable
* `CharExt::is_digit` is now stable
* `CharExt::to_digit` is now stable
* `CharExt::to_{lower,upper}case` are now stable after being modified to return
an iterator over characters. While the implementation today has not changed
this should allow us to implement the full set of case conversions in unicode
where some characters can map to multiple when doing an upper or lower case
mapping.
* `StrExt::to_{lower,upper}case` was added as unstable for a convenience of not
having to worry about characters expanding to more characters when you just
want the whole string to get into upper or lower case.
This is a breaking change due to the change in the signatures of the
`CharExt::to_{upper,lower}case` methods. Code can be updated to use functions
like `flat_map` or `collect` to handle the difference.
[breaking-change]
Closes#20333
This commit performs another pass over the `std::char` module for stabilization.
Some minor cleanup is performed such as migrating documentation from libcore to
libunicode (where the `std`-facing trait resides) as well as a slight
reorganiation in libunicode itself. Otherwise, the stability modifications made
are:
* `char::from_digit` is now stable
* `CharExt::is_digit` is now stable
* `CharExt::to_digit` is now stable
* `CharExt::to_{lower,upper}case` are now stable after being modified to return
an iterator over characters. While the implementation today has not changed
this should allow us to implement the full set of case conversions in unicode
where some characters can map to multiple when doing an upper or lower case
mapping.
* `StrExt::to_{lower,upper}case` was added as unstable for a convenience of not
having to worry about characters expanding to more characters when you just
want the whole string to get into upper or lower case.
This is a breaking change due to the change in the signatures of the
`CharExt::to_{upper,lower}case` methods. Code can be updated to use functions
like `flat_map` or `collect` to handle the difference.
[breaking-change]
This may not be quite ready to go out, I fixed some docs but suspect I missed a bunch.
I also wound up fixing a bunch of redundant `[]` suffixes, but on closer inspection I don't believe that can land until after a snapshot.
Building on #22076, I've added some tests for stable methods in f32 and f64 that didn't have any before.
Please let me know if there are any improvements I can make, and I am happy to make them! 📬
Being a person who somehow has taken a liking to premature optimisation, my knee-jerk reaction to
locking in std handles was preamble resembling following snippet:
let stdout = stdout();
let lstdout = stdout.lock();
let stdin = stdin();
let lstdin = stdin.lock();
and then reading from the locked handle like this:
let mut letter = [0; 1];
lstdin.read(&mut letter).unwrap();
As it is now this code will deadlock because the `read` method attempts to lock stdout as well!
r? @alexcrichton
---
Either way, I find flushing stdout when stdin is used debatable. I believe people who write prompts should take care to flush stdout when necessary themselves.
Another idea: Would be cool if locks on std handles would be taken for a thread, rather than a handle, so given preamble (first code snippet)
stdin.lock()
or more generally
stdin.read(…)
worked fine. I.e. if more than a single lock are all taken inside the same thread, it would work, though not sure if our synchronisation primitives are expressive enough to make it possible.
The `std::net` primitives should be ready for use now and as a result the old
ones are now deprecated and slated for removal. Most TCP/UDP functionality is
now available through `std::net` but the `std::old_io::net::pipe` module is
removed entirely from the standard library.
Unix socket funtionality can be found in sfackler's [`unix_socket`][unix] crate
and there is currently no replacement for named pipes on Windows.
[unix]: https://crates.io/crates/unix_socket
[breaking-change]
The `std::net` primitives should be ready for use now and as a result the old
ones are now deprecated and slated for removal. Most TCP/UDP functionality is
now available through `std::net` but the `std::old_io::net::pipe` module is
removed entirely from the standard library.
Unix socket funtionality can be found in sfackler's [`unix_socket`][unix] crate
and there is currently no replacement for named pipes on Windows.
[unix]: https://crates.io/crates/unix_socket
[breaking-change]
Being a person who somehow has taken a liking to premature optimisation, my knee-jerk reaction to
locking in std handles was preamble resembling following snippet:
let stdout = stdout();
let lstdout = stdout.lock();
let stdin = stdin();
let lstdin = stdin.lock();
and then reading from the locked handle like this:
let mut letter = [0; 1];
lstdin.read(&mut letter).unwrap();
As it is now this code will deadlock because the `read` method attempts to lock stdout as well!
Unstable items used in a macro expansion will now always trigger
stability warnings, *unless* the unstable items are directly inside a
macro marked with `#[allow_internal_unstable]`. IOW, the compiler warns
unless the span of the unstable item is a subspan of the definition of a
macro marked with that attribute.
E.g.
#[allow_internal_unstable]
macro_rules! foo {
($e: expr) => {{
$e;
unstable(); // no warning
only_called_by_foo!();
}}
}
macro_rules! only_called_by_foo {
() => { unstable() } // warning
}
foo!(unstable()) // warning
The unstable inside `foo` is fine, due to the attribute. But the
`unstable` inside `only_called_by_foo` is not, since that macro doesn't
have the attribute, and the `unstable` passed into `foo` is also not
fine since it isn't contained in the macro itself (that is, even though
it is only used directly in the macro).
In the process this makes the stability tracking much more precise,
e.g. previously `println!("{}", unstable())` got no warning, but now it
does. As such, this is a bug fix that may cause [breaking-change]s.
The attribute is definitely feature gated, since it explicitly allows
side-stepping the feature gating system.
---
This updates `thread_local!` macro to use the attribute, since it uses
unstable features internally (initialising a struct with unstable
fields).
This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.
The following apis are now marked `#[stable]`:
* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
reject cross-platform openings of directories. This means that some platforms
will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
remove a readonly file has been removed. This means that removing a readonly
file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`
The following apis remain `#[unstable]`.
* `WalkDir` and `walk` - there are many methods by which a directory walk can be
constructed, and it's unclear whether the current semantics are the right
ones. For example symlinks are not handled super well currently. This is now
behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
provides on top of what the system offers and it's unclear whether we should
be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
abstraction for a moment in time which is what these APIs should likely be
returning, so these remain `#[unstable]` for now. These are now behind a new
`fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
the appropriate abstraction for the arguments here so this API remains
unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
some methods may be removed. This API remains unstable behind the `path_ext`
feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
permissions on a file instead of just a blanket \"set all permissions\" method.
This function remains behind the `fs` feature.
The following apis are now `#[deprecated]`
* The `TempDir` type is now entirely deprecated and is [located on
crates.io][tempdir] as the `tempdir` crate with [its source][github] at
rust-lang/tempdir.
[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir
The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].
[rfc-issue]: rust-lang/rfcs#939
Closes#22879
[breaking-change]
This module is now superseded by the `std::process` module. This module still
has some room to expand to get quite back up to parity with the `old_io`
version, and there is a [tracking issue][issue] for feature requests as well as
known room for expansion.
[issue]: https://github.com/rust-lang/rfcs/issues/941
[breaking-change]
The new `io` module has had some time to bake and this commit stabilizes some of
the utilities associated with it. This commit also deprecates a number of
`std::old_io::util` functions and structures.
These items are now `#[stable]`
* `Cursor`
* `Cursor::{new, into_inner, get_ref, get_mut, position, set_position}`
* Implementations of I/O traits for `Cursor<T>`
* Delegating implementations of I/O traits for references and `Box` pointers
* Implementations of I/O traits for primitives like slices and `Vec<T>`
* `ReadExt::bytes`
* `Bytes` (and impls)
* `ReadExt::chain`
* `Chain` (and impls)
* `ReadExt::take` (and impls)
* `BufReadExt::lines`
* `Lines` (and impls)
* `io::copy`
* `io::{empty, Empty}` (and impls)
* `io::{sink, Sink}` (and impls)
* `io::{repeat, Repeat}` (and impls)
These items remain `#[unstable]`
* Core I/O traits. These may want a little bit more time to bake along with the
commonly used methods like `read_to_end`.
* `BufReadExt::split` - this function may be renamed to not conflict with
`SliceExt::split`.
* `Error` - there are a number of questions about its representation,
`ErrorKind`, and usability.
These items are now `#[deprecated]` in `old_io`
* `LimitReader` - use `take` instead
* `NullWriter` - use `io::sink` instead
* `ZeroReader` - use `io::repeat` instead
* `NullReader` - use `io::empty` instead
* `MultiWriter` - use `broadcast` instead
* `ChainedReader` - use `chain` instead
* `TeeReader` - use `tee` instead
* `copy` - use `io::copy` instead
[breaking-change]
Unstable items used in a macro expansion will now always trigger
stability warnings, *unless* the unstable items are directly inside a
macro marked with `#[allow_internal_unstable]`. IOW, the compiler warns
unless the span of the unstable item is a subspan of the definition of a
macro marked with that attribute.
E.g.
#[allow_internal_unstable]
macro_rules! foo {
($e: expr) => {{
$e;
unstable(); // no warning
only_called_by_foo!();
}}
}
macro_rules! only_called_by_foo {
() => { unstable() } // warning
}
foo!(unstable()) // warning
The unstable inside `foo` is fine, due to the attribute. But the
`unstable` inside `only_called_by_foo` is not, since that macro doesn't
have the attribute, and the `unstable` passed into `foo` is also not
fine since it isn't contained in the macro itself (that is, even though
it is only used directly in the macro).
In the process this makes the stability tracking much more precise,
e.g. previously `println!(\"{}\", unstable())` got no warning, but now it
does. As such, this is a bug fix that may cause [breaking-change]s.
The attribute is definitely feature gated, since it explicitly allows
side-stepping the feature gating system.
---
This updates `thread_local!` macro to use the attribute, since it uses
unstable features internally (initialising a struct with unstable
fields).
