# NATSORTFILES Examples

The function NATSORTFILES sorts filenames or filepaths, taking into account number values within the strings. This is known as natural order or alphanumeric order. Note that MATLAB's inbuilt SORT function sorts only by character order, as does SORT in most programming languages.

NATSORTFILES does not just provide a naive alphanumeric sort, it also splits and sorts the file/folder names and file extensions separately, which means that shorter names come before longer ones. For the same reason filepaths are split at every path-separator character and each folder level is sorted separately. See the "Explanation" sections below for more details.

To sort the rows of a string/cell array use NATSORTROWS.

To sort the elements of a string/cell array use NATSORT.

## Basic Usage

By default NATSORTFILES interprets consecutive digits as being part of a single integer, any remaining substrings are treated as text.

```A = {'a2.txt', 'a10.txt', 'a1.txt'};
sort(A)
natsortfiles(A)
```
```ans =
'a1.txt'    'a10.txt'    'a2.txt'
ans =
'a1.txt'    'a2.txt'    'a10.txt'
```

## Input 1: Array to Sort

The first input must be one of the following array types:

• a cell array of character row vectors,
• a string array,
• the structure array returned by DIR.

The sorted array is returned as the first output argument, making NATSORTFILES very simple to include with any code:

```P = 'natsortfiles_test';
S = dir(fullfile('.',P,'A*.txt'));
S = natsortfiles(S);
for k = 1:numel(S)
fprintf('%-13s%s\n',S(k).name,S(k).date)
end
```
```A_1.txt      27-Nov-2020 06:19:36
A_1-new.txt  27-Nov-2020 06:19:36
A_1_new.txt  27-Nov-2020 06:19:36
A_2.txt      27-Nov-2020 06:19:36
A_3.txt      27-Nov-2020 06:19:36
A_10.txt     27-Nov-2020 06:19:36
A_100.txt    27-Nov-2020 06:19:36
A_200.txt    27-Nov-2020 06:19:36
```

## Input 2: Regular Expression

The optional second input argument is a regular expression which specifies the number matching (see "Regular Expressions" section below):

```B = {'1.3.txt','1.10.txt','1.2.txt'};
natsortfiles(B)   % by default match integers
natsortfiles(B, '\d+\.?\d*') % match decimal fractions
```
```ans =
'1.2.txt'    '1.3.txt'    '1.10.txt'
ans =
'1.10.txt'    '1.2.txt'    '1.3.txt'
```

## Input 3+: Remove "." and ".." Names

The dot directory names "." and ".." can be removed using the "rmdot" option:

```S = dir(fullfile('.','HTML','*'));
{S.name}
S = natsortfiles(S,[],'rmdot');
{S.name}
```
```ans =
'.'    '..'    'natsort_doc.html'    [1x20 char]
ans =
'natsort_doc.html'    'natsortrows_doc.html'
```

## Input 3+: No File Extension

For names that do not have file extensions (e.g. folder names, filenames without extensions) then the optional 'noext' argument should be used:

```C = {'1.9','1.10','1.2'}; % names without extensions
natsortfiles(C,'\d+\.?\d*') % by default the dot indicates the file extension
natsortfiles(C,'\d+\.?\d*','noext')
```
```ans =
'1.2'    '1.9'    '1.10'
ans =
'1.10'    '1.2'    '1.9'
```

## Input 3+: Ignore File Path

By default the filepath (if provided) will be taken into account and sorted too (either split from the filename, or taken from the folder field). To ignore the path and sort by filename only simply specify the optional 'xpath' argument:

```D = {'B/3.txt','A/1.txt','B/100.txt','A/20.txt'};
natsortfiles(D) % by default sorts the file path too
natsortfiles(D,[],'xpath')
```
```ans =
'A/1.txt'    'A/20.txt'    'B/3.txt'    'B/100.txt'
ans =
'A/1.txt'    'B/3.txt'    'A/20.txt'    'B/100.txt'
```

## Inputs 3+: Optional Arguments

Further inputs are passed directly to NATSORT, thus giving control over the case sensitivity, sort direction, and other options. See the NATSORT help for explanations and examples of the supported options:

```E = {'B.txt','10.txt','1.txt','A.txt','2.txt'};
natsortfiles(E, [], 'descend')
natsortfiles(E, [], 'char<num')
```
```ans =
'B.txt'    'A.txt'    '10.txt'    '2.txt'    '1.txt'
ans =
'A.txt'    'B.txt'    '1.txt'    '2.txt'    '10.txt'
```

## Output 2: Sort Index

The second output argument is a numeric array of the sort indices ndx, such that Y = X(ndx) where Y = natsortfiles(X):

```F = {'abc2xyz.txt', 'abc2xy8.txt', 'abc10xyz.txt', 'abc1xyz.txt'};
[out,ndx] = natsortfiles(F)
```
```out =
'abc1xyz.txt'    'abc2xy8.txt'    'abc2xyz.txt'    'abc10xyz.txt'
ndx =
4     2     1     3
```

## Output 3: Debugging Array

The third output is a cell vector of cell arrays which correspond to the input directory hierarchy, filenames, and file extensions. The cell arrays contain any matched numbers (after converting to numeric using the specified SSCANF format) and all non-number substrings. These cell arrays are useful for confirming that the numbers are being correctly identified by the regular expression.

```[~,~,dbg] = natsortfiles(F);
dbg{:}
```
```ans =
'abc'    [ 2]    'xyz'     []
'abc'    [ 2]    'xy'     
'abc'        'xyz'     []
'abc'    [ 1]    'xyz'     []
ans =
'.txt'
'.txt'
'.txt'
'.txt'
```

## Explanation: Short Before Long

Filenames and file extensions are joined by the extension separator, the period character '.'. Using a normal SORT this period gets sorted after all of the characters from 0 to 45 (including !"#\$%&'()*+,-, the space character, and all of the control characters, e.g. newlines, tabs, etc). This means that a naive sort returns some shorter filenames after longer filenames. To ensure that shorter filenames come first, NATSORTFILES splits filenames from file extensions and sorts them separately:

```G = {'test_ccc.m'; 'test-aaa.m'; 'test.m'; 'test.bbb.m'};
sort(G) % '-' sorts before '.'
natsort(G) % '-' sorts before '.'
natsortfiles(G) % short before long
```
```ans =
'test-aaa.m'
'test.bbb.m'
'test.m'
'test_ccc.m'
ans =
'test-aaa.m'
'test.bbb.m'
'test.m'
'test_ccc.m'
ans =
'test.m'
'test-aaa.m'
'test.bbb.m'
'test_ccc.m'
```

## Explanation: Filenames

NATSORTFILES sorts the split name parts using a natural-order sort, so that the number values within the filenames are taken into consideration:

```H = {'test2.m'; 'test10-old.m'; 'test.m'; 'test10.m'; 'test1.m'};
sort(H) % Wrong number order.
natsort(H) % Correct number order, but longer before shorter.
natsortfiles(H) % Correct number order and short before long.
```
```ans =
'test.m'
'test1.m'
'test10-old.m'
'test10.m'
'test2.m'
ans =
'test1.m'
'test2.m'
'test10-old.m'
'test10.m'
'test.m'
ans =
'test.m'
'test1.m'
'test2.m'
'test10.m'
'test10-old.m'
```

## Explanation: Filepaths

For much the same reasons, filepaths are split at each file path separator character (note that for PCs both '/' and '\' are considered as path separators, for Linux and Mac only '/' is) and every level of the directory structure is sorted separately:

```I = {'A2-old/test.m';'A10/test.m';'A2/test.m';'AXarchive.zip';'A1/test.m'};
sort(I) % Wrong number order, and '-' sorts before '/'.
natsort(I) % Correct number order, but long before short.
natsortfiles(I) % Correct number order and short before long.
```
```ans =
'A1/test.m'
'A10/test.m'
'A2-old/test.m'
'A2/test.m'
'AXarchive.zip'
ans =
'A1/test.m'
'A2-old/test.m'
'A2/test.m'
'A10/test.m'
'AXarchive.zip'
ans =
'A1/test.m'
'A2/test.m'
'A2-old/test.m'
'A10/test.m'
'AXarchive.zip'
```

## Regular Expressions: Decimal Numbers, E-notation, +/- Sign

NATSORTFILES number matching can be customized to detect numbers with a decimal fraction, E-notation, a +/- sign, binary/hexadecimal, or other required features. The number matching is specified using an appropriate regular expression, see NATSORT for details and examples.

```J = {'1.23V.csv','-1V.csv','+1.csv','010V.csv','1.200V.csv'};
natsortfiles(J) % by default match integers only.
natsortfiles(J,'[-+]?\d+\.?\d*')
```
```ans =
'1.23V.csv'    '1.200V.csv'    '010V.csv'    '+1.csv'    '-1V.csv'
ans =
'-1V.csv'    '+1.csv'    '1.200V.csv'    '1.23V.csv'    '010V.csv'
```

## Bonus: Interactive Regular Expression Tool

Regular expressions are powerful and compact, but getting them right is not always easy. One assistance is to download my interactive tool IREGEXP, which lets you quickly try different regular expressions and see all of REGEXP's outputs displayed and updated as you type.