From 39676c8bf0ad0fe7249f788ab6ab6790360af73c Mon Sep 17 00:00:00 2001 From: Sebastian Gesemann Date: Fri, 16 Jan 2015 08:31:01 +0100 Subject: [PATCH] Fix/update core::ops module documentation w.r.t. operator traits * Not all traits are part of the prelude anymore * We switched from pass-by-reference to pass-by-value for most traits * Add some explanations around pass-by-value traits in the context of generic code and additional implementations for reference types. --- src/libcore/ops.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs index 144019147af7..88e0aac2b123 100644 --- a/src/libcore/ops.rs +++ b/src/libcore/ops.rs @@ -13,12 +13,20 @@ //! Implementing these traits allows you to get an effect similar to //! overloading operators. //! -//! The values for the right hand side of an operator are automatically -//! borrowed, so `a + b` is sugar for `a.add(&b)`. -//! -//! All of these traits are imported by the prelude, so they are available in +//! Some of these traits are imported by the prelude, so they are available in //! every Rust program. //! +//! Many of the operators take their operands by value. In non-generic +//! contexts involving built-in types, this is usually not a problem. +//! However, using these operators in generic code, requires some +//! attention if values have to be reused as opposed to letting the operators +//! consume them. One option is to occasionally use `clone()`. +//! Another option is to rely on the types involved providing additional +//! operator implementations for references. For example, for a user-defined +//! type `T` which is supposed to support addition, it is probably a good +//! idea to have both `T` and `&T` implement the traits `Add` and `Add<&T>` +//! so that generic code can be written without unnecessary cloning. +//! //! # Example //! //! This example creates a `Point` struct that implements `Add` and `Sub`, and then