APIs stabilization metabug

[alexcrichton]

We will eventually need a process for API stabilization planning and discussion, but while we're first getting used to the 6 week cadence, we'll use this issue for tracking.

Planned for 1.0 stable

• [x] str::Utf8Error (switch from enum to opaque struct, with accessor for "last valid byte position")
• [x] io::Error::from_raw_os_error
• [x] Clone::clone_from (likely)

  Planned for 1.1 beta

• [x] str_words -- see #15628

  Planned for 1.1 stable

• [ ] thread::catch_panic
• [ ] time::Duration
• [x] debug builders
• [ ] collections::Bound
• [ ] One/Zero + .sum / .product
• [ ] iter::StepBy -- decide what to do on a negative step
• [ ] Box::from_raw, boxed::into_raw
• [ ] char::encode_utf{8,16}

  APIs with known problems/requiring more thought

• [ ] iter::order -- would prefer to use comparison operators
• [ ] alloc::heap -- huge risks for future tracing support etc.
• [ ] IteratorExt::{min,max}_by -- #15311
• [ ] <[_]>::position_elem
• [ ] #[bench] -- want more pluggable framework
• [ ] std::slice::bytes -- wants more design work
• [ ] char::width
• [ ] Read::chars -- has problematic error type; should this even be provided given how slow it is?
• [ ] iter::range_inclusive -- replace with adapters
• [ ] collections::{BitVec, VecMap} -- need clearer policy on what ships in collections
• [ ] mem::copy{,_mut}_lifetime, ptr::Unique -- wants more general design for "safer unsafe patterns"

  Slated for eventual deprecation/removal (if unstable)

• [ ] Vec::push_all
• [ ] Vec::from_raw_buf
• [ ] FromPrimitive/ToPrimitive/NumCast (will be replaced with more general failable cast)

  Far-future

• [ ] raw::TraitObject
• [ ] intrinsics::volatile_set_memory
• [ ] intrinsics::type_name

[alexcrichton]

triage: P-high (1.1)

[steveklabnik]

str_words is very small, might be worthwhile :)

[bstrie]

std::str::from_utf8 is marked stable, but it can return std::str::Utf8Error which is still unstable. Need to correct this oversight, as well as be sure to audit all stable functions to make sure their return types are stable.

[mitsuhiko]

push_all on vectors really needs to become stable. I'm trying to replace my uses with that extend/into_iter or iter/cloned dance currently and it's not just slow, it's also terrible to look at.

[BurntSushi]

I second @bstrie's suggestion of str::Utf8Error. It's definitely weird for that to be unstable.

Some nice-to-haves:

• char::width
• accessed and modified on fs::Metadata (I guess this is probably blocking on stabilizing some kind of Duration type.)

[kinghajj]

Any chance that alloc::heap can be made stable? The deque crate uses this to allocate its buffers.

[vhbit]

convert for passing Path -> OsStr -> CString -> C code.

[sfackler]

I'd like to stabilize the debug builders.

[mrmonday]

I'm not sure that this is the right place to mention it, but http://doc.rust-lang.org/std/io/struct.Error.html#method.from_os_error is marked with "unclear whether this function is necessary" - I would argue it is necessary for the following reasons:

• The standard library does not (and probably should not) provide abstractions for all OS APIs
• Many libraries/miscellaneous kernel modules (not just OS APIs) return OS error codes
• Third party libraries (i.e. not standard library) that wrap these APIs should be able to provide an API which is consistent with what the standard library offers (having to duplicate std::io::Error for each different library would be a shame).

Arguments against:

• Users could mistakenly try to use it for any FFI error codes, not just OS error codes, leading to confusion. I'm not sure if/how this could be avoided.

[skade]

I had to do a change because type_name is exported into std, but not marked stable. It's not that I absolutely need it, but I have a usecase for something with it's guarantees: a stable identifier for a specific type between versions. I'd prefer using it.

[pyfisch]

• [ ] FromPrimitive - e.g. casting from an integer to an enum

Great, that it will be added again. Hyper used it for both HTTP status codes and quality values, it was removed to make hyper run on beta. But Hyper also needs ToPrimitive, will this also stabilized, or is it planned to deprecate it?

[tomaka]

Read::chars is very useful when you want to lex/parse some UTF-8 input.

[mvdnes]

Something stabilizing #![no_std] and extern crate core; would be great. For normal crates it isn't very useful, but it would be nice to compile my 'kernel' with a stable compiler.

Also the value field of UnsafeCell. This is necessary to create a static initializer. Constant expressions would also be able to solve this though

[nagisa]

accessed and modified on fs::Metadata (I guess this is probably blocking on stabilizing some kind of Duration type.)

Duration for an absolute time stamp sounds odd.

[mhristache]

I also need char::width

[apasel422]

std::collections::Bound and its variants have no stability marker, but I assume this is waiting on changes or additions to the Range types.

[jedisct1]

collections::BitVec would be nice to stabilize.

Also, what prevents core::iter::StepBy from being stabilized?

[dnaq]

std::intrinsics::volatile_set_memory

[skade]

test, because #[bench] requires "test::Bencher" for its function signatures.

[ghost]

std::sync::Semaphore

[SimonSapin]

str_words

I think we should just remove this one. It’s unclear what "a word" is or should be. Unicode has an entire document (UAX #29 Text Segmentation) with a non-trivial algorithm to standardize this, but I think an implementation of it belongs more on crates.io than in std.

Instead, we could have "split a string on whitespace" in std, based on char::is_whitespace. This is much less ambiguous. It could be either a stand-alone method, or a custom std::str::Pattern implementation to be used with str::split.

[skade]

I agree with @SimonSapin there. I think a good crates.io library is what we need. https://github.com/rust-lang/rfcs/issues/797#issuecomment-73041246

[anonova]

Vec::from_raw_buf

[skade]

@anonova This is quite well expressed by from_raw_parts combined with to_vec

use std::slice::from_raw_parts;
from_raw_parts(value, length as usize).to_vec()

[reem]

@skade that requires a copy of all the contents, which is often not desirable.

[jedisct1]

I would really love to see Vec::from_raw_buf() to be stabilized as well.

[TyOverby]

I'm blocking on the whole unicode crate.

It also looks like NumCast and RawSlice are blocking for me as well.

[SimonSapin]

I'm blocking on the whole unicode crate.

What features specifically? At some point I want to move them to crates.io

[carllerche]

I'm pretty keen on getting TraitObject or some API to work with them stable.

[Benjamin-L]

libc is sometimes required to do things although I doubt that it will be stable for a long time. For example, signal handling requires it. A better solution would be to put wrappers around libc functionality in the standard library.

[bluss]

I had to do a change because type_name is exported into std, but not marked stable. It's not that I absolutely need it, but I have a usecase for something with it's guarantees: a stable identifier for a specific type between versions. I'd prefer using it.

@skade It sounds unlikely that Rust would guarantee that the type names were stable across versions, even if the function would be marked stable.

[skade]

@bluss I don't understand. How would stable public type names and user-provided type names change?

[bluss]

When exporting compiler internals right out I'd always like to use that caveat first, it's much easier to not promise anything. It seems the output is not stable now, given that the type name of "struct Foo" is Foo and of trait "Copy" it is core::marker::Copy which apart from being inconsistent with using path or not, leaks implementation details (location inside implementation crate libcore). (Add to this concerns over generics, default type parameters..)

[ogham]

@TyOverby: As someone who's dependent on str#width, I'd really like a stable unicode crate. Is there anything blocking this function in particular?

[jgallagher]

I'd like to use ptr::Unique as in this PR for holding on to the handle to a SQLite database.

[ajfrantz]

One vote for core::str::StrExt to be available out of the box.

[SimonSapin]

@ajfrantz, core::str::StrExt is replaced with inherent methods on the str type: http://doc.rust-lang.org/std/primitive.str.html

[ajfrantz]

@SimonSapin Ah, perfect. If I just search 'contains' in the API docs it doesn't make that very obvious.

Thanks!

[SimonSapin]

Yes, that’s a bug in rustdoc: https://github.com/rust-lang/rust/issues/23511

[blackbeam]

Vote for char::encode_utf(8|16).

[nagisa]

Vote for char::encode_utf(8|16).

There’s the encoding crate.

[blackbeam]

There’s the encoding crate.

Thanks!

[SimonSapin]

Vote for char::encode_utf(8|16).

As a work-around, I’ve replaced encode_utf8 with:

        let mut utf_8 = [0u8; 4];
        let bytes_written = {
            let mut buffer = &mut utf_8[..];
            write!(buffer, "{}", c).unwrap();
            4 - buffer.len()
        };
        self.write_str(unsafe { mem::transmute(&utf_8[..bytes_written]) })

As to, encode_utf16, you could just inline it:

if ch < '\u{10000}' {
    &[ch as u16][..]
} else {
    ch -= 0x1_0000;
    &[0xD800 | ((ch >> 10) as u16),
      0xDC00 | ((ch as u16) & 0x3FF)][..]
}

[blackbeam]

Thanks, Simon!

Also vote for TcpStream::set_keepalive.

[xitep]

test

[daboross]

@vhbit It's totally possible at the moment to get from OsStr to CString on rust stable, it's just a bit indirect I guess, though it shouldn't really be any more costly performance wise than the unstable APIs.

use std::ffi::CString;
use std::path::Path;

fn main() {
    let path = Path::new(".");
    let os_str = path.as_os_str();
    let str = os_str.to_str().unwrap(); // fails if invalid unicode
    let c_string = CString::new(str).unwrap(); // fails if null bytes
}

@Benjamin-L Just depend on the libc crate in Cargo.toml. The in-rustc version is (I think) very unlikely to stabilize, and using the crates.io version is the provided replacement.

[SimonSapin]

std::os::unix::ffi::OsStrExt::as_bytes is stable and does not require UTF-8 well-formedness, but only exists on Unix. (I’m not sure what encoding a CString is supposed to be in on Windows anyway.)

[carllerche]

Another API that is important: NonZero. Without it, structs that used to be 1ptr in size have grown to 4x the size (because of nesting).

Also, non-zeroing drop since I used to use #[unsafe_no_drop_flag] to improve the struct size as well.

[daboross]

Personally, IntoCow (or Into<Cow>) being stabilized would be awesome, it's something that would be really useful when creating library APIs.

[BurntSushi]

@daboross Into<Cow> is stable: http://doc.rust-lang.org/std/convert/trait.Into.html and http://doc.rust-lang.org/std/borrow/enum.Cow.html