function [field,value] = get_field_value(X,allow)

% get_field_value - get_field value pairs from cell array
% -------------------------------------------------------
%
% [field,value] = get_field_value(X,allow)
%
% Input:
% ------
%  X - cell array containing field value pairs
%  allow - allowed field names
%
% Output:
% -------
%  field - field names cell array
%  value - values cell array

%--------------------------------
% Author: Harold Figueroa
%--------------------------------
% $Revision: 1472 $
% $Date: 2005-08-05 20:01:05 -0400 (Fri, 05 Aug 2005) $
%--------------------------------

% TODO: add unique flag to only allow a single instance of field value pair

% TODO: consider adding case insensitivity

%---------------------------------------------
% HANDLE INPUT
%---------------------------------------------

%--
% set default allow (allow anything)
%--

% NOTE: consider using regular expressions

if (nargin < 2)
	allow = cell(0);
end

%--
% handle special case of empty input
%--

if (isempty(X))	
	field = cell(0); value = cell(0); return;	
end

%--
% check for cell input of even length
%--

if (~iscell(X))
	disp(' '); 
	error('Input must be of type cell.');
end

if (mod(length(X),2))
	disp(' ');
	error('Input cell array must be of even length.');
end

%---------------------------------------------
% GET FIELDS AND VALUES
%---------------------------------------------

%--
% separate fields and values
%--

field = X(1:2:end); value = X(2:2:end);

%--
% check that field names are strings
%--

for k = 1:length(field)
	
	if (~ischar(field{k}))
		disp(' ');
		error('Contents of odd indexed cells must be strings.');
	end
	
end

%--
% check for allowed fields
%--

% NOTE: consider ignoring the not allowed field

if (~isempty(allow))
	
	for k = 1:length(field)
	
		% NOTE: find the fields in the allowed fields list
		
		if (isempty(find(strcmp(field{k},allow))))
			disp(' ');
			error(['Field ''' field{k} ''' is not an allowed field.']);
		end

	end

end

%--
% sort the field value pairs by field names
%--

[field,ix] = sort(field);

value = value(ix);
	