function[list]=dirc(dir_name,filter,sort_by,group)
%DIRC Directory listing with cell output and optional arguments.
%
% DIRC(DIR_NAME) uses the DIR function to return the directory listing of
% directory DIR_NAME, with usage of optional arguments, and with the
% following differences in output:
%
% - The output is in a 'cell' format instead of a 'structure' format.
%
% - The output includes the following columns (in the stated order):
% Full Item Name, Item Name, Item Extension, Date, Bytes, IsDir
%
% OPTIONAL ARGUMENTS:
%
% The following are arguments that can optionally be used:
%
% (If the value for any of the arguments below is left blank, i.e. if it
% is entered as '', the stated default value is used.)
%
% FILTER:
% a: Return all items (both files and directories) (default).
% ae: Return all items (both files and directories), but excludes the
% '.' and '..' directories if they are present.
% f: Return only files.
% d: Return only directories.
% de: Return only directories, and excludes the '.' and '..'
% directories if they are present.
%
% SORT_BY:
% o: Use original DIR function's dictionary sort (sort by full name)
% (case-sensitive) (default).
% n: Sort by full name (case-insensitive) (alphabetic).
% e: Sort by extension (alphabetic).
% t: Sort by extension and where equal, sort further by full name
% (case-insensitive) (alphabetic).
% d: Sort by date and time (oldest first).
% s: Sort by size (smallest first).
% r: (Suffix this to any of the above, to sort in reverse order.)
%
% GROUP:
% n: Do not group (default).
% d: Group directories first.
% f: Group files first.
%
% EXAMPLES:
% dirc('C:\')
% dirc('C:\Windows','de','n')
% dirc('C:\','','t','d')
%
% REMARKS:
%
% Because FILEPARTS is used to parse the FULL ITEM NAME into ITEM NAME
% and ITEM EXTENSION (as long as the item is a file), the function uses
% additional time to run (assuming PARSE_ITEM_NAMES under CONFIGURABLE
% OPTIONS is left enabled).
%
% The ITEM EXTENSION, if present, does not include an initial dot. This
% is unlike the output of the FILEPARTS function, where the ITEM
% EXTENSION of the output does include an initial dot.
%
% See the CONFIGURABLE OPTIONS section in the code for additional
% options.
%
% VERSION DATE: 2005.06.10
% MATLAB VERSION: 7.0.1.24704 (R14) Service Pack 1
%
% See also DIR, FILEPARTS.
%{
REVISION HISTORY:
2005.06.10: Added 'or' SORT_BY option.
2005.04.12: Removed undesirable 'clc' line from code.
2005.04.07: Original release.
KEYWORDS:
dir, directory, directories, directory listing, folder, folders,
file, files, file name, file names, filename, filenames, fileparts,
ext, extension
%}
%**************************************************************************
%% CONFIGURABLE OPTIONS
parse_item_names=1;
%If set to 1 (default), items are parsed into name and extension. If set to
%0, items are not parsed into name and extension, and those two columns in
%the output are left empty.
parse_dir_names=0;
%If set to 0 (default), only files are parsed into name and extension, and
%directories are not. If set to 1, both files and directories are parsed to
%name and extension. This applies only if PARSE_ITEM_NAMES is set to 1.
%**************************************************************************
%% Confirm FILTER value, if entered, is valid; else set default value.
if nargin>=2,
switch filter
case{'','a','ae','f','d','de'}
otherwise
error('Invalid filter option.')
end
else
filter='';
end
%--------------------------------------------------------------------------
%% Confirm SORT_BY value, if entered, is valid; else set default value.
if nargin>=3,
switch sort_by
case{'','o','or','n','nr','e','er','t','tr','d','dr','s','sr'}
otherwise
error('Invalid sort option.')
end
else
sort_by='';
end
%--------------------------------------------------------------------------
%% Confirm GROUP value, if entered, is valid; else set default value.
if nargin>=4,
switch group
case{'','n','d','f'}
otherwise
error('Invalid group option.')
end
else
group='';
end
%**************************************************************************
%% Get directory listing and convert it to cell format.
list=dir(dir_name);
list=struct2cell(list);
list=list';
%--------------------------------------------------------------------------
%% Insert columns for ITEM NAME and ITEM EXTENSION.
list(:,7:9)=list(:,2:4);
list(:,2:4)='';
%--------------------------------------------------------------------------
%% If PARSE_ITEM_NAMES is enabled, parse and store FULL ITEM NAME into ITEM
% NAME and ITEM EXTENSION in LIST.
if parse_item_names
list_items=size(list,1);
for item_count=1:list_items
%Query ITEM ISDIR status.
item_isdir=list(item_count,6);
item_isdir=cell2mat(item_isdir);
%If ITEM is file or PARSE_DIR_NAMES is enabled, update LIST with
%ITEM_NAME and ITEM_EXT.
item_isfile=(item_isdir==0);
if item_isfile || parse_dir_names
%Query FULL_ITEM_NAME.
full_item_name=list(item_count,1);
full_item_name=cell2mat(full_item_name);
%Generate ITEM_NAME and ITEM_EXT.
[item_path,item_name,item_ext]=...
fileparts([dir_name,'\',full_item_name]);
%IF ITEM_EXT exists, remove dot from it.
item_ext_size=numel(item_ext);
item_ext_exists=(item_ext_size>0);
if item_ext_exists
item_ext=item_ext(2:end);
end
%Update LIST with ITEM_NAME and ITEM_EXT.
list(item_count,2)={item_name};
list(item_count,3)={item_ext};
end
end
end
%**************************************************************************
%% Filter LIST as relevant.
switch filter
case{'','a'}
%Do not delete anything.
case{'ae'}
%Delete '.' and '..' directories if they exist.
if strcmp(cell2mat(list(1,1)),'.') && ...
strcmp(cell2mat(list(2,1)),'..')
list(1:2,:)=[];
end
case{'f'}
%Determine directory indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
dir_indices=find(isdir_values==1);
%Delete directories.
list(dir_indices,:)=[];
case{'d'}
%Determine files.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
file_indices=find(isdir_values==0);
%Delete files.
list(file_indices,:)=[];
case{'de'}
%Determine file indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
file_indices=find(isdir_values==0);
%Delete files.
list(file_indices,:)=[];
%Delete '.' and '..' directories if they exist.
if strcmp(cell2mat(list(1,1)),'.') && ...
strcmp(cell2mat(list(2,1)),'..')
list(1:2,:)=[];
end
end
%**************************************************************************
%% Sort LIST as relevant.
switch sort_by
case{'','o','or'}
%Use default sort.
case{'n','nr'}
%Sort by full name.
full_item_names=list(:,1);
full_item_names=lower(full_item_names);
[full_item_names,index]=sortrows(full_item_names);
list=list(index,:);
case{'e','er'}
%Sort by extension
item_exts=list(:,3);
item_exts_numel=size(item_exts,1);
for item_count=1:item_exts_numel
item_ext=item_exts(item_count);
item_ext=cell2mat(item_ext);
if isequal(item_ext,[])
item_exts(item_count)={''};
end
end
item_exts=lower(item_exts);
[item_exts,index]=sortrows(item_exts);
list=list(index,:);
case{'t','tr'}
%Sort by extension and where equal, sort further by full name
%(executes in reverse).
%Sort by full name.
full_item_names=list(:,1);
full_item_names=lower(full_item_names);
[full_item_names,index]=sortrows(full_item_names);
list=list(index,:);
item_exts=list(:,3);
item_exts_numel=size(item_exts,1);
for item_count=1:item_exts_numel
item_ext=item_exts(item_count);
item_ext=cell2mat(item_ext);
if isequal(item_ext,[])
item_exts(item_count)={''};
end
%Sort by extension.
end
item_exts=lower(item_exts);
[item_exts,index]=sortrows(item_exts);
list=list(index,:);
case{'d','dr'}
%Sort by date and time.
item_dates=list(:,4);
item_dates=cell2mat(item_dates);
item_dates=datenum(item_dates);
[item_dates,index]=sortrows(item_dates);
list=list(index,:);
case{'s','sr'}
%Sort by size
item_sizes=list(:,5);
item_sizes=cell2mat(item_sizes);
[item_sizes,index]=sortrows(item_sizes);
list=list(index,:);
end
%--------------------------------------------------------------------------
%% Reverse the sorted order if relevant.
if numel(sort_by)==2 && sort_by(2)=='r'
list_items=size(list,1);
list=list(list_items:-1:1,:);
end
%**************************************************************************
%% Group LIST as relevant.
switch group
case{'','n'}
%Do not group.
case{'','d'}
%Group directories first.
%Determine directory indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
dir_indices=find(isdir_values==1);
%Determine file indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
file_indices=find(isdir_values==0);
%Merge grouping indices.
regrouping_indices=[dir_indices;file_indices];
%Group
list=list(regrouping_indices,:);
case{'','f'}
%Group files first.
%Determine directory indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
dir_indices=find(isdir_values==1);
%Determine file indices.
isdir_values=list(:,6);
isdir_values=cell2mat(isdir_values);
file_indices=find(isdir_values==0);
%Merge grouping indices.
regrouping_indices=[file_indices;dir_indices];
%Group
list=list(regrouping_indices,:);
end
%**************************************************************************