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

Jump to navigation Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.

Latest revision Your text
Line 1: Line 1:
== Introduction ==
== Introduction ==


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.
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.


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
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.


<pre>
==== Example 1 : Simple Conditional (colloc() from colloc.cc) ====
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
!Before !! After
Line 46: Line 22:
|}
|}


==== Example 2 : ovl() extending over multiple lines ====
==== Example 2 : Multiple Conditional (fopen() from file-io.cc) ====
{|
{|
!Before !! After
!Before !! After
Please note that all contributions to Octave may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Octave:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)
Retrieved from "https://wiki.octave.org/Refactor_C%2B%2B_code_to_use_ovl()_when_returning_multiple_values"