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

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

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 

<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
|-
|<pre>
retval(3) = q;
retval(2) = B;
retval(1) = A;
retval(0) = r;

return retval;
</pre>
|<pre>
return ovl (r, A, B, q);
</pre>
|}

==== Example 2 : ovl() extending over multiple lines ====
{|
!Before !! After
|-
|<pre>
if (nargout == 3)
  {
    retval(2) = eye.index (perm, idx_vector::colon);
    retval(1) = U;
    retval(0) = L.index (perm, idx_vector::colon) + eye;
  }
else
  {
    retval(1) = U;
    retval(0) = L + eye.index (perm, idx_vector::colon);
  }
</pre>
|<pre>
if (nargout == 3)
  {
    retval = ovl (L.index (perm, idx_vector::colon) + eye,
                  U,
                  eye.index (perm, idx_vector::colon);
  }
else
  {
    retval = ovl (L + eye.index (perm, idx_vector::colon), U);
  }
</pre>
|}