vb_table_query_value

 search record by key and return the value of the record.

 [USAGE]
    [value, extra_data] = vb_table_query_value(table, key);
 [IN]
      key : key for search record. <<string>>
    table : table data.      [Nx1 struct]
           .key   : search key <<string>>
           .value : value. any type is ok.
           <<extended specification>>
            - you can add extra fields freely. (e.g. extra1, extra2)
           .extra1 : any name, any type is ok.
           .extra2 : any name, any ttype is ok.
 [OUT]
         value : value in the found record.
    extra_data : User defined extra fields.
                 <<struct>> extra fields are returned by structure.
                  e.g. extra_data.extra1
                                 .extra2
 [see]
    vb_key_value_pair.m
    vb_table_insert.m

 [example]
     tbl = [];
     % create record
     key = 'brain_file';
     value = 'Cortical model file (.brain.mat)';
     record = vb_key_value_pair(key, value);
     % insert
     tbl = vb_table_insert(tbl, record);
     % inquery
     value  = vb_table_query_value(tbl, key);

 Copyright (C) 2011, ATR All Rights Reserved.
 License : New BSD License(see VBMEG_LICENSE.txt)

0001 function [value, extra_data] = vb_table_query_value(table, key)
0002 % search record by key and return the value of the record.
0003 %
0004 % [USAGE]
0005 %    [value, extra_data] = vb_table_query_value(table, key);
0006 % [IN]
0007 %      key : key for search record. <<string>>
0008 %    table : table data.      [Nx1 struct]
0009 %           .key   : search key <<string>>
0010 %           .value : value. any type is ok.
0011 %           <<extended specification>>
0012 %            - you can add extra fields freely. (e.g. extra1, extra2)
0013 %           .extra1 : any name, any type is ok.
0014 %           .extra2 : any name, any ttype is ok.
0015 % [OUT]
0016 %         value : value in the found record.
0017 %    extra_data : User defined extra fields.
0018 %                 <<struct>> extra fields are returned by structure.
0019 %                  e.g. extra_data.extra1
0020 %                                 .extra2
0021 % [see]
0022 %    vb_key_value_pair.m
0023 %    vb_table_insert.m
0024 %
0025 % [example]
0026 %     tbl = [];
0027 %     % create record
0028 %     key = 'brain_file';
0029 %     value = 'Cortical model file (.brain.mat)';
0030 %     record = vb_key_value_pair(key, value);
0031 %     % insert
0032 %     tbl = vb_table_insert(tbl, record);
0033 %     % inquery
0034 %     value  = vb_table_query_value(tbl, key);
0035 %
0036 % Copyright (C) 2011, ATR All Rights Reserved.
0037 % License : New BSD License(see VBMEG_LICENSE.txt)
0038 
0039 
0040 %
0041 % --- Previous check
0042 %
0043 if ~exist('table', 'var')
0044     error('table is a required parameter.');
0045 end
0046 if ~exist('key', 'var')
0047     error('key is a required parameter.');
0048 end
0049 if ~ischar(key)
0050     error('key should be string.');
0051 end
0052 if isempty(table) || ~isstruct(table(1)) || ...
0053    ~isfield(table(1), 'key') || ~isfield(table(1), 'value')
0054     error('Unknown format table were specified.');
0055 end
0056 
0057 %
0058 % --- Main Procedure
0059 %
0060 value = [];
0061 extra_data = [];
0062 
0063 % Search
0064 keys = {table.key};
0065 ix = strmatch(key, keys, 'exact');
0066 
0067 if ~isempty(ix)
0068     if length(ix) >= 2
0069         error('multiple records were found. Please check table data.');
0070     end
0071 
0072     % value
0073     record = table(ix);
0074     value = record.value;
0075 
0076     % extra_data
0077     fields = fieldnames(record);
0078     Nfields = length(fields);
0079     if Nfields > 2
0080         % create extra_data
0081         extra_data = struct;
0082         for k=1:Nfields
0083             field_name = fields{k};
0084             if ~strcmp(field_name, 'key') && ~strcmp(field_name, 'value')
0085                 extra_data.(field_name) = record.(field_name);
0086             end
0087         end
0088     end
0089 end
0090