Refactor C++ code to use ovl() when returning multiple values: Difference between revisions

Refactor C++ code to use ovl() when returning multiple values (edit)

Revision as of 16:27, 10 December 2015

744 bytes added , 10 December 2015

m

→‎Introduction

Rik

1,072

edits

@@ Line 1: / Line 1: @@
 == Introduction ==
-Some functions In Octave C++ error handling mechanism in core Octave has been changed to use exceptions.  Previously, calling print_usage() or error() in C++ would always return execution to the calling function.  This made it necessary to explicitly use the return keyword to exit a function, or arrange for an if/else tree in the original function so that normal function execution would not continue in the case of an error.  With exceptions, the C++ code may now be written in a manner that closely resembles Octave's own m-file language.
+Some Octave functions return more than one value.  For example, the LU factorization can return L and U, but also P, Q, and R.  In C++ these functions return an octave_value_list object which is a row vector of return values.  The first element in the vector (element 0) contains the leftmost return argument.  For return arguments L,U,P the indices would be 0,1,2.
-The principal work for this sprint topic is to convert the C++ code to the new syntax.  In general, this means moving the input validation to the start of the function and logically negating the conditional used to test for an error condition.  For a single condition, the condition itself should be reversed rather than just adding the negation operator '!' to the start of the conditional.  For a test with multiple conditions, use DeMorgan's Law ([https://en.wikipedia.org/wiki/Demorgans_law Demorgan's Law]).  In brief, you will need to negate each individual conditional and then change all && to || or vice versa.
+However, unless the octave_value_list has been pre-declared to the correct size, growing the row vector by indexing into a non-existent position forces the array to grow.  Thus, the straightforward and very clear coding strategy of
-==== Example 1 : Simple Conditional (colloc() from colloc.cc) ====
+<pre>
+retval(0) = L;
+retval(1) = U;
+retval(2) = P;
+</pre>
+turns out to be an inefficient implementation.  For this reason, current Octave code always writes this in reverse as
+<pre>
+retval(2) = P;
+retval(1) = U;
+retval(0) = L;
+</pre>
+The first indexing operation resizes the row vector and is done only once, but the disadvantage is that this code is more difficult to match with the function's behavior.
+As an alternative, there is the ovl() function where the name stands for Octave Value List.  This function grows the vector just once and allows the arguments to be presented in their natural order.  In this case, the example code could be written as
+<pre>
+retval = ovl (L, U, P);
+</pre>
+The principal work for this sprint topic is to convert the C++ code to use the ovl() function where possible.  In general, this means collapsing multiple assignment statements to a single assignment.  Keeping in mind that line length should be limited to 80 characters, this may mean appropriately breaking the line and indenting the following lines.  In some cases, the declaration of "octave_value_list retval" may no longer be necessary and a direct "return ovl (...)" will be possible.  In that case, the code can be further simplified by eliminating the retval variable entirely from the function.
+==== Example 1 : Remove List and retval declaration (colloc() from colloc.cc) ====
 {|
 !Before !! After
@@ Line 22: / Line 46: @@
 |}
-==== Example 2 : Multiple Conditional (fopen() from file-io.cc) ====
+==== Example 2 : ovl() extending over multiple lines ====
 {|
 !Before !! After