function  [descr,idx] = find_sbj_descr(sbj_number,database,warnp)

%FIND_SBJ_DESCR -- Look for a particular participant in the database.
%
%  [descr,idx] = find_sbj_descriptor(sbj_number,database)
%
%  SBJ_NUMBER is a number that uniquely identifies the subject.
%  DATABASE must be either a structure or a name (a string) of a file
%  created by SAVE_SBJ_DATABASE or UPDATE_SBJ_DATABASE.
%
%  When DATABASE contains an entry with this SBJ_NUMBER, it is returned
%  in DESCR and its index in the database array in IDX.
%  When multiple matching entries exist the leftmost one is returned
%  in DESCR; IDX contains a row vector of all matching indices.
%  As it is anomalous to have multiple matching entries, a warning is
%  issued unless WARNP is 0 (it defaults to 1).
%  If no entries match the query, DESCR is set to [] and IDX to [].
%
%  See also NEW_SBJ_DESCR, OPEN_SBJ_DATABASE.

% Original coding by Alex Petrov, Ohio State University
% $Revision: 1.0 $  $Date: 2002/01/03 15:27 $
%
% Part of the utils toolbox version 1.1 for MATLAB version 5 and up.
% http://alexpetrov.com/softw/utils/
% Copyright (c) Alexander Petrov 1999-2006, http://alexpetrov.com
% Please read the LICENSE and NO WARRANTY statement in ../utils_license.m

if (nargin < 3)   warnp = 1 ;  end         % issue warnings by default

database = open_sbj_database(database) ;   % filename --> struct
all_Ss = [database(:).sbj_number] ;
idx = find(all_Ss==sbj_number) ;

if (isempty(idx))      % no subject with this number
   descr = [] ;   
elseif (length(idx)>1)
   if warnp
      w = sprintf('Multiple (%d) entries exist for subject number %d.',...
                  length(idx),sbj_number) ;
      warning(w) ;
   end
   descr = database(min(idx)) ;     % use the leftmost entry
else   % there is a unique entry
   descr = database(idx) ;
end

%--- Return DESCR and IDX
%%%%% End of file SBJ_DESCRIPTOR.M
