function s=cosmo_structjoin(varargin)
% joins values in structs or key-value pairs
%
% s=cosmo_structjoin(arg1, arg2, ...)
%
% Inputs:
% arg{X} Any of the following:
% - if a cell, then it should contain structs or key-value
% pairs
% - if a struct, then value=arg{X}.(key) for each key in
% fieldnames(arg{X}) is stored as s.(key)=value.
% In this case, it is required that the struct is of size
% 1x1.
% - if a string, then it is stored as s.(arg{X})=arg{X+1}
%
% Returns:
% s Struct with fieldnames and their associated values
% as key-value pairs. Values in the input are stored from
% left-to-right.
%
% Example:
% x=cosmo_structjoin('a',{1;2},'b',{3,4});
% cosmo_disp(x);
% %|| .a
% %|| { [ 1 ]
% %|| [ 2 ] }
% %|| .b
% %|| { [ 3 ] [ 4 ] }
% y=cosmo_structjoin(x,'a',66,'x',x,{'c','hello'});
% cosmo_disp(y);
% %|| .a
% %|| [ 66 ]
% %|| .b
% %|| { [ 3 ] [ 4 ] }
% %|| .x
% %|| .a
% %|| { [ 1 ]
% %|| [ 2 ] }
% %|| .b
% %|| { [ 3 ] [ 4 ] }
% %|| .c
% %|| 'hello'
%
% % simulate a function definition function out=f(varargin)
% % to illustrate overriding default values
% varargin={'radius',2,'nsamples',12};
% defaults=struct();
% defaults.radius=10;
% defaults.nfeatures=2;
% params=cosmo_structjoin(defaults,varargin);
% cosmo_disp(params);
% %|| .radius
% %|| [ 2 ]
% %|| .nfeatures
% %|| [ 2 ]
% %|| .nsamples
% %|| [ 12 ]
%
% % illustrate overriding values in 'sub-structs' (structs as values in
% % other structs)
% v=struct();
% v.a.foo={1,2};
% v.b=3;
% w=struct();
% w.a.bar=[2,3];
% w.c=4;
% j=cosmo_structjoin(v,w);
% cosmo_disp(j)
% %|| .a
% %|| .foo
% %|| { [ 1 ] [ 2 ] }
% %|| .bar
% %|| [ 2 3 ]
% %|| .b
% %|| [ 3 ]
% %|| .c
% %|| [ 4 ]
%
%
% Notes:
% - this function can be used to parse input arguments (including
% varargin in a "'key1',value1,'key2',value2,..." fashion)
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
