# Rationale
When dealing with strings, many functions deal with either a `char` (unicode
codepoint) or a byte (utf-8 encoding related). There is often an inconsistent
way in which methods are referred to as to whether they contain "byte", "char",
or nothing in their name. There are also issues open to rename *all* methods to
reflect that they operate on utf8 encodings or bytes (e.g. utf8_len() or
byte_len()).
The current state of String seems to largely be what is desired, so this PR
proposes the following rationale for methods dealing with bytes or characters:
> When constructing a string, the input encoding *must* be mentioned (e.g.
> from_utf8). This makes it clear what exactly the input type is expected to be
> in terms of encoding.
>
> When a method operates on anything related to an *index* within the string
> such as length, capacity, position, etc, the method *implicitly* operates on
> bytes. It is an understood fact that String is a utf-8 encoded string, and
> burdening all methods with "bytes" would be redundant.
>
> When a method operates on the *contents* of a string, such as push() or pop(),
> then "char" is the default type. A String can loosely be thought of as being a
> collection of unicode codepoints, but not all collection-related operations
> make sense because some can be woefully inefficient.
# Method stabilization
The following methods have been marked #[stable]
* The String type itself
* String::new
* String::with_capacity
* String::from_utf16_lossy
* String::into_bytes
* String::as_bytes
* String::len
* String::clear
* String::as_slice
The following methods have been marked #[unstable]
* String::from_utf8 - The error type in the returned `Result` may change to
provide a nicer message when it's `unwrap()`'d
* String::from_utf8_lossy - The returned `MaybeOwned` type still needs
stabilization
* String::from_utf16 - The return type may change to become a `Result` which
includes more contextual information like where the error
occurred.
* String::from_chars - This is equivalent to iter().collect(), but currently not
as ergonomic.
* String::from_char - This method is the equivalent of Vec::from_elem, and has
been marked #[unstable] becuase it can be seen as a
duplicate of iterator-based functionality as well as
possibly being renamed.
* String::push_str - This *can* be emulated with .extend(foo.chars()), but is
less efficient because of decoding/encoding. Due to the
desire to minimize API surface this may be able to be
removed in the future for something possibly generic with
no loss in performance.
* String::grow - This is a duplicate of iterator-based functionality, which may
become more ergonomic in the future.
* String::capacity - This function was just added.
* String::push - This function was just added.
* String::pop - This function was just added.
* String::truncate - The failure conventions around String methods and byte
indices isn't totally clear at this time, so the failure
semantics and return value of this method are subject to
change.
* String::as_mut_vec - the naming of this method may change.
* string::raw::* - these functions are all waiting on [an RFC][2]
[2]: rust-lang/rfcs#240
The following method have been marked #[experimental]
* String::from_str - This function only exists as it's more efficient than
to_string(), but having a less ergonomic function for
performance reasons isn't the greatest reason to keep it
around. Like Vec::push_all, this has been marked
experimental for now.
The following methods have been #[deprecated]
* String::append - This method has been deprecated to remain consistent with the
deprecation of Vec::append. While convenient, it is one of
the only functional-style apis on String, and requires more
though as to whether it belongs as a first-class method or
now (and how it relates to other collections).
* String::from_byte - This is fairly rare functionality and can be emulated with
str::from_utf8 plus an assert plus a call to to_string().
Additionally, String::from_char could possibly be used.
* String::byte_capacity - Renamed to String::capacity due to the rationale
above.
* String::push_char - Renamed to String::push due to the rationale above.
* String::pop_char - Renamed to String::pop due to the rationale above.
* String::push_bytes - There are a number of `unsafe` functions on the `String`
type which allow bypassing utf-8 checks. These have all
been deprecated in favor of calling `.as_mut_vec()` and
then operating directly on the vector returned. These
methods were deprecated because naming them with relation
to other methods was difficult to rationalize and it's
arguably more composable to call .as_mut_vec().
* String::as_mut_bytes - See push_bytes
* String::push_byte - See push_bytes
* String::pop_byte - See push_bytes
* String::shift_byte - See push_bytes
# Reservation methods
This commit does not yet touch the methods for reserving bytes. The methods on
Vec have also not yet been modified. These methods are discussed in the upcoming
[Collections reform RFC][1]
[1]: https://github.com/aturon/rfcs/blob/collections-conventions/active/0000-collections-conventions.md#implicit-growth
Setting LC_ALL to C helps keep gdb's output consistent ('print' gives us expected output). This fixes#17423. I do not have access to a windows/mac machines to test this. I've only tested it on an x86_64 linux box.
This PR adds a new Vim compiler file specifically for use with Cargo. It passes all arguments through, so commands like `:make build`, `:make clean`, and `:make run` all work as expected.
It also adds a quickfix autocommand for fixing the paths before populating the error list. `cargo build` reports errors with file paths that are relative to Cargo.toml, so if you're further down in the project tree, then trying to open the error will result in a blank buffer because Vim treats that path as relative to the working directory instead. With this fix, the paths work properly no matter where you are in the project.
Right now, libuv will **always** be built for the host system (at least when building on OSX) because the information about the cross compiler is never actually passed to GYP. I don't know how anybody has been managing to build cross compilers with this.
Note that, at least on OSX, there is a bug in GYP that will send clang flags to non-clang compilers and it will still attempt to use Xcode's libtool, so this doesn't completely fix the problem of cross-compiling on an OSX host, but it's a start.
When I fixed the previous issue with rational rounding, I had introduced a regression. There was also an overflow bug introduced for fixed-precision rationals. This patch corrects both bugs.
Because I'm still 😷😷😷 , I figured some mindless tasks would be better than trying to finish the ownership guide.
The manual has long been waiting for some ❤️❤️❤️ , and so I gave it a quick once-over. I made small commits in case any of the changes are a bit weird, I mostly did a few things:
1. changed 'manual' to 'reference.' I feel like this name is better. If it's not, It's not a huge deal. it shouldn't be `rust.md` though.
2. word wrapped everything appropriately. Changes 1&2 are in the first commit, so that its' easier to see the changes in the later ones.
3. fixed other small style issues
4. removed references to things that are in the standard library, and not the language itself
There's still lots of gross in here, but I didn't want to pile on too too many changes.
/cc @brson @nikomatsakis
See: http://doc.rust-lang.org/std/from_str/trait.FromStr.html
```
let input_num = from_str::<Option<uint>>("5");
```
```
<anon>:2:21: 2:45 error: failed to find an implementation of trait std::from_str::FromStr for core::option::Option<uint>
<anon>:2 let input_num = from_str::<Option<uint>>("5");
^~~~~~~~~~~~~~~~~~~~~~~~
```
While reading the intro, I was confused as to why there were two variables named "numbers". Unless I'm mistaken and it's not necessary, let's get rid of it to make it clearer.
This breaks code like:
struct Foo {
...
}
pub fn make_foo() -> Foo {
...
}
Change this code to:
pub struct Foo { // note `pub`
...
}
pub fn make_foo() -> Foo {
...
}
The `visible_private_types` lint has been removed, since it is now an
error to attempt to expose a private type in a public API.
Closes#16463.
RFC #48.
[breaking-change]
r? @alexcrichton
This breaks code like:
struct Foo {
...
}
pub fn make_foo() -> Foo {
...
}
Change this code to:
pub struct Foo { // note `pub`
...
}
pub fn make_foo() -> Foo {
...
}
The `visible_private_types` lint has been removed, since it is now an
error to attempt to expose a private type in a public API. In its place
a `#[feature(visible_private_types)]` gate has been added.
Closes#16463.
RFC #48.
[breaking-change]
Closes#17185.
The stability lint will now check code generated by macro expansion. It will allow to detect :
- arguments passed to macros using deprecated (and others) items
- macro expansion generating code using deprecated items due to its arguments (hence the second commit, fixing such issue found in libcollections)
Checking is still done at expansion, but it will also detect a macro explicitly using a deprecated item in its definition.
- Don't attempt to autoderef `!`. The `Deref`/`DerefMut` trait lookup would generate a bunch of unhelpful error spew.
- Don't allow explicit deref of `!`, since later passes just ICE. This closes issue #17373
- Don't allow explicit index of `!`, since later passes just ICE. There does not seem to be an issue associated with this
This is just true of all of Rust, and doesn't make a lot of sense now.
Especially as we move towards finalizing things, I think it's time for
this to go.
