Update docs for 4.5 release.

Author: cfis

4.x/_sources/bindings.rst.txt

@@ -14,6 +14,7 @@ Bindings
   bindings/enums
   bindings/constants
   bindings/iterators
+  bindings/arrays
   bindings/class_templates
   bindings/operators
   bindings/memory_management

4.x/_sources/bindings/callbacks.rst.txt

@@ -33,7 +33,7 @@ To wrap this code in Rice, first expose the register function to Ruby:
   rb_mCv.define_module_function("set_mouse_callback", &cv::setMouseCallback,
     Arg("winname"), Arg("on_mouse"), Arg("userdata") = static_cast<void *>(0));
 
-Next, in Ruby, define a Proc to handle the callback and then call the resgister exposed register function:
+Next, in Ruby, define a Proc to handle the callback and then call the register exposed register function:
 
 .. code-block:: ruby
 
@@ -46,18 +46,18 @@ Next, in Ruby, define a Proc to handle the callback and then call the resgister
 
   # Register the proc
   Cv::set_mouse_callback("Starry", on_mouse_event)
-  Module rb_mCv = define_module("Cv");
 
 You can also use ``lambdas`` in addition to ``Procs``
 
 User Data
 ^^^^^^^^^
-Notice that the ``MouseCallback`` callback defines a parameter called ``userdata`` which has a type of ``void*``. This is a common pattern in C style callbacks and allows clients to pass information into the callback - its a way of handling state.
+Notice that the ``MouseCallback`` callback defines a parameter called ``userdata`` which has a type of ``void*``. This is a common pattern in C style callbacks and allows clients to pass information into the callback - it's a way of handling state.
 
 Rice enables Ruby code to pass Ruby objects from the client to the callback. To do this, you must tell Rice that it should not try to convert the Ruby object to C++ or from C++ to Ruby. This is done by using the ``setOpaque`` method:
 
 .. code-block:: cpp
 
+  Module rb_mCv = define_module("Cv");
   rb_mCv.define_module_function("set_mouse_callback", &cv::setMouseCallback,
     Arg("winname"), Arg("on_mouse"), Arg("userdata").setOpaque() = static_cast<void *>(0));
 
@@ -67,9 +67,9 @@ Notice the addition of ``Arg("userdata").setOpaque()``. Ruby code can now call t
 
   Cv::set_mouse_callback("Starry", on_mouse_event, self)
 
-This allows the current Ruby object, self, to pass a reference to itself to the callback method.
+This allows the current Ruby object, ``self``, to pass a reference to itself to the callback method.
 
-However, this only solves 1/2 the problem - passing a Ruby object unchanged to C++. When C++ later invokes the callback, Rice will try to tranlsate it from C++ to Ruby. Of course, that does not make sense for the self reference, so we need to tell Rice not to do it. This is done by using the ``define_callback`` function.
+However, this only solves 1/2 the problem - passing a Ruby object unchanged to C++. When C++ later invokes the callback, Rice will try to translate it from C++ to Ruby. Of course, that does not make sense for the self reference, so we need to tell Rice not to do it. This is done by using the ``define_callback`` function.
 
 .. code-block:: cpp
 
@@ -93,21 +93,27 @@ Simple Callback
 """""""""""""""
 In the simplest case, a callback is only used once in a code base. Thus there is a one-to-one mapping between a callback and its associated Ruby ``Proc``.
 
-This is easy to implement - Rice generates a new C++ class based on the callback's signature using the `NativeCallbackSimple <https://github.com/ruby-rice/rice/blob/master/rice/detail/NativeCallbackSimple.hpp>`_ class template. The generated class has a static member field that stores the ``Proc``. Thus every callback is associated with a single instantiation of the `NativeCallbackSimple` template.
+This is easy to implement - Rice generates a new C++ class based on the callback's signature using the `NativeCallbackSimple <https://github.com/ruby-rice/rice/blob/master/rice/detail/NativeCallbackSimple.hpp>`_ class template. The generated class has a static member field that stores the ``Proc``. Thus every callback is associated with a single instantiation of the ``NativeCallbackSimple`` template.
 
 LibFFI Callback
 """""""""""""""
 However, a library often times use a callback in multiple places. For example:
 
 .. code-block:: cpp
 
-  void setMouseClickCallback(MouseCallback_T onSingleClick, MouseCallback_T onDoubleClick, );
+  void setMouseClickCallback(MouseCallback_T onSingleClick, MouseCallback_T onDoubleClick);
   void setMouseEnterExitCallback(MouseCallback_T onEnterExit);
 
 The above code uses the same callback type 3 different times, thus the one-to-one mapping between callback type and C++ class is broken. Therefore the simple solution of using a static member variable to store the Ruby proc no longer works. Instead, we need to store 3 different ``Procs`` and figure out which one to call when the callback is invoked.
 
-In this case, Rice uses libffi's `closure <https://github.com/libffi/libffi/blob/master/src/closures.c>`_ API. The closure API associates a piece of user data, in this case the ``Proc``, with a callback and then dynamically generates a new function which is what is invoked by the callback function.
+In this case, Rice can use libffi's `closure <https://github.com/libffi/libffi/blob/master/src/closures.c>`_ API. The closure API associates a piece of user data, in this case the ``Proc``, with a callback and then dynamically generates a new function which is what is invoked by the callback function.
+
+Since you are working with Ruby, it is highly likely that LibFFI is already installed since the `Fiddle <https://github.com/ruby/fiddle>`_ gem requires it.
+
+However, you must opt into using libffi. To do this update your ``extconf.rb`` file like this:
+
+.. code-block:: ruby
 
-Since you are working with Ruby, it is highly likely that LibFFI is already installed since the `Fiddle <https://github.com/ruby/fiddle>`_ gem requires it. The default build script will check for LibFFI and if it is found compile it into your bindings.
+  abort "libffi not found" unless have_libffi
 
-If you are using CMake, you will need to add a C++ preprocessor define called ``HAVE_LIBFFI`` and link to libffi.
+If you are using CMake, you will need to add a C++ preprocessor define called ``HAVE_LIBFFI`` and link to libffi.

4.x/_sources/bindings/class_templates.rst.txt

@@ -56,11 +56,11 @@ Instead, write a function to create wrappers. A simplified version looks like th
     inline void Mat__builder(Data_Type_T& klass)
     {
       klass.define_constructor(Constructor<cv::Mat_::Mat_<_Tp>>()).
-        define_constructor(Constructor<cv::Mat_::Mat_<_Tp>, int, int>(),
-          Arg("_rows"), Arg("_cols")).
+        define_constructor(Constructor<cv::Mat_::Mat_<_Tp>, int, int>(), Arg("_rows"), Arg("_cols")).
+
         template define_iterator<cv::Mat_<_Tp>::iterator(cv::Mat_<_Tp>::*)()>(&cv::Mat_<_Tp>::begin, &cv::Mat_<_Tp>::end, "each").
-        template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(),
-          Arg("row"), Arg("col")).
+        template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(), Arg("row"), Arg("col")).
+
         define_method("[]=", [](cv::Mat_<_Tp>& self, int row, int column, _Tp& value)
         {
           self(row, column) = value;
@@ -89,7 +89,7 @@ Second, the ``template`` keyword needs to be used in front of methods:
 
    template define_iterator<cv::Mat_<_Tp>::iterator(cv::Mat_<_Tp>::*)()>(&cv::Mat_<_Tp>::begin, &cv::Mat_<_Tp>::end, "each").
 
-   template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(),
+   template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(), Arg("row"), Arg("col")).
 
 Third, the array constructor cannot be wrapped because it uses a template parameter that is not defined:
 
@@ -102,11 +102,10 @@ Fourth, the ``operator()`` is mapped to two Ruby methods, ``[]`` and ``[]=``.
 
 .. code-block:: cpp
 
-        template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(),
-          Arg("row"), Arg("col")).
+        template define_method<_Tp&(cv::Mat_<_Tp>::*)(int, int)>("[]", &cv::Mat_<_Tp>::operator(), Arg("row"), Arg("col")).
         define_method("[]=", [](cv::Mat_<_Tp>& self, int row, int column, _Tp& value)
         {
           self(row, column) = value;
         });
 
-Once you have created a class builder function it then becomes easy to create new C++ classes from class templates and wrap them in Ruby.
+Once you have created a class builder function it then becomes easy to create new C++ classes from class templates and wrap them in Ruby.

4.x/_sources/bindings/constants.rst.txt

@@ -32,4 +32,4 @@ These constants can be wrapped like this:
 
 Enums as Constants
 ------------------
-Older C++ code sometimes uses anonymous C style enums as a hack for defining class constants. For more information see :ref:anonymous_enums.
+Older C++ code sometimes uses anonymous C style enums as a hack for defining class constants. For more information see :ref:`anonymous_enums`.

4.x/_sources/bindings/constructors.rst.txt

@@ -72,7 +72,7 @@ This defines a constructor that takes no arguments. It can be invoked from Ruby
 
     Mat.new
 
-Under the hood, the ``define_constructor`` call creates a new ``initialize`` method on the Ruby Mat class. The ``initialize`` method is responsible for creating a new C++ ``Mat`` instance and associating it with the wrapper Ruby object. Thus if you override the ``initialize`` method you MUST call super:
+Under the hood, the ``define_constructor`` call creates a new ``initialize`` method on the Ruby ``Mat`` class. The ``initialize`` method is responsible for creating a new C++ ``Mat`` instance and associating it with the wrapper Ruby object. Thus if you override the ``initialize`` method you MUST call ``super``:
 
 .. code-block:: ruby
 
@@ -113,7 +113,7 @@ Most C++ classes include a copy constructor that takes one argument. These are m
 
 .. code-block:: cpp
 
-  define_constructor(Constructor<const Mat&())
+  define_constructor(Constructor<const Mat&>())
 
 Rice maps copy constructors to Ruby's ``clone`` and ``dup`` methods:
 
@@ -123,7 +123,7 @@ Rice maps copy constructors to Ruby's ``clone`` and ``dup`` methods:
     mat2 = mat1.dup
     mat3 = mat1.clone
 
-Under the hood, the ``define_constructor`` call creates a new ``initialize_copy`` method on the Ruby Mat class. The ``initialize_copy`` method is responsible for calling the C++ copy constructor and assigning the new C++ instance to the wrapper Ruby object. Thus if you override the ``initialize_copy`` method you MUST call super:
+Under the hood, the ``define_constructor`` call creates a new ``initialize_copy`` method on the Ruby Mat class. The ``initialize_copy`` method is responsible for calling the C++ copy constructor and assigning the new C++ instance to the wrapper Ruby object. Thus if you override the ``initialize_copy`` method you MUST call ``super``:
 
 .. code-block:: ruby
 

4.x/_sources/bindings/enums.rst.txt

@@ -26,7 +26,7 @@ To expose an enum to Ruby, use ``define_enum`` like this:
     .define_value("BLACK", BLACK)
     .define_value("GREEN", GREEN);
 
-``define_enum<Color>("Color")`` creates a new Ruby class called ``Color``. Each call to ``define_value``  defines a new instance of Color that is stored as a constant on the Color class. Thus from the Ruby side of things, the mapping looks like:
+``define_enum<Color>("Color")`` creates a new Ruby class called ``Color``. Each call to ``define_value`` defines a new instance of Color that is stored as a constant on the Color class. Thus from the Ruby side of things, the mapping looks like:
 
 .. code-block:: ruby
 
@@ -88,7 +88,7 @@ From the Ruby side, this creates:
   class MyClass
     SOME_CONSTANT = 42
     HACKED_CLASS_CONSTANT_1 = MyClass::HACKED_CLASS_CONSTANT_1
-    HACKED_CLASS_CONSTANT_2", MyClass::HACKED_CLASS_CONSTANT_2
+    HACKED_CLASS_CONSTANT_2 = MyClass::HACKED_CLASS_CONSTANT_2
 
     class Season
       Spring = Color.new(Season::Spring)
@@ -102,29 +102,35 @@ Ruby API
 --------
 Generated enum classes have the following Ruby API.
 
-Enum.from_int
+.. code-block::
 
-Enum#<=>
-Enum#eql?
-Enum#hash
-Enum#each
-Enum#inspect
-Enum#to_int
-Enum#to_s
+  Enum.from_int
 
-Enum#&
-Enum#|
-Enum#^
-Enum#~
-Enum#<<
-Enum#>>
+  Enum#<=>
+  Enum#eql?
+  Enum#hash
+  Enum#each
+  Enum#inspect
+  Enum#to_int
+  Enum#to_s
+
+  Enum#&
+  Enum#|
+  Enum#^
+  Enum#~
+  Enum#<<
+  Enum#>>
 
 In addition, they have the following aliases:
 
-Enum#===  Enum#eql?
-Enum#to_i Enum#to_int
+.. code-block::
+
+  Enum#===
+  Enum#eql?
+  Enum#to_i
+  Enum#to_int
 
 And mixin the following modules:
 
-* Comparable
-* Enumerable
+* `Comparable <https://ruby-doc.org/core-3.0.3/Comparable.html>`_
+* `Enumerable <https://ruby-doc.org/core-3.0.3/Enumerable.html>`_

4.x/_sources/bindings/exceptions.rst.txt

@@ -128,7 +128,7 @@ If your C++ code calls a Ruby API which then in turns calls C++ code, you will n
         std::map<T, U>* result = (std::map<T, U>*)(user_data);
 
         // This method is being called from Ruby so we cannot let any C++
-        // exceptions propogate back to Ruby
+        // exceptions propagate back to Ruby
         return cpp_protect([&]
         {
           result->operator[](From_Ruby<T>().convert(key)) = From_Ruby<U>().convert(value);

4.x/_sources/bindings/inheritance.rst.txt

@@ -38,8 +38,8 @@ Directors
 Inheritance becomes much more complex if you want to create Ruby classes that inherit from wrapped C++ classes. This introduces several problems:
 
 * Ruby classes should be able to override C++ virtual methods
-* Overriden virtual methods should be able to call ``super`` and invoke the overriden C++ method
-* C++ code calling the virtual methods should invoke the overriden version in Ruby
+* Overridden virtual methods should be able to call ``super`` and invoke the overridden C++ method
+* C++ code calling the virtual methods should invoke the overridden version in Ruby
 
 Rice supports these use cases through the use of ``Director`` classes. ``Directors`` are proxies that can correctly dispatch method invocations up or down a Class hierarchy.
 
@@ -126,7 +126,7 @@ Next we implement ``doWork``. The director class overrides its by forwarding the
         return VirtualBase::doWork();
       }
 
-It director also implements ``default_doWork`` which enables Ruby to call the overriden virtual C++ method. The ``default_`` prefix is a naming convention to help keep straight which methods perform which functions.
+It director also implements ``default_doWork`` which enables Ruby to call the overridden virtual C++ method. The ``default_`` prefix is a naming convention to help keep straight which methods perform which functions.
 
 If Ruby should never call the C++ method then the ``default_`` implementation should call ``raisePureVirtual()``:
 

4.x/_sources/bindings/iterators.rst.txt

@@ -3,7 +3,7 @@
 Iterators
 =========
 
-C++ iterators are used to traverse through elements stored in a container. C++ iterators are external iterators that work in pairs, with a beginning iterator and an ending iterator. For example, std::vector has begin/end, cbegin/cend, rbegin/rend, etc.
+C++ iterators are used to traverse through elements stored in a container. C++ iterators are external iterators that work in pairs, with a beginning iterator and an ending iterator. For example, ``std::vector`` has begin/end, cbegin/cend, rbegin/rend, etc.
 
 Enumerable Support (Internal Iterators)
 ---------------------------------------
@@ -32,7 +32,7 @@ For example let's create a simple wrapper around std::vector (for full support p
 
 Notice that we have to tell Rice which overloaded version of ``push_back``, ``begin`` and ``end`` we want to expose For more information please see :ref:`overloaded_methods`.
 
-Once the interator is defined you can write standard Ruby code such as:
+Once the iterator is defined you can write standard Ruby code such as:
 
 .. code-block:: ruby
 
@@ -47,7 +47,7 @@ Once the interator is defined you can write standard Ruby code such as:
 
 Where result will be ``[2, 4, 6]``.
 
-Let's say you also want to expose std::vector's reverse iterator to Ruby using the method name ``reach``. This is done by adding a third parameter to the ``define_iterator`` call, in this case it is set to reach":
+Let's say you also want to expose std::vector's reverse iterator to Ruby using the method name ``reach``. This is done by adding a third parameter to the ``define_iterator`` call, in this case it is set to ``"reach"``:
 
 .. code-block:: cpp
 
@@ -80,7 +80,7 @@ Enumerator Support (External Iterators)
 ---------------------------------------
 Ruby supports external iterators via the `Enumerator <https://ruby-doc.org/3.2.2/Enumerator.html>`_ class. The ``define_iterator`` method automatically adds support for Enumerators.
 
-Enumerators can be created by calling an iterator method without a block, in the same way you can call Array#each or other methods without a block. For example:
+Enumerators can be created by calling an iterator method without a block, in the same way you can call ``Array#each`` or other methods without a block. For example:
 
 .. code-block:: ruby
 

4.x/_sources/bindings/memory_management.rst.txt

@@ -198,7 +198,7 @@ Obviously this code could be rewritten to make sure the database object remains
   define_class<Database>("Database")
     .define_method("get_column", &Database::getColumn, Return().keepAlive())
 
-Note that Return().keepAlive() will work with external types only. An attempt to use it with builtin type will result in runtime exception.
+Note that ``Return().keepAlive()`` will work with external types only. An attempt to use it with builtin type will result in runtime exception.
 
 C++ Referencing Ruby Objects
 ----------------------------

4.x/_sources/bindings/methods.rst.txt

@@ -112,12 +112,22 @@ For example, reusing the example above:
 
 The ``hello`` function can be called from Ruby like this:
 
-.. code-block:: cpp
+.. code-block:: ruby
 
   test = Test.new
   test.hello(first: "Hello", second: "World")
   test.hello(first: "Hello") # This is ok because the second parameter has a default value
 
+And it can also be called in the traditional manner like this:
+
+.. code-block:: ruby
+
+  test = Test.new
+  test.hello("Hello", "World")
+  test.hello("Hello")
+
+The ability to call the function in two different ways (position and keyword) could cause problems in the future. Imagine that you decide to move the code to Ruby - you will need to chose one of the two forms. That could result in breaking someone else's code. This risk seems low though, so for the moment Rice only supports defining arguments using the ``Arg`` class. In the future Rice may introduce a ``KeyArg`` class to avoid this issue.
+
 .. _return_self:
 
 Return Self
@@ -136,7 +146,7 @@ The above code works because the ``<<`` method returns the Array ``a``. You can
 .. code-block:: cpp
 
   define_vector<std::vector<int32_t>>().
-  define_method("<<", [](std::vector<int32_t>& self, int32_t value) -> std::vector<int32_t>&  // <----- DONT MISS THIS
+  define_method("<<", [](std::vector<int32_t>& self, int32_t value) -> std::vector<int32_t>&  // <----- DON'T MISS THIS
   {
     self.push_back(value);
     return self;  // <------  Allows chaining on calls
@@ -155,8 +165,7 @@ Ruby classes are expected to define a ``to_s`` method that provides a string rep
       define_method("to_s", [](Test& self)
       {
          return "<Test>";
-      })
-    );
+      });
 
 We define the ``to_s`` method to take a single parameter, self, which is an C++ instance of ``Test``. Note that ``self`` is passed by reference - we do not want to create a copy of the Test object!