From de623a766891d3d3088500d7ff0439c44fa1d739 Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel.jakob@epfl.ch>
Date: Wed, 9 Mar 2016 21:11:19 +0100
Subject: [PATCH] added faq

---
 docs/faq.rst   | 37 +++++++++++++++++++++++++++++++++++++
 docs/index.rst |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 docs/faq.rst

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 000000000..45cb70ecb
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,37 @@
+Frequently asked questions
+##########################
+
+(under construction)
+
+Limitations involving reference arguments
+=========================================
+
+In C++, it's fairly common to pass arguments using mutable references or
+mutable pointers, which allows both read and write access to the value
+supplied by the caller. This is sometimes done for efficiency reasons, or to
+realize functions that have multiple return values. Here are two very basic
+examples:
+
+.. code-block:: cpp
+
+    void increment(int &i) { i++; }
+    void increment_ptr(int *i) { (*i)++; }
+
+In Python, all arguments are passed by reference, so there is no general
+issue in binding such code from Python.
+
+However, certain basic Python types (like ``str``, ``int``, ``bool``,
+``float``, etc.) are **immutable**. This means that the following attempt
+to port the function to Python doesn't have the same effect on the value
+provided by the caller -- in fact, it does nothing at all.
+
+.. code-block:: python
+
+    def increment(i):
+        i += 1 # nope..
+
+pybind11 is also affected by such language-level conventions, which means
+that binding ``increment`` or ``increment_ptr`` will also create Python functions that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types
+in a custom type that does allow modifications.
diff --git a/docs/index.rst b/docs/index.rst
index b9afea5fb..a06a46cc5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,5 +14,6 @@ Contents:
    advanced
    cmake
    benchmark
+   faq
    reference
    changelog