FUN_nc_time_select_from_multi_files.m

function [filelist, timelist] = FUN_nc_time_select_from_multi_files( file_dir, file_list_in, time_var_str, timelimit, is_AutoTimeUnit )
%  [filelist, timelist] = FUN_nc_time_select_from_multi_files( file_dir, file_list_in, time_var_str, timelimit, is_AutoTimeUnit )
% This function is written to find the records within a specific time
% limit from multiple files.
% INPUT
%      file_dir     : path to the folder conatining all the files
%      file_list_in : It can be either a string or a strcutures array
%                     [string]: Name of the files (e.g., ECCOV4R2* for all files starting with ECCOV4R2 )
%                     [strucutre array]: generated by the command "dir", e.g., file_list_in = dir( 'ECCO4R2*.nc');
%      time_var_str : name of the time variable/axis in nc files. 
%                     Please note
%      is_AutoTimeUnit: 
%                    true:  loading the time unit and its origin from the "units" property. 
%                    false: load the time series as is. 
%
% OUTPUT
%     filelist: structure
%               filelist.timelist_all: All times in this file no matter they are in or out of the timelimit 
%               filelist.timelist    : Times in this file which are also within the timelimit
%
%        see FUN_nc_varget_sub_genStartCount for the following three values
%               filelist.nc_time.start
%               filelist.nc_time.count
%               filelist.nc_time.loc
%
%     timelist: Time from all files within the timelimit

% V1.10 By L. Chi
% V1.00 By L. Chi (L.Chi.Ocean@outlook.com)


%% Debug only
% 
% file_dir     = 'I:\Data\ECCOv4\release2\Convert_intput_force_gcmface_into_ll.wrongData\input_forcing_monthly';
% filenamestr  = 'ECCOV4R2*';
% time_var_str = 'time';
% timelimit    = [ datenum(2002,5,1) datenum(2005,9,30) ];

%% Initial values
    timelist0 = []; % Total timelist, including time out of the limit

%% prepare data
if isstruct( file_list_in )
    filelist = file_list_in;
else
    filelist = dir( fullfile( file_dir, file_list_in) );
end

%% check
is_load_time_from_var = FUN_nc_exist_var( fullfile( file_dir, filelist(1).name ), time_var_str );

if ~is_load_time_from_var
    warning('Cannot find the variable for time. The value of time will be counted from 1!');
    disp('Please be cautious about the rank of files!');
    
    if is_AutoTimeUnit
       error('is_AutoTimeUnit cannot be turned on for the missing of time values') 
    end
end

%% generate timelist for each file

for it = 1:length( filelist )
    
    % load time info ------------------------------------------------------
    file_now = fullfile( file_dir, filelist(it).name );
    if is_AutoTimeUnit
        tem_timelist = FUN_nc_get_time_in_matlab_format( file_now, time_var_str );
    elseif is_load_time_from_var
        tem_timelist = FUN_nc_varget_enhanced( file_now, time_var_str );
    else
        tem_dim_length = FUN_nc_get_dim_length(  file_now, time_var_str );
        
        if it == 1
            tem_timelist = 1 : tem_dim_length;
        else
            tem_timelist = [ 1 : tem_dim_length ] + timelist0(end) ;
        end
    end
    timelist0 = [ timelist0 ; tem_timelist(:)];
    
    % find records within the given timelimit -----------------------------
    if all( tem_timelist > max(timelimit) ) || all( tem_timelist < min(timelimit) )
        % This file is completely out of the time limit
        filelist(it).within_limit = false;
    else
        filelist(it).within_limit = true;
        
        [filelist(it).nc_time.start, filelist(it).nc_time.count, filelist(it).nc_time.loc] = FUN_nc_varget_sub_genStartCount( tem_timelist, timelimit );
        filelist(it).timelist_all  = tem_timelist;  
        filelist(it).timelist      = tem_timelist(filelist(it).nc_time.loc);  
        
        if it == 1
            filelist(it).ind_start = 1;
            filelist(it).ind_end   = filelist(it).nc_time.count;
        else
            filelist(it).ind_start = filelist(it-1).ind_end + 1;
            filelist(it).ind_end   = filelist(it-1).ind_end + filelist(it).nc_time.count ;
        end
   
    end
    

end

filelist = filelist( [filelist.within_limit] );

%% double check
timelist_check = timelist0( timelist0 >= timelimit(1) & timelist0 <= timelimit(2) );
timelist = cat(1, filelist(:).timelist );
if all( timelist == timelist_check )
else
   error('Something wrong during selecting the time records, please check.') 
end

%% resort the files
tem_time_for_sort = nan(length(filelist),1);
for it = 1:length(filelist)
    tem_time_for_sort(it,1) = filelist(it).timelist(1);
end

[~, sort_ind ] = sort( tem_time_for_sort, 'ascend' );

filelist = filelist(sort_ind);
timelist = cat(1, filelist(:).timelist );

if all( timelist(2:end) > timelist(1:end-1) )
else
   warning('The timelist is not monotony!') 
end