]>
Commit | Line | Data |
---|---|---|
85aaf69f SL |
1 | % Output from functions and methods |
2 | ||
3 | ### Don't overpromise. [FIXME] | |
4 | ||
5 | > **[FIXME]** Add discussion of overly-specific return types, | |
6 | > e.g. returning a compound iterator type rather than hiding it behind | |
7 | > a use of newtype. | |
8 | ||
9 | ### Let clients choose what to throw away. [FIXME: needs RFC] | |
10 | ||
11 | #### Return useful intermediate results: | |
12 | ||
13 | Many functions that answer a question also compute interesting related data. If | |
14 | this data is potentially of interest to the client, consider exposing it in the | |
15 | API. | |
16 | ||
17 | Prefer | |
18 | ||
19 | ```rust | |
20 | struct SearchResult { | |
21 | found: bool, // item in container? | |
62682a34 | 22 | expected_index: usize // what would the item's index be? |
85aaf69f SL |
23 | } |
24 | ||
25 | fn binary_search(&self, k: Key) -> SearchResult | |
26 | ``` | |
27 | or | |
28 | ||
29 | ```rust | |
62682a34 | 30 | fn binary_search(&self, k: Key) -> (bool, usize) |
85aaf69f SL |
31 | ``` |
32 | ||
33 | over | |
34 | ||
35 | ```rust | |
36 | fn binary_search(&self, k: Key) -> bool | |
37 | ``` | |
38 | ||
39 | #### Yield back ownership: | |
40 | ||
41 | Prefer | |
42 | ||
43 | ```rust | |
44 | fn from_utf8_owned(vv: Vec<u8>) -> Result<String, Vec<u8>> | |
45 | ``` | |
46 | ||
47 | over | |
48 | ||
49 | ```rust | |
50 | fn from_utf8_owned(vv: Vec<u8>) -> Option<String> | |
51 | ``` | |
52 | ||
53 | The `from_utf8_owned` function gains ownership of a vector. In the successful | |
54 | case, the function consumes its input, returning an owned string without | |
55 | allocating or copying. In the unsuccessful case, however, the function returns | |
56 | back ownership of the original slice. |