locates occurences of a (wildcarded) vector in a matrix or hypermatrix
ind = vectorfind(haystack, needle) ind = vectorfind(haystack, needle, dimAlong) ind = vectorfind(haystack, needle, dimAlong, ,indType) [ind, matching] = vectorfind(haystack, needle, dimAlong, joker) [ind, matching] = vectorfind(haystack, needle, dimAlong, joker, indType)
A matrix or hypermatrix of any type, possibly sparse encoded: The array in which the vector will be searched.
The vector to be searched in the haystack
, of the same type.
If the haystack
is sparse-encoded, the needle
may be dense. In addition, if the haystack
is boolean and a
joker
is used, the needle
must be numerical
instead of boolean. In this case, any of its non-zero components is
%T
![]() |
|
Direction inside the haystack
array along which the
needle
vector is searched. Possible values are
"r"
or 1
(along rows),
"c"
or 2
(along columns),
or for an hypermatrix, any integer such that
2 < dimAlong <= ndims(haystack)
representing the index of the scanned dimension.
By default, "r"
is used.
![]() | dimAlong is mandatory when a joker
or indType is specified. |
Single element of needle
's data type.
The needle
components equal to the joker
are ignored (they match/accept any values from the haystack
).
When the haystack is boolean, the joker
must be a
non-zero number.
To skip the joker
, specify
..dimAlong, ,indType
with no joker value.
Single case-insensitive word among ""
(empty text = default), "headIJK"
, and "headN"
:
Specifies the format or returned indices. See here-below the description of
ind
.
When the needle
is longer than the
haystack
size along the chosen dimension
dimAlong
, ind=[]
is returned.
When the needle
's length matches the
haystack
size along the chosen dimension,
By default
(indType==""
):
ind
is a row vector containing the indices
of matching rows or columns of the haystack. In case of hypermatrix,
returned indices of matching ranges are linearized accross all
dimensions but the dimAlong
one (see examples).
indType="headN":
ind
is the row vector of
linear indices in
the haystack
of the heading component of its
matching rows, columns, or higher ranges.
indType="headIJK":
ind
is a matrix: Each row returns the
[i j ..]
indices in the haystack
of the heading
component of its matching ranges (rows, columns, or higher ranges).
ind
has as many rows as there are matching
ranges in the haystack
.
Otherwise (short needle): By default,
ind
is the row vector of linear indices of the
components of the haystack
where matching ranges
start. Using the indType="headN"
option does
nothing more. Using indType="headIJK"
returns
ind
as a matrix of [i j k ..]
indices, as described here-above.
![]() | Returned indices are sorted in increasing order. |
When a joker is used, this matching
optional output
is a matrix of haystack's data type returning the actual matching ranges:
The matching range number #i is returned in the row matching(i,:)
.
![]() | When the haystack is sparse-encoded,
the matching matrix is sparse as well. |
vectorfind()
looks for a given series of values (needle) in a
haystack array, along a given right direction/dimension: width (rows), height (columns),
thickness (like RGB pixels), etc. The needle may be as long or shorter than the size
of the probed side of the haystack.
A special value so-called joker may be specified. Then this value works as a wildcard where it occurs in the needle vector. Since this value is no longer selective -- ANY value from the haystack matches at its position --, it can't simultaneously be used in the needle as a selective one. In practical, any value not present in the haystack makes necessarily a good joker. However, this condition is not mandatory.
Consequence: When the haystack is boolean, the joker -- and so the needle vector as well -- must be numerical. Indeed, it would be otherwise impossible to choose a joker value out of the {%T, %F} limited set of values.
When such a wildcard is used, actual values in matching ranges are not fixed. It is
then possible to retrieve them thanks to the
matching
optional output. Otherwise, matching
is empty (it is a trivial repetition of the needle vector).
Using vectorfind()
with an hypermatrix haystack deserves some
special attention:
About the direction value dimAlong
:
For instance, we
can then probe the haystack array in "thickness", i.e.
accross its successive layers
haystack(:,:,#,..)
. To do so, we will here specify
dimAlong = 3
.
Like for matrices, this kind of high-dimension array can be
scanned along its rows or columns.
The corresponding dimAlong
values have there some exceptions:
dimAlong = "r"
value should be equivalent to
dimAlong = 2
instead of 1!dimAlong = "c"
should be equivalent to
dimAlong = 1
instead of 2!In order to not quit the common convention "r"<=>1
and "c"<=>2
used everywhere in Scilab,
vectorfind()
keeps and copes with it. But one should keep in
mind the underlying switch, to have a clear understanding of the returned
default indices when "r",1
or "c",2
are used.
About returned indices of matching rows, columns, "pixels"... when the needle
is as long as the haystack side size and no indType
option
is used:
Indices of matching ranges are then linear indices of components of the following subspaces:
dimAlong = "r" = 1
:
in haystack(:,1,:,:..)
dimAlong = "c" = 2
:
in haystack(1,:,:,:..)
dimAlong = 3
:
in haystack(:,:,1,:..)
dimAlong = 4
:
in haystack(:,:,:,1,:..)
.indType = "headN" | "headIJK
will then return
more workable indices refering to the whole haystack
array.In a matrix of numbers:
In a boolean matrix:
In a tiny 8-color RGB image (3D hypermatrix of uint8 integers):
// Generating the array of color brightnesses: m = [1 1 1 1 1 0 1 0 0 0 1 0 1 0 0 1 1 0 0 0 0 1 0 1 0 1 1 1 1 1 1 1 0 1 0 1 1 0 0 1 1 0 0 1 0]; m = uint8(matrix(m,3,5,3)*255) // m = //(:,:,1) // RED layer // 255 255 255 255 255 // 255 255 0 0 0 // 255 255 0 255 0 //(:,:,2) // GREEN layer // 0 255 0 0 0 // 0 255 0 255 0 // 255 255 0 0 255 //(:,:,3) // BLUE layer // 255 0 255 0 0 // 255 255 255 255 255 // 255 0 0 255 0 // Locates red pixels: vectorfind(m, [255 0 0], 3) // => [10 13] vectorfind(m, [255 0 0], 3,,"headIJK") // => [1 4 1 ; 1 5 1] // Pixels with Green & Blue ON, whatever is their Red channel: // We may use a decimal-encoded needle (not a uint8). // Then, %nan is a possible joker, that can't be in the uint8 image: vectorfind(m, [%nan 255 255], 3, %nan,"headIJK") // => [3 1 1; 2 2 1; 2 4 1] // Columns of 255: vectorfind(m, [255 255 255], "c") // => [1 2 7 11] | ![]() | ![]() |
In a 4D hypermatrix of text:
m = [ "U" "C" "G" "A" "A" "A" "U" "U" "A" "G" "A" "G" "A" "A" "A" "A" "C" "C" "U" "U" "C" "G" "G" "G" "A" "G" "A" "C" "G" "C" "C" "C" "G" "C" "A" "G" "C" "U" "G" "G" "G" "A" "A" "G" "C" "C" "C" "C" "C" "G" "G" "A" "A" "G" "U" "C" "A" "U" "G" "C" ]; m = matrix(m, 3, 5, 2, 2); // (:,:,1,1) // !U C A G A ! // !A C G G G ! // !A C U A G ! //(:,:,2,1) // !A G C A C ! // !A A G A A ! // !C A G C G ! //(:,:,1,2) // !U A U C G ! // !U U C A C ! // !C U G C A ! //(:,:,2,2) // !G C G G G ! // !G U A G C ! // !C A C G C ! vectorfind(m, ["A" "A" "C"], "c") // => [6 9] vectorfind(m, ["" "G" "G"], "c", "") // => [5 8 19] // Joker [n, ma] = vectorfind(m, ["" "G" "G"], "c", "", "headN") // => n=[13 22 55], ma=[A G G; C G G; G G G] vectorfind(m, ["" "C" "C"], "c", "", "headIJK") // => [1 2 1 1 ; 1 5 2 2] // Short needle vectorfind(m, ["C" "C"], "c",,"headIJK") // => [1 2 1 1; 2 2 1 1; 2 5 2 2] // Short needle with joker vectorfind(m, ["A" "" "A"],"r","","headIJK") // => [1 3 1 1 ; 2 2 2 1] | ![]() | ![]() |
Version | Description |
6.1 |
|