function [split, nsplit]=cosmo_strsplit(string, delim, varargin)
% splits a string based on another delimeter string
%
% [split,n]=cosmo_strsplit(string[,delim,][pos1, delim2, pos2, delim2,...])
%
% Inputs:
% string input to be split
% delim delimiter string. delim can contain backslash-escaped
% characters that are interpreted by sprintf; for
% example '\t', '\n' and '\\' represent a tab, newline
% and backslash character, respectively.
% If omitted or equal to [], then the string is split
% based on whitespaces occuring in string
%
% pos (optional) a single index indicating which split part
% should be returned. If string is split in N elements,
% then a negative value for pos is equivalent to pos+1+N
% (similar to Python). For example, pos=-1 means that the
% last element is returned, and pos=-2 means that the
% element before the last element is returned.
% If omitted a cell with all parts are returned.
% delim* (optional) subsequent delimeters applied after applying
% pos. It requires that the preceding pos has a single
% value.
%
% Output:
% split when the last argument is non-positional, split is a
% cell with the string split by delim. When there are N
% non-overlapping occurences of delim in string, then
% split has N+1 elements, and the string
% [delim split{1} delim split{2} ... split{N} delim]
% is equal to string.
% If the last argument is positional, then split is
% a string with value split_{pos} where split_ is the
% result if pos where not the last arugment.
% n the number of elements in split, if split is a cell;
% 0 otherwise
%
% Examples:
% % split by '*'
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','*')
% %|| { 'A' 'AbbAbA' 'AbA' 'A' 'Ab' }
%
% % split by 'A*A'
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','A*A')
% %|| { '' 'bbAb' 'b' '*Ab' }
%
% % take second element after split
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','A*A',2)
% %|| 'bbAb'
%
% % get last element after split
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','A*A',-1)
% %|| '*Ab'
%
% % split twice, first on 'A*A', take second element, then on 'A'
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','A*A',2,'A')
% %|| { 'bb' 'b' }
%
% % take first element after second split
% cosmo_strsplit('A*AbbAbA*AbA*A*Ab','A*A',2,'A',1)
% %|| 'bb'
%
% % illustrate effect of not using a delimiter string
% % (which causes the string to be split by whitespace) and using
% % a space as delimiter
% cosmo_strsplit(' CoSMoMVPA makes live... easy!')
% %|| { 'CoSMoMVPA' 'makes' 'live...' 'easy!' }
% cosmo_strsplit(' CoSMoMVPA makes live... easy!',' ')
% %|| { '' 'CoSMoMVPA' 'makes' 'live...' '' 'easy!' }
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
