[Scilab-users] vectorfind() upgrade [SEP]

[Samuel Gougeon]

Hi,

Looking for occurrences of a vector in an array is a general task that 
can be useful in many situations.

vectorfind() currently does it, but with some cumbersome limitations.
A work was started in last February to extend vectorfind() capabilities.
It was announced @ 
http://mailinglists.scilab.org/Scilab-users-Search-for-a-subvector-in-a-vector-tp4035450p4035452.html

An extended version is now available for tests and comments, at the 
unchanged URL:
https://codereview.scilab.org/#/c/19055/
A copy of its documentation page in PDF is attached.
This is a Scilab Enhancement Proposal (SEP).

Its history section summarizes new proposed features.
They are reminded and illustrated herebelow.

All comments are welcome.
Best regards
Samuel

=======================

*New features proposed*:

  * |vectorfind(H,[])| returns an error.
    => Returning |[]| is proposed instead.

  * When the needle is longer than the haystack side size, an error is
    yielded.
    => Returning |[]| is proposed instead

  * vectorfind() can't presently be used with a needle shorter than the
    haystack size.
    This was the limitation pointed by Christophe in February.
    => Supporting any *short needle* is proposed.
    example:
      m  = [
        1  0  0  1
        1  0  0  1
        0  0  1  0 ];
    vectorfind(m, [0 0], "r")  // => [3 4 5] instead of an error
    vectorfind(m, [1 1], "c")  // => [1 10] instead of an error

  * When the haystack array has some *%nan* values, these ones are
    presently never matching.
    => Considering %nan values as regular ones is proposed.
    Example:
      m  = [
        1 %nan 0   1
        1  0   0   1
        0  0   1  %nan ];
    vectorfind(m, [1 %nan], "r")  // => [1 9] instead of []

  * It is presently not possible to use *wildcards* in the vector to
    search. For instance, if in the previous matrix m we search all
    columns starting with 0 and ending with 1, there is no way to
    specify a [0 * * 1]-like vector as needle.
      o A new *joker* option is proposed in input. It declares a value
        that can be used in the vector and has the status of a wildcard:
        It is matched by any value of the haystack array.
      o In addition, a new *matching* output argument is proposed. It
        allows to retrieve actual matching ranges. Example with the m
        matrix hereabove:
        --> [ind, matching] = vectorfind(m, [1 *-1*0], "r", *-1*)
        ind  =
            1.   2.
        matching  =
            1.   Nan   0.
            1.   0.    0.

  * It is presently not possible to search the vector inside an
    *hypermatrix*. Yet, N-Dimensional data are not rare -- like any RGB
    image --, and hypermatrices are now natively encoded in Scilab 6.
    => Supporting hypermatrices as haystack is proposed. The attached
    page shows 2 examples, like selecting all pixels of a RGB image (3D
    array) having some given [r g b] values.
    Another short example:
    --> m = grand(2,4,3,"uin",0,2)
      m  =
    (:,:,1)
        2.   1.   2.   1.
        1.   1.   0.   0.
    (:,:,2)
        0.   1.   0.   2.
        2.   0.   1.   0.
    (:,:,3)
        0.   1.   2.   2.
        0.   0.   1.   2.

    --> vectorfind(m, [2 0], "c")
      ans  =
        3.   8.

    --> [ind, matching] = vectorfind(m, [0 -1 -1 2], "r", -1)
      matching  =
        0.   1.   0.   2.
        0.   1.   2.   2.
        0.   0.   1.   2.
      ind  =
        3.   5.   6.

  * Extending vectorfind() to hypermatrices requires to allow probing
    extra directions beyond rows and columns. Hence, specifying the
    *probing direction as an integer 1 , 2, 3*,.. is proposed. However,
    as indicated in the page (Description section), the equivalences 1
    <=> "r" and 2 <=> "c" are questionable. The present proposal is
    implemented  with them.
    Example with the m hypermatrix hereabove:
    --> vectorfind(m, [2 0], 3)
      ans  =
        1.   5.   10.

  * Interpreting and using "matrix-like" default indices returned by
    vectorfind() when the haystack is an hypermatrix may be hard and not
    handy. A new option *|indType|* is proposed to allow returning
    explicit or truly linear indices. It is proposed as well when
    searching in a simple matrix.
    Back to the last example hereabove, we will get, instead of [1 5 10]:
    --> vectorfind(m, [2 0], 3,,"headIJK")
      ans  =
        1.   1.   1.
        1.   3.   1.
        2.   1.   2.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/users/attachments/20170816/007d02c6/attachment.htm>