Rollup merge of rust-lang#40452 - frewsxcv:frewsxcv-unstable-docs, r=GuillaumeGomez

Add basic documentation/examples for six unstable features.

Author: frewsxcv

cargo

@@ -6,5 +6,17 @@ The tracking issue for this feature is: [#29599]
 
 ------------------------
 
+The `concat_idents` feature adds a macro for concatenating multiple identifiers
+into one identifier.
 
+## Examples
 
+```rust
+#![feature(concat_idents)]
+
+fn main() {
+    fn foobar() -> u32 { 23 }
+    let f = concat_idents!(foo, bar);
+    assert_eq!(f(), 23);
+}
+```

src/doc/unstable-book/src/concat-idents.md

@@ -6,5 +6,61 @@ The tracking issue for this feature is: [#34511]
 
 ------------------------
 
+The `conservative_impl_trait` feature allows a conservative form of abstract
+return types.
 
+Abstract return types allow a function to hide a concrete return type behind a
+trait interface similar to trait objects, while still generating the same
+statically dispatched code as with concrete types.
 
+## Examples
+
+```rust
+#![feature(conservative_impl_trait)]
+
+fn even_iter() -> impl Iterator<Item=u32> {
+    (0..).map(|n| n * 2)
+}
+
+fn main() {
+    let first_four_even_numbers = even_iter().take(4).collect::<Vec<_>>();
+    assert_eq!(first_four_even_numbers, vec![0, 2, 4, 6]);
+}
+```
+
+## Background
+
+In today's Rust, you can write function signatures like:
+
+````rust,ignore
+fn consume_iter_static<I: Iterator<u8>>(iter: I) { }
+
+fn consume_iter_dynamic(iter: Box<Iterator<u8>>) { }
+````
+
+In both cases, the function does not depend on the exact type of the argument.
+The type held is "abstract", and is assumed only to satisfy a trait bound.
+
+* In the `_static` version using generics, each use of the function is
+  specialized to a concrete, statically-known type, giving static dispatch,
+  inline layout, and other performance wins.
+* In the `_dynamic` version using trait objects, the concrete argument type is
+  only known at runtime using a vtable.
+
+On the other hand, while you can write:
+
+````rust,ignore
+fn produce_iter_dynamic() -> Box<Iterator<u8>> { }
+````
+
+...but you _cannot_ write something like:
+
+````rust,ignore
+fn produce_iter_static() -> Iterator<u8> { }
+````
+
+That is, in today's Rust, abstract return types can only be written using trait
+objects, which can be a significant performance penalty. This RFC proposes
+"unboxed abstract types" as a way of achieving signatures like
+`produce_iter_static`. Like generics, unboxed abstract types guarantee static
+dispatch and inline data layout.

src/doc/unstable-book/src/conservative-impl-trait.md

@@ -6,5 +6,24 @@ The tracking issue for this feature is: [#24111]
 
 ------------------------
 
+The `const_fn` feature allows marking free functions and inherent methods as
+`const`, enabling them to be called in constants contexts, with constant
+arguments.
 
+## Examples
 
+```rust
+#![feature(const_fn)]
+
+const fn double(x: i32) -> i32 {
+    x * 2
+}
+
+const FIVE: i32 = 5;
+const TEN: i32 = double(FIVE);
+
+fn main() {
+    assert_eq!(5, FIVE);
+    assert_eq!(10, TEN);
+}
+```

src/doc/unstable-book/src/const-fn.md

@@ -6,5 +6,14 @@ The tracking issue for this feature is: [#29947]
 
 ------------------------
 
+The `const_indexing` feature allows the constant evaluation of index operations
+on constant arrays and repeat expressions.
 
+## Examples
 
+```rust
+#![feature(const_indexing)]
+
+const ARR: [usize; 5] = [1, 2, 3, 4, 5];
+const ARR2: [usize; ARR[1]] = [42, 99];
+```

src/doc/unstable-book/src/const-indexing.md

@@ -6,5 +6,20 @@ The tracking issue for this feature is: [#35118]
 
 ------------------------
 
+The `i128_type` feature adds support for 128 bit signed and unsigned integer
+types.
 
+```rust
+#![feature(i128_type)]
+
+fn main() {
+    assert_eq!(1u128 + 1u128, 2u128);
+    assert_eq!(u128::min_value(), 0);
+    assert_eq!(u128::max_value(), 340282366920938463463374607431768211455);
+
+    assert_eq!(1i128 - 2i128, -1i128);
+    assert_eq!(i128::min_value(), -170141183460469231731687303715884105728);
+    assert_eq!(i128::max_value(), 170141183460469231731687303715884105727);
+}
+```
 

src/doc/unstable-book/src/i128-type.md

@@ -6,5 +6,13 @@ The tracking issue for this feature is: [#28979]
 
 ------------------------
 
+The `non_ascii_idents` feature adds support for non-ASCII identifiers.
 
+## Examples
 
+```rust
+#![feature(non_ascii_idents)]
+
+const ε: f64 = 0.00001f64;
+const Π: f64 = 3.14f64;
+```