rustdoc: refactor and unstyle inline section headers
doc: perform some 80-chars wrappings
rustdoc: style tweaks
Add a streaming parser to serialize::json.
Fix a code formatting issue in json.rs
Update libworkcache with libserialize's json changes
Fix test issue-4016.rs with the json API change
std: Rewrite crate docs

Also move prelude explanation to the prelude module.
rustdoc: fix a few inconsistencies
Provide an implementation of DoubleEndedIterator for the results of &[T]::split and &[T]::rsplit

This makes the splitting functions in std::slice return DoubleEndedIterators. Unfortunately,
splitn and rsplitn cannot provide such an interface and so must return different types. As a
result, the following changes were made:

* RevSplits was removed in favor of explicitly using Rev
* Splits can no longer bound the number of splits done
* Splits now implements DoubleEndedIterator
* SplitsN was added, taking the role of what both Splits and RevSplits used to be
* rsplit returns Rev<Splits<'a, T>> instead of RevSplits<'a, T>
* splitn returns SplitsN<'a, T> instead of Splits<'a, T>
* rsplitn returns SplitsN<'a, T> instead of RevSplits<'a, T>

All functions that were previously implemented on each return value still are, so outside of changing
of type annotations, existing code should work out of the box. In the rare case that code relied
on the return types of split and splitn or of rsplit and rsplitn being the same, the previous
behavior can be emulated by calling splitn or rsplitn with a bount of uint::MAX.

The value of this change comes in multiple parts:

* Consistency. The splitting code in std::str is structured similarly to the new slice splitting code,
  having separate CharSplits and CharSplitsN types.
* Smaller API. Although this commit doesn't implement it, using a DoubleEndedIterator for splitting
  means that rsplit, path::RevComponents, path::RevStrComponents, Path::rev_components, and
  Path::rev_str_components are no longer needed - they can be emulated simply with .rev().
* Power. DoubleEndedIterators are able to traverse the list from both sides at once instead of only
  forwards or backwards.
* Efficiency. For the common case of using split instead of splitn, the iterator is slightly smaller
  and slightly faster.

[breaking-change]
Deprecate the rev_iter pattern in all places where a DoubleEndedIterator is provided (everywhere but treemap)

This commit deprecates rev_iter, mut_rev_iter, move_rev_iter everywhere (except treemap) and also
deprecates related functions like rsplit, rev_components, and rev_str_components. In every case,
these functions can be replaced with the non-reversed form followed by a call to .rev(). To make this
more concrete, a translation table for all functional changes necessary follows:

* container.rev_iter() -> container.iter().rev()
* container.mut_rev_iter() -> container.mut_iter().rev()
* container.move_rev_iter() -> container.move_iter().rev()
* sliceorstr.rsplit(sep) -> sliceorstr.split(sep).rev()
* path.rev_components() -> path.components().rev()
* path.rev_str_components() -> path.str_components().rev()

In terms of the type system, this change also deprecates any specialized reversed iterator types (except
in treemap), opting instead to use Rev directly if any type annotations are needed. However, since
methods directly returning reversed iterators are now discouraged, the need for such annotations should
be small. However, in those cases, the general pattern for conversion is to take whatever follows Rev in
the original reversed name and surround it with Rev<>:

* RevComponents<'a> -> Rev<Components<'a>>
* RevStrComponents<'a> -> Rev<StrComponents<'a>>
* RevItems<'a, T> -> Rev<Items<'a, T>>
* etc.

The reasoning behind this change is that it makes the standard API much simpler without reducing readability,
performance, or power. The presence of functions such as rev_iter adds more boilerplate code to libraries
(all of which simply call .iter().rev()), clutters up the documentation, and only helps code by saving two
characters. Additionally, the numerous type synonyms that were used to make the type signatures look nice
like RevItems add even more boilerplate and clutter up the docs even more. With this change, all that cruft
goes away.

[breaking-change]
regex: remove the use of ~[] & some unnecessary ~'s.

The AST doesn't need ~s everywhere, so we can save allocations this way
& the enum isn't particularly large (~4 words) nor are regexes
long (normally), so the space saved in the `Cat` vector is unlikely to
be very much.
mk: Depend on regex_macros for tests appropriately

There is currently not much precedent for target crates requiring syntax
extensions to compile their test versions. This dependency is possible, but
can't be encoded through the normal means of DEPS_regex because it is a
test-only dependency and it must be a *host* dependency (it's a syntax
extension).

Closes #13844
rustc: Enable -f{function,data}-sections

The compiler has previously been producing binaries on the order of 1.8MB for
hello world programs "fn main() {}". This is largely a result of the compilation
model used by compiling entire libraries into a single object file and because
static linking is favored by default.

When linking, linkers will pull in the entire contents of an object file if any
symbol from the object file is used. This means that if any symbol from a rust
library is used, the entire library is pulled in unconditionally, regardless of
whether the library is used or not.

Traditional C/C++ projects do not normally encounter these large executable
problems because their archives (rust's rlibs) are composed of many objects.
Because of this, linkers can eliminate entire objects from being in the final
executable. With rustc, however, the linker does not have the opportunity to
leave out entire object files.

In order to get similar benefits from dead code stripping at link time, this
commit enables the -ffunction-sections and -fdata-sections flags in LLVM, as
well as passing --gc-sections to the linker *by default*. This means that each
function and each global will be placed into its own section, allowing the
linker to GC all unused functions and data symbols.

By enabling these flags, rust is able to generate much smaller binaries default.
On linux, a hello world binary went from 1.8MB to 597K (a 67% reduction in
size). The output size of dynamic libraries remained constant, but the output
size of rlibs increased, as seen below:

    libarena         -  2.27% bigger (   292872 =>    299508)
    libcollections   -  0.64% bigger (  6765884 =>   6809076)
    libflate         -  0.83% bigger (   186516 =>    188060)
    libfourcc        - 14.71% bigger (   307290 =>    352498)
    libgetopts       -  4.42% bigger (   761468 =>    795102)
    libglob          -  2.73% bigger (   899932 =>    924542)
    libgreen         -  9.63% bigger (  1281718 =>   1405124)
    libhexfloat      - 13.88% bigger (   333738 =>    380060)
    liblibc          - 10.79% bigger (   551280 =>    610736)
    liblog           - 10.93% bigger (   218208 =>    242060)
    libnative        -  8.26% bigger (  1362096 =>   1474658)
    libnum           -  2.34% bigger (  2583400 =>   2643916)
    librand          -  1.72% bigger (  1608684 =>   1636394)
    libregex         -  6.50% bigger (  1747768 =>   1861398)
    librustc         -  4.21% bigger (151820192 => 158218924)
    librustdoc       -  8.96% bigger ( 13142604 =>  14320544)
    librustuv        -  4.13% bigger (  4366896 =>   4547304)
    libsemver        -  2.66% bigger (   396166 =>    406686)
    libserialize     -  1.91% bigger (  6878396 =>   7009822)
    libstd           -  3.59% bigger ( 39485286 =>  40902218)
    libsync          -  3.95% bigger (  1386390 =>   1441204)
    libsyntax        -  4.96% bigger ( 35757202 =>  37530798)
    libterm          - 13.99% bigger (   924580 =>   1053902)
    libtest          -  6.04% bigger (  2455720 =>   2604092)
    libtime          -  2.84% bigger (  1075708 =>   1106242)
    liburl           -  6.53% bigger (   590458 =>    629004)
    libuuid          -  4.63% bigger (   326350 =>    341466)
    libworkcache     -  8.45% bigger (  1230702 =>   1334750)

This increase in size is a result of encoding many more section names into each
object file (rlib). These increases are moderate enough that this change seems
worthwhile to me, due to the drastic improvements seen in the final artifacts.
The overall increase of the stage2 target folder (not the size of an install)
went from 337MB to 348MB (3% increase).

Additionally, linking is generally slower when executed with all these new
sections plus the --gc-sections flag. The stage0 compiler takes 1.4s to link the
`rustc` binary, where the stage1 compiler takes 1.9s to link the binary. Three
megabytes are shaved off the binary. I found this increase in link time to be
acceptable relative to the benefits of code size gained.

This commit only enables --gc-sections for *executables*, not dynamic libraries.
LLVM does all the heavy lifting when producing an object file for a dynamic
library, so there is little else for the linker to do (remember that we only
have one object file).

I conducted similar experiments by putting a *module's* functions and data
symbols into its own section (granularity moved to a module level instead of a
function/static level). The size benefits of a hello world were seen to be on
the order of 400K rather than 1.2MB. It seemed that enough benefit was gained
using ffunction-sections that this route was less desirable, despite the lesser
increases in binary rlib size.
auto merge of #13845 : alexcrichton/rust/regex-deps, r=brson

There is currently not much precedent for target crates requiring syntax
extensions to compile their test versions. This dependency is possible, but
can't be encoded through the normal means of DEPS_regex because it is a
test-only dependency and it must be a *host* dependency (it's a syntax
extension).

Closes #13844
auto merge of #13772 : brson/rust/cratedocs, r=alexcrichton

Also move prelude explanation to the prelude module.

This tries to provide a guide to what's in the standard library, organized bottom up from primitives to I/O.
auto merge of #13833 : alexcrichton/rust/ffunction-sections, r=thestinger

The compiler has previously been producing binaries on the order of 1.8MB for
hello world programs "fn main() {}". This is largely a result of the compilation
model used by compiling entire libraries into a single object file and because
static linking is favored by default.

When linking, linkers will pull in the entire contents of an object file if any
symbol from the object file is used. This means that if any symbol from a rust
library is used, the entire library is pulled in unconditionally, regardless of
whether the library is used or not.

Traditional C/C++ projects do not normally encounter these large executable
problems because their archives (rust's rlibs) are composed of many objects.
Because of this, linkers can eliminate entire objects from being in the final
executable. With rustc, however, the linker does not have the opportunity to
leave out entire object files.

In order to get similar benefits from dead code stripping at link time, this
commit enables the -ffunction-sections and -fdata-sections flags in LLVM, as
well as passing --gc-sections to the linker *by default*. This means that each
function and each global will be placed into its own section, allowing the
linker to GC all unused functions and data symbols.

By enabling these flags, rust is able to generate much smaller binaries default.
On linux, a hello world binary went from 1.8MB to 597K (a 67% reduction in
size). The output size of dynamic libraries remained constant, but the output
size of rlibs increased, as seen below:

    libarena       -  2.27% bigger
    libcollections -  0.64% bigger
    libflate       -  0.85% bigger
    libfourcc      - 14.67% bigger
    libgetopts     -  4.52% bigger
    libglob        -  2.74% bigger
    libgreen       -  9.68% bigger
    libhexfloat    - 13.68% bigger
    liblibc        - 10.79% bigger
    liblog         - 10.95% bigger
    libnative      -  8.34% bigger
    libnum         -  2.31% bigger
    librand        -  1.71% bigger
    libregex       -  6.43% bigger
    librustc       -  4.21% bigger
    librustdoc     -  8.98% bigger
    librustuv      -  4.11% bigger
    libsemver      -  2.68% bigger
    libserialize   -  1.92% bigger
    libstd         -  3.59% bigger
    libsync        -  3.96% bigger
    libsyntax      -  4.96% bigger
    libterm        - 13.96% bigger
    libtest        -  6.03% bigger
    libtime        -  2.86% bigger
    liburl         -  6.59% bigger
    libuuid        -  4.70% bigger
    libworkcache   -  8.44% bigger

This increase in size is a result of encoding many more section names into each
object file (rlib). These increases are moderate enough that this change seems
worthwhile to me, due to the drastic improvements seen in the final artifacts.
The overall increase of the stage2 target folder (not the size of an install)
went from 337MB to 348MB (3% increase).

Additionally, linking is generally slower when executed with all these new
sections plus the --gc-sections flag. The stage0 compiler takes 1.4s to link the
`rustc` binary, where the stage1 compiler takes 1.9s to link the binary. Three
megabytes are shaved off the binary. I found this increase in link time to be
acceptable relative to the benefits of code size gained.

This commit only enables --gc-sections for *executables*, not dynamic libraries.
LLVM does all the heavy lifting when producing an object file for a dynamic
library, so there is little else for the linker to do (remember that we only
have one object file).

I conducted similar experiments by putting a *module's* functions and data
symbols into its own section (granularity moved to a module level instead of a
function/static level). The size benefits of a hello world were seen to be on
the order of 400K rather than 1.2MB. It seemed that enough benefit was gained
using ffunction-sections that this route was less desirable, despite the lesser
increases in binary rlib size.
regex: General style tweaks.

For loops are nicer than manual whiles, etc.
auto merge of #13776 : adrientetar/rust/rustdoc-fix, r=brson

- Closes #13591. Relevant example: http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm
(Had to use `!important` to override CSS selector precedence, namely matching over parent class.)
- Implement changes from #13780 feedback, namely:
  * Changed font-size from 18px to 15px
  * Reintroduced gray background for code samples
  * Tightened up the margins
- Fix point 1 and point 4 of #13804.

Samples:

- [enum.FileType](http://adrientetar.legtux.org/cached/rust-docs/enum.FileType.htm)
- [struct.CChars](http://adrientetar.legtux.org/cached/rust-docs/struct.CChars.htm)
- [std](http://adrientetar.legtux.org/cached/rust-docs/std.htm)
- [std::io](http://adrientetar.legtux.org/cached/rust-docs/io.htm).

r? @brson
Add a bitflags! macro

The `bitflags!` macro generates a `struct` that holds a set of C-style bitmask flags. It is useful for creating typesafe wrappers for C APIs.

For example:

~~~rust
#[feature(phase)];
#[phase(syntax)] extern crate collections;

bitflags!(Flags: u32 {
    FlagA       = 0x00000001,
    FlagB       = 0x00000010,
    FlagC       = 0x00000100,
    FlagABC     = FlagA.bits
                | FlagB.bits
                | FlagC.bits
})

fn main() {
    let e1 = FlagA | FlagC;
    let e2 = FlagB | FlagC;
    assert!((e1 | e2) == FlagABC);   // union
    assert!((e1 & e2) == FlagC);     // intersection
    assert!((e1 - e2) == FlagA);     // set difference
}
~~~