% VChooseKRO.c
% VChooseKRO - Permutations of K elements [MEX]
% VChooseKRO(V, K) creates a matrix, which rows are all permutations of
% choosing K elements of the vector V with order and with repetitions.
%
% INPUT:
% V: Array of class DOUBLE, SINGLE, (U)INT8/16/32/64, LOGICAL, CHAR.
% V can have any shape.
% K: Number of elements to choose. Scalar DOUBLE with integer value >= 0.
%
% OUTPUT:
% Y: Matrix of size [N^K, K] with N is the number of elements of V.
% Y has the same class as the input V.
% A warning appears, if the output exceeds 500MB, and an error for 1GB.
% Both limits can be adjusted according to the available RAM in the
% C-Mex source.
%
% EXAMPLES:
% Choose 2 elements from [1,2,3]:
% VChooseKRO(1:3, 2) % ==> [1,1; 1,2; 1,3; 2,1; 2,2; 2,3; 3,1; 3,2; 3,3]
% For speed cast the input to integer types if possible:
% Y = double(VChooseKRO(int16(1:1000), 2));
% is faster than:
% Y = VChooseKRO(1:1000, 2);
% To get the combinations of cell arrays, use the combinations of the index:
% C = {'a', 'b', 'c', 'd'};
% C2 = C(VChooseKRO(1:4, 2))
% ==> C2 = {'a', 'b'; 'a', 'c'; 'a', 'd'; 'b', 'c'; 'b', 'd'; 'c', 'd'}
%
% COMPILE:
% mex -O VChooseKRO.c
% Precompiled MEX: http://www.n-simon.de/mex
% Compatibility to 64-bit machines is assumed, but cannot be tested currently.
% On Linux the C99 comments must be considered (thanks Sebastiaan Breedveld):
% mex CFLAGS="\$CFLAGS -std=C99" -O VChooseKRO.c
% Please run the unit-test TestVChooseKRO after compiling!
%
% Tested: Matlab 6.5, 7.7, 7.8, WinXP, [UnitTest]
% Compilers: BCC5.5, LCC2.4/3.8, Open Watcom 1.8
% Watcom lib is 20% faster than BCC and LCC libs for INT8!
% Author: Jan Simon, Heidelberg, (C) 2010 matlab.THISYEAR(a)nMINUSsimon.de
% License: BSD (use/copy/modify on own risk, but mention author)
%
% See also: NCHOOSEK, PERMS.
% FEX: COMBINATOR, NPERMUTEK, COMBINATIONS, COMBN, VCHOOSEK.
% Other related publications in the FEX:
% (http://www.mathworks.com/matlabcentral/fileexchange/<number>)
% COMBINATOR (Matt Fig) with/without order/repetitions: 24325
% NPERMUTEK (Matt Fig): 11462
% COMBINATIONS (Gautam Vallabha): 23080
% COMBN (Jos van der Geest): 7147
% VCHOOSEK (Jan Simon) no order, no repetitions: 26190
% This M-file allows to use Matlab's HELP function directly.
