bugGNU Octave - Bugs: bug #46265, Docs of lookup insufficient

 
 

bug #46265: Docs of lookup insufficient

Submitter:  Francesco Potortì <pot>
Submitted:  Wed 21 Oct 2015 11:43:25 AM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  5 - Normal Item Group:  Feature Request
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * 4.0.0 Operating System:  * GNU/Linux
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 03 Sep 2017 12:55:00 AM UTC, comment #6: 

I mad some improvements to the documentation for lookup including adding @strong{} around the word "sorted" before table as well as a Note at the bottom of the docstring that the table needs to be sorted for the function to behave correctly.  See cset http://hg.savannah.gnu.org/hgweb/octave/rev/21d2114476a4.

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Fri 23 Oct 2015 07:41:16 AM UTC, comment #5: 

Sorry, my comment #4 is incorrect: my described behaviour will only happen when the code takes the path that leads to the case of a complexity of O(M+N) (for sorted Y). For general Y of course you only get the logarithmic complexity with an efficient binary lookup that will lead to results not as simple as I supposed.

But: when you want to error out when the table is not ordered, you have to replace your complexity by O(min(max(N,M*log(N)),M+N)), which will be vastly less efficient for the not-so-exotic case of large sorted TABLE and small Y.

Anonymous
Fri 23 Oct 2015 07:18:21 AM UTC, comment #4: 

Why not define the behaviour and modify the semantics of lookup to return the index of the first table entry larger than the respective entries in y? This would then essentially be a find(table>y,1) for vector-valued y, and probably there are even use-cases for this. I had not looked into the code, but very probably the at-the-moment undefined behaviour of lookup is just what I descried above. Then the new semantics would be an extension of the old ones: if you pass in a sorted vector, which is the only allowed case now, the results agree. Error checking should then be done at the level of the interpolation routines.

Of course, the present lookup claims to work also for monotonically decreasing tables. Therefore the definition of lookup will get a bit more awkward than what I wrote above.

Anonymous
Thu 22 Oct 2015 07:38:30 PM UTC, comment #3: 

I don't like this "undefined" business. That's a concept in C++, not in Octave. Could lookup just be modified to error out if the table isn't ordered?

Jordi Gutiérrez Hermoso <jordigh>
Group Member
Wed 21 Oct 2015 04:20:20 PM UTC, comment #2: 

Right, sorry for the inaccuracy.

I would add one more sentence, to put somwhere: «If TABLE is not sorted, the results of lookup are undefined».

Francesco Potortì <pot>
Wed 21 Oct 2015 02:02:04 PM UTC, comment #1: 

The help string starts with the summary sentence: "Lookup values in a sorted table". So right at the start it says the first argument is expected to be sorted.

Not rejecting this report, just showing that the information is there, maybe not as clear as possible.

Mike Miller <mtmiller>
Group Member
Wed 21 Oct 2015 11:43:25 AM UTC, original submission:  

The docs start by saying «This function is usually used as a prelude to interpolation.»  This is largely insufficient, because it does not say that TABLE should be sorted and because it does not say first things first.

The above text should be substituted by:

«Look in TABLE for each element of Y and return an index into TABLE.  TABLE is a sorted numeric array or a sorted cell array of strings.  Correspondingly, Y is a number or a string.  Y can also be a numeric array or a cell array of strings: in this case lookup returns an array of indexes into TABLE. This function is usually used as a prelude to interpolation.»

Consequently, the next paragraph should end with the additional text «Lexicographical comparison is used in the case of strings.»

Last, the paragraph «TABLE and Y can also be cell arrays of strings (or Y can be a single string).  In this case, string lookup is performed using lexicographical comparison.» should be removed.

Francesco Potortì <pot>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by jordigh (Posted a comment)
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by pot (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-09-03 rik5 StatusNone Fixed
        Open/ClosedOpen Closed
    2015-10-21 mtmiller Severity3 - Normal 1 - Wish

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code