function p=cosmo_cartprod(xs, convert_to_numeric)
% returns the cartesian product with all combinations of the input
%
% p=cosmo_cartprod(xs[, convert_to_numeric])
%
% Inputs:
% xs Px1 cell array with values for which the product
% is to be returned. Each element xs{k} should be
% - a cell with Qk values
% - a numeric array [xk_1,...,xk_Qk], which is
% interpreted as the cell {xk_1,...,xk_Qk}.
% - or a string s, which is interpreted as {s}.
% Alternatively xs can be a struct with P fieldnames
% where each value is a cell with Qk values.
%
% convert_to_numeric Optional; if true (default), then when the output
% contains numeric values only a numerical matrix is
% returned; otherwise a cell is returned.
% Output:
% p QxP cartesian product of xs (where Q=Q1*...*Qk)
% containing all combinations of values in xs.
% - If xs is a cell, then p is represented by either
% a matrix (if all values in xs are numeric and
% convert_to_numeric==true) or a cell (in all
% other cases).
% - If xs is a struct, then p is a Qx1 cell. Each
% element in p is a struct with the same
% fieldnames as xs.
%
% Examples:
% cosmo_cartprod({{1,2},{'a','b','c'}})'
% %|| {1,2,1,2,1,2;
% %|| 'a','a' ,'b','b','c','c'}
%
% cosmo_cartprod({[1,2],[5,6,7]})'
% %|| [1,2,1,2,1,2;
% %|| 5,5,6,6,7,7]
%
% cosmo_cartprod(repmat({1:2},1,4))'
% %|| [1 2 1 2 1 2 1 2 1 2 1 2 1 2 1 2;
% %|| 1 1 2 2 1 1 2 2 1 1 2 2 1 1 2 2;
% %|| 1 1 1 1 2 2 2 2 1 1 1 1 2 2 2 2;
% %|| 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2]
%
% s=struct();
% s.roi={'v1','loc'};
% s.hemi={'L','R'};
% s.subj=[1 3 9];
% s.ana='vis';
% s.beta=4;
% p=cosmo_cartprod(s)';
% cosmo_disp(p);
% %|| { .roi .roi .roi ... .roi .roi .roi
% %|| 'v1' 'loc' 'v1' 'loc' 'v1' 'loc'
% %|| .hemi .hemi .hemi .hemi .hemi .hemi
% %|| 'L' 'L' 'R' 'L' 'R' 'R'
% %|| .subj .subj .subj .subj .subj .subj
% %|| [ 1 ] [ 1 ] [ 1 ] [ 9 ] [ 9 ] [ 9 ]
% %|| .ana .ana .ana .ana .ana .ana
% %|| 'vis' 'vis' 'vis' 'vis' 'vis' 'vis'
% %|| .beta .beta .beta .beta .beta .beta
% %|| [ 4 ] [ 4 ] [ 4 ] [ 4 ] [ 4 ] [ 4 ] }@1x12
% %
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
