From 12ee697a336a8ef192e926914e7e170534e24e5b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Adjemian=20=28Charybdis=29?=
<stepan@adjemian.eu>
Date: Sun, 16 Feb 2020 11:42:57 +0100
Subject: [PATCH] Introduce underscore methods.
---
doc/manual/source/time-series.rst | 27 ++++++++++++++++++++++-----
1 file changed, 22 insertions(+), 5 deletions(-)
diff --git a/doc/manual/source/time-series.rst b/doc/manual/source/time-series.rst
index 7dfa410bae..125da7662a 100644
--- a/doc/manual/source/time-series.rst
+++ b/doc/manual/source/time-series.rst
@@ -251,20 +251,37 @@ The dates class
A list of the available methods, by alphabetical order, is given
- below. Note that the MATLAB/Octave classes do not allow in place
+ below. Note that by default the methods do not allow in place
modifications: when a method is applied to an object a new object
is instantiated. For instance, to apply the method
``multiplybytwo`` to an object ``X`` we write::
- Y = X.multiplybytwo()
+ >> X = 2;
+ >> Y = X.multiplybytwo();
+ >> X
+ 2
+ >> Y
+ 4
+
or equivalently::
- Y = multiplybytwo(X)
+ >> Y = multiplybytwo(X);
the object ``X`` is left unchanged, and the object ``Y`` is a
- modified copy of ``X``.
-
+ modified copy of ``X`` (multiplied by two). This behaviour is
+ altered if the name of the method is postfixed with an
+ underscore. In this case the creation of a copy is avoided. For
+ instance, following the previous example, we would have::
+
+ >> X = 2;
+ >> X.multiplybytwo_();
+ >> X
+ 4
+
+ Modifying the objects in place, with underscore methods, is
+ particularly useful if the methods are called in loops, since this
+ saves the object instantiation overhead.
.. datesmethod:: C = append (A, B)
--
GitLab