src/doc/style/features/functions-and-methods/output.md

   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?
  22     expected_index: uint  // what would the item's index be?
  23 }
  24
  25 fn binary_search(&self, k: Key) -> SearchResult
  26 ```
  27 or
  28
  29 ```rust
  30 fn binary_search(&self, k: Key) -> (bool, uint)
  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.