Skip to content

Commit d796dba

Browse files
pnkfelixpnkfelix
committed
---
yaml --- r: 196351 b: refs/heads/master c: eaea188 h: refs/heads/master i: 196349: 8e31908 196347: 8aa2f14 196343: 1c53e8f 196335: e61e6e1 196319: fd00f04 196287: 3c95f05 196223: 6461628 196095: f0a51c3 v: v3
1 parent fde38ca commit d796dba

File tree

10 files changed

+167
-466
lines changed

10 files changed

+167
-466
lines changed

‎[refs]

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
refs/heads/master: d17d6e7f1f05fbdd4d9d246400ffebf768878c7a
2+
refs/heads/master: eaea188d9674c8b9eba36dec5f20277a6fe7ae43
33
refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
44
refs/heads/snap-stage3: b3317d68910900f135f9f38e43a7a699bc736b4a
55
refs/heads/try: 961e0358e1a5c0faaef606e31e9965742c1643bf

‎trunk/src/doc/trpl/SUMMARY.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,5 @@
4343
* [Lang items](lang-items.md)
4444
* [Link args](link-args.md)
4545
* [Benchmark Tests](benchmark-tests.md)
46-
* [Box Syntax and Patterns](box-syntax-and-patterns.md)
4746
* [Conclusion](conclusion.md)
4847
* [Glossary](glossary.md)

‎trunk/src/doc/trpl/box-syntax-and-patterns.md

Lines changed: 0 additions & 100 deletions
This file was deleted.

‎trunk/src/doc/trpl/pointers.md

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -574,7 +574,7 @@ fn main() {
574574
```
575575

576576
We can mutably borrow `x` multiple times, but only if x itself is mutable, and
577-
it may not be *simultaneously* borrowed:
577+
it may not be *simultaneously* borrowed:
578578

579579
```{rust,ignore}
580580
fn increment(x: &mut i32) {
@@ -595,7 +595,8 @@ Notice the signature of `increment()` requests a mutable reference.
595595

596596
## Best practices
597597

598-
Boxes are most appropriate to use when defining recursive data structures.
598+
Boxes are appropriate to use in two situations: Recursive data structures,
599+
and occasionally, when returning data.
599600

600601
### Recursive data structures
601602

@@ -629,6 +630,14 @@ we don't know the size, and therefore, we need to heap allocate our list.
629630
Working with recursive or other unknown-sized data structures is the primary
630631
use-case for boxes.
631632

633+
### Returning data
634+
635+
This is important enough to have its own section entirely. The TL;DR is this:
636+
you don't want to return pointers, even when you might in a language like C or
637+
C++.
638+
639+
See [Returning Pointers](#returning-pointers) below for more.
640+
632641
# Rc and Arc
633642

634643
This part is coming soon.
@@ -645,6 +654,79 @@ This part is coming soon.
645654

646655
This part is coming soon.
647656

657+
# Returning Pointers
658+
659+
In many languages with pointers, you'd return a pointer from a function
660+
so as to avoid copying a large data structure. For example:
661+
662+
```{rust}
663+
struct BigStruct {
664+
one: i32,
665+
two: i32,
666+
// etc
667+
one_hundred: i32,
668+
}
669+
670+
fn foo(x: Box<BigStruct>) -> Box<BigStruct> {
671+
Box::new(*x)
672+
}
673+
674+
fn main() {
675+
let x = Box::new(BigStruct {
676+
one: 1,
677+
two: 2,
678+
one_hundred: 100,
679+
});
680+
681+
let y = foo(x);
682+
}
683+
```
684+
685+
The idea is that by passing around a box, you're only copying a pointer, rather
686+
than the hundred `int`s that make up the `BigStruct`.
687+
688+
This is an antipattern in Rust. Instead, write this:
689+
690+
```rust
691+
#![feature(box_syntax)]
692+
693+
struct BigStruct {
694+
one: i32,
695+
two: i32,
696+
// etc
697+
one_hundred: i32,
698+
}
699+
700+
fn foo(x: Box<BigStruct>) -> BigStruct {
701+
*x
702+
}
703+
704+
fn main() {
705+
let x = Box::new(BigStruct {
706+
one: 1,
707+
two: 2,
708+
one_hundred: 100,
709+
});
710+
711+
let y: Box<BigStruct> = box foo(x);
712+
}
713+
```
714+
715+
Note that this uses the `box_syntax` feature gate, so this syntax may change in
716+
the future.
717+
718+
This gives you flexibility without sacrificing performance.
719+
720+
You may think that this gives us terrible performance: return a value and then
721+
immediately box it up ?! Isn't this pattern the worst of both worlds? Rust is
722+
smarter than that. There is no copy in this code. `main` allocates enough room
723+
for the `box`, passes a pointer to that memory into `foo` as `x`, and then
724+
`foo` writes the value straight into the `Box<T>`.
725+
726+
This is important enough that it bears repeating: pointers are not for
727+
optimizing returning values from your code. Allow the caller to choose how they
728+
want to use your output.
729+
648730
# Creating your own Pointers
649731

650732
This part is coming soon.

‎trunk/src/libcollections/fmt.rs

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -368,12 +368,12 @@
368368
//! should always be printed.
369369
//! * '-' - Currently not used
370370
//! * '#' - This flag is indicates that the "alternate" form of printing should
371-
//! be used. For array slices, the alternate form omits the brackets.
372-
//! For the integer formatting traits, the alternate forms are:
373-
//! * `#x` - precedes the argument with a "0x"
374-
//! * `#X` - precedes the argument with a "0x"
375-
//! * `#t` - precedes the argument with a "0b"
376-
//! * `#o` - precedes the argument with a "0o"
371+
//! be used. By default, this only applies to the integer formatting
372+
//! traits and performs like:
373+
//! * `x` - precedes the argument with a "0x"
374+
//! * `X` - precedes the argument with a "0x"
375+
//! * `t` - precedes the argument with a "0b"
376+
//! * `o` - precedes the argument with a "0o"
377377
//! * '0' - This is used to indicate for integer formats that the padding should
378378
//! both be done with a `0` character as well as be sign-aware. A format
379379
//! like `{:08}` would yield `00000001` for the integer `1`, while the

‎trunk/src/liblibc/lib.rs

Lines changed: 9 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -863,16 +863,13 @@ pub mod types {
863863
pub sa_data: [u8; 14],
864864
}
865865
#[repr(C)]
866-
#[derive(Copy)] pub struct sockaddr_storage {
866+
#[derive(Copy, Clone)] pub struct sockaddr_storage {
867867
pub ss_len: u8,
868868
pub ss_family: sa_family_t,
869869
pub __ss_pad1: [u8; 6],
870870
pub __ss_align: i64,
871871
pub __ss_pad2: [u8; 112],
872872
}
873-
impl ::core::clone::Clone for sockaddr_storage {
874-
fn clone(&self) -> sockaddr_storage { *self }
875-
}
876873
#[repr(C)]
877874
#[derive(Copy, Clone)] pub struct sockaddr_in {
878875
pub sin_len: u8,
@@ -920,14 +917,11 @@ pub mod types {
920917
pub ai_next: *mut addrinfo,
921918
}
922919
#[repr(C)]
923-
#[derive(Copy)] pub struct sockaddr_un {
920+
#[derive(Copy, Clone)] pub struct sockaddr_un {
924921
pub sun_len: u8,
925922
pub sun_family: sa_family_t,
926923
pub sun_path: [c_char; 104]
927924
}
928-
impl ::core::clone::Clone for sockaddr_un {
929-
fn clone(&self) -> sockaddr_un { *self }
930-
}
931925
#[repr(C)]
932926
#[derive(Copy, Clone)] pub struct ifaddrs {
933927
pub ifa_next: *mut ifaddrs,
@@ -1131,16 +1125,13 @@ pub mod types {
11311125
pub sa_data: [u8; 14],
11321126
}
11331127
#[repr(C)]
1134-
#[derive(Copy)] pub struct sockaddr_storage {
1128+
#[derive(Copy, Clone)] pub struct sockaddr_storage {
11351129
pub ss_len: u8,
11361130
pub ss_family: sa_family_t,
11371131
pub __ss_pad1: [u8; 6],
11381132
pub __ss_align: i64,
11391133
pub __ss_pad2: [u8; 112],
11401134
}
1141-
impl ::core::clone::Clone for sockaddr_storage {
1142-
fn clone(&self) -> sockaddr_storage { *self }
1143-
}
11441135
#[repr(C)]
11451136
#[derive(Copy, Clone)] pub struct sockaddr_in {
11461137
pub sin_len: u8,
@@ -1188,14 +1179,11 @@ pub mod types {
11881179
pub ai_next: *mut addrinfo,
11891180
}
11901181
#[repr(C)]
1191-
#[derive(Copy)] pub struct sockaddr_un {
1182+
#[derive(Copy, Clone)] pub struct sockaddr_un {
11921183
pub sun_len: u8,
11931184
pub sun_family: sa_family_t,
11941185
pub sun_path: [c_char; 104]
11951186
}
1196-
impl ::core::clone::Clone for sockaddr_un {
1197-
fn clone(&self) -> sockaddr_un { *self }
1198-
}
11991187
#[repr(C)]
12001188
#[derive(Copy, Clone)] pub struct ifaddrs {
12011189
pub ifa_next: *mut ifaddrs,
@@ -1417,16 +1405,13 @@ pub mod types {
14171405
pub sa_data: [u8; 14],
14181406
}
14191407
#[repr(C)]
1420-
#[derive(Copy)] pub struct sockaddr_storage {
1408+
#[derive(Copy, Clone)] pub struct sockaddr_storage {
14211409
pub ss_len: u8,
14221410
pub ss_family: sa_family_t,
14231411
pub __ss_pad1: [u8; 6],
14241412
pub __ss_pad2: i64,
14251413
pub __ss_pad3: [u8; 240],
14261414
}
1427-
impl ::core::clone::Clone for sockaddr_storage {
1428-
fn clone(&self) -> sockaddr_storage { *self }
1429-
}
14301415
#[repr(C)]
14311416
#[derive(Copy, Clone)] pub struct sockaddr_in {
14321417
pub sin_len: u8,
@@ -1474,14 +1459,11 @@ pub mod types {
14741459
pub ai_next: *mut addrinfo,
14751460
}
14761461
#[repr(C)]
1477-
#[derive(Copy)] pub struct sockaddr_un {
1462+
#[derive(Copy, Clone)] pub struct sockaddr_un {
14781463
pub sun_len: u8,
14791464
pub sun_family: sa_family_t,
14801465
pub sun_path: [c_char; 104]
14811466
}
1482-
impl ::core::clone::Clone for sockaddr_un {
1483-
fn clone(&self) -> sockaddr_un { *self }
1484-
}
14851467
#[repr(C)]
14861468
#[derive(Copy, Clone)] pub struct ifaddrs {
14871469
pub ifa_next: *mut ifaddrs,
@@ -3134,7 +3116,7 @@ pub mod consts {
31343116
pub const MAP_FIXED : c_int = 0x0010;
31353117
pub const MAP_ANON : c_int = 0x0800;
31363118

3137-
pub const MAP_FAILED : *mut c_void = !0 as *mut c_void;
3119+
pub const MAP_FAILED : *mut c_void = -1 as *mut c_void;
31383120

31393121
pub const MCL_CURRENT : c_int = 0x0001;
31403122
pub const MCL_FUTURE : c_int = 0x0002;
@@ -3870,7 +3852,7 @@ pub mod consts {
38703852
pub const MAP_FIXED : c_int = 0x0010;
38713853
pub const MAP_ANON : c_int = 0x1000;
38723854

3873-
pub const MAP_FAILED : *mut c_void = !0 as *mut c_void;
3855+
pub const MAP_FAILED : *mut c_void = -1 as *mut c_void;
38743856

38753857
pub const MCL_CURRENT : c_int = 0x0001;
38763858
pub const MCL_FUTURE : c_int = 0x0002;
@@ -4324,7 +4306,7 @@ pub mod consts {
43244306
pub const MAP_FIXED : c_int = 0x0010;
43254307
pub const MAP_ANON : c_int = 0x1000;
43264308

4327-
pub const MAP_FAILED : *mut c_void = !0 as *mut c_void;
4309+
pub const MAP_FAILED : *mut c_void = -1 as *mut c_void;
43284310

43294311
pub const MCL_CURRENT : c_int = 0x0001;
43304312
pub const MCL_FUTURE : c_int = 0x0002;

0 commit comments

Comments
 (0)