function msk=cosmo_match(haystack, needle, varargin)
% returns a mask indicating matching occurences in two arrays or cells
% relative to the second array
%
% msk=cosmo_match(haystack1, needle1[, needle2, haystack2, ...])
%
% Inputs:
% haystack* numeric vector, or cell with strings. A string is
% also allowed and interpreted as the name of a feature
% dimension ('i','j' or 'k' in fmri datasets; 'chan',
% 'time', or 'freq' in MEEG datasets), and its
% respective values (from ds.a.fdim.values{dim}, where
% dim is the dimension corresponding to haystack) as
% indexed by ds.fa.(haystack) are used as haystack.
% needle* numeric vector, or cell with strings. A string is
% also allowed and interpreted as {needle}.
%
% Output:
% msk boolean array of the same size as haystack, with
% true where the value in haystack is equal to at least
% one value in needle. If multiple needle/haystack
% pairs are provided, then the haystack inputs should
% have the same number of elements, and msk contains
% the intersection of the individual masks.
%
% Examples
% % simple character comparison
% cosmo_match({'a','b','c'},{'b','c','d','e','b'})
% %|| [false true true]
% % swap the order of inputs
% cosmo_match({'b','c','d','e','b'},{'a','b','c'})
% %|| [true true false false true]
%
% % in an fMRI dataset, get mask for features with with first spatial
% % dimension indices 5 or 7.
% msk=cosmo_match(ds.fa.i,[5 7]);
%
% % get mask for chunk values 1 and 4
% msk=cosmo_match(ds.sa.chunks,[1 4]);
%
% % get mask for chunk values 1 and 4, and target values 1, 3 or 6.
% msk=cosmo_match(ds.sa.chunks, [1 4], ds.sa.targets, [1 3 6]);
%
% % get feature mask for the fourth channel in an MEEG dataset
% msk=cosmo_match(ds.fa.chan,4)
%
% Notes:
% - the output of this function can be used with cosmo_slice
% to select features or samples of interest
% - to select feature dimension values in an fmri or meeg dataset
% (e.g., channel selection), see cosmo_dim_match
%
% See also: cosmo_slice, cosmo_stack, cosmo_dim_match
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
