Functions
function	abs (in path, in style)
	Return the Get absolute canonical path of a file or folder. More...

Function Documentation

◆ abs()

function abs	(	in	path,
		in	style
	)

Return the Get absolute canonical path of a file or folder.

Absolute path names are safer than relative paths, e.g., when a GUI or TIMER callback changes the current directory.
Only canonical paths without "." and ".." can be recognized uniquely.

Note: Long path names (>259 characters) require a magic initial key "\\?\" to be handled by Windows API functions, e.g. for MATLAB intrinsic routines fopen(), dir() and exist().; Some functions of the Windows-API still do not support long file names.
For example, the Recycler and the Windows Explorer fail even with the magic '\\?\' prefix.
Some functions of MATLAB accept 260 characters (value of MAX_PATH), some at 259 already.
The 'fat' style is useful e.g., when MATLAB dir() command is called for a folder with less than 260 characters, but together with the file name this limit is exceeded.
Then, "dir(pm.sys.path.abs([folder, '\*.*'], 'fat'))" helps.

Developer Remark:: A MEX version of this function developed by Jan Simon performs much faster on Windows.
Difference between M- and Mex-version:

Mex does not work under MacOS/Unix.
Mex calls Windows API function pm.sys.path.abs.
Mex is much faster.

Parameters

[in]	path	: The input argument that can be either, a scalar MATLAB string or character, or, a MATLAB string or cell array of strings or character values, containing the absolute or relative name(s) of a file(s) or folder(s). The path need not exist. Unicode strings, UNC paths and long names are supported.
[in]	style	: The optional input scalar MATLAB string or character, containing the style of the output as string. The following values are possible: `'auto'` : Add `'\\?\'` or `'\\?\UNC\'` for long names on demand. `'lean'` : Magic string is not added. `'fat'` : Magic string is added for short names also. The input `style` is ignored when not running under Windows. (optional, default = 'auto')

Returns: path : The output scalar MATLAB character string containing the absolute path corresponding to the input path.
If the input path is empty, pathAbs is the current directory.
The optional prefixes '\\?\' or '\\?\UNC' are added on demand as requested by the optional input argument style.

Possible calling interfaces ⛓

: path = pm.sys.path.abs(file)

path = pm.sys.path.abs(file, style)

See also: A collection of MATLAB mex files for system path manipulation

Example usage ⛓

: cd(tempdir); % Assumed as 'C:\Temp' here

pm.sys.path.abs('File.Ext') % 'C:\Temp\File.Ext'

pm.sys.path.abs('..\File.Ext') % 'C:\File.Ext'

pm.sys.path.abs('..\..\File.Ext') % 'C:\File.Ext'

pm.sys.path.abs('.\File.Ext') % 'C:\Temp\File.Ext'

pm.sys.path.abs('*.txt') % 'C:\Temp\*.txt'

pm.sys.path.abs('..') % 'C:\'

pm.sys.path.abs('..\..\..') % 'C:\'

pm.sys.path.abs('Folder\') % 'C:\Temp\Folder\'

pm.sys.path.abs('D:\A\..\B') % 'D:\B'

pm.sys.path.abs('\\Server\Folder\Sub\..\File.ext') % '\\Server\Folder\File.ext'

pm.sys.path.abs({'..', 'new'}) % {'C:\', 'C:\Temp\new'}

pm.sys.path.abs(["..", "new"]) % ["C:\", "C:\Temp\new"]

pm.sys.path.abs('.', 'fat') % '\\?\C:\Temp\File.Ext'

Example usage ⛓

: 1cd(fileparts(mfilename('fullpath'))); % Change working directory to source code directory.

2addpath('../../../../'); % Add the ParaMonte library root directory to the search path.

3

4pm.matlab.show()

5pm.matlab.show('cd(tempdir); pwd')

6 cd(tempdir); pwd

7

8pm.matlab.show()

9pm.matlab.show('pm.sys.path.abs("File.Ext")')

10pm.matlab.show( pm.sys.path.abs("File.Ext") )

11

12pm.matlab.show()

13pm.matlab.show('pm.sys.path.abs("..\File.Ext")')

14pm.matlab.show( pm.sys.path.abs("..\File.Ext") )

15

16pm.matlab.show()

17pm.matlab.show('pm.sys.path.abs("..\..\File.Ext")')

18pm.matlab.show( pm.sys.path.abs("..\..\File.Ext") )

19

20pm.matlab.show()

21pm.matlab.show('pm.sys.path.abs(".\File.Ext")')

22pm.matlab.show( pm.sys.path.abs(".\File.Ext") )

23

24pm.matlab.show()

25pm.matlab.show('pm.sys.path.abs("*.txt")')

26pm.matlab.show( pm.sys.path.abs("*.txt") )

27

28pm.matlab.show()

29pm.matlab.show('pm.sys.path.abs("..")')

30pm.matlab.show( pm.sys.path.abs("..") )

31

32pm.matlab.show()

33pm.matlab.show('pm.sys.path.abs("..\..\..")')

34pm.matlab.show( pm.sys.path.abs("..\..\..") )

35

36pm.matlab.show()

37pm.matlab.show('pm.sys.path.abs("Folder\")')

38pm.matlab.show( pm.sys.path.abs("Folder\") )

39

40pm.matlab.show()

41pm.matlab.show('pm.sys.path.abs("D:\A\..\B")')

42pm.matlab.show( pm.sys.path.abs("D:\A\..\B") )

43

44pm.matlab.show()

45pm.matlab.show('pm.sys.path.abs("\\Server\Folder\Sub\..\File.ext")')

46pm.matlab.show( pm.sys.path.abs("\\Server\Folder\Sub\..\File.ext") )

47

48pm.matlab.show()

49pm.matlab.show('pm.sys.path.abs(["..", "new"])')

50pm.matlab.show( pm.sys.path.abs(["..", "new"]) )

51

52pm.matlab.show()

53pm.matlab.show("pm.sys.path.abs({'..', 'new'})")

54pm.matlab.show( pm.sys.path.abs({'..', 'new'}) )

55

56pm.matlab.show()

57pm.matlab.show('pm.sys.path.abs(".", "fat")')

58pm.matlab.show( pm.sys.path.abs(".", "fat") )

root
function root()
Return a scalar MATLAB string containing the root directory of the ParaMonte library package.

Example output ⛓
1

2cd(tempdir); pwd

3ans =

4 '/tmp'

5

6pm.sys.path.abs("File.Ext")

7/tmp/File.Ext

8

9pm.sys.path.abs("..\File.Ext")

10/File.Ext

11

12pm.sys.path.abs("..\..\File.Ext")

13/File.Ext

14

15pm.sys.path.abs(".\File.Ext")

16/tmp/File.Ext

17

18pm.sys.path.abs("*.txt")

19/tmp/*.txt

20

21pm.sys.path.abs("..")

22/

23

24pm.sys.path.abs("..\..\..")

25/

26

27pm.sys.path.abs("Folder\")

28/tmp/Folder/

29

30pm.sys.path.abs("D:\A\..\B")

31/tmp/D:/B

32

33pm.sys.path.abs("\\Server\Folder\Sub\..\File.ext")

34//Server/Folder/File.ext

35

36pm.sys.path.abs(["..", "new"])

37 "/" "/tmp/new"

38

39pm.sys.path.abs({'..', 'new'})

40{1}

41/

42{2}

43/tmp/new

44

45pm.sys.path.abs(".", "fat")

46/tmp

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

This file is based on a functionality originally developed by Jan Simon.

///      Copyright (c) 2016, Jan Simon
///      All rights reserved.
///
///      Redistribution and use in source and binary forms, with or without
///      modification, are permitted provided that the following conditions are met:
///
///      * Redistributions of source code must retain the above copyright notice, this
///        list of conditions and the following disclaimer.
///
///      * Redistributions in binary form must reproduce the above copyright notice,
///        this list of conditions and the following disclaimer in the documentation
///        and/or other materials provided with the distribution
///      * Neither the name of  nor the names of its
///        contributors may be used to endorse or promote products derived from this
///        software without specific prior written permission.
///      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
///      AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
///      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
///      DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
///      FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
///      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
///      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
///      CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
///      OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
///      OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
///
///      Tested: MATLAB 2009a, 2015b(32/64), 2016b, 2018b, Win7/10
///              Compiler: LCC2.4/3.8, BCC5.5, OWC1.8, MSVC2008/2010
///      Assumed Compatibility: higher MATLAB versions
///      Author: Jan Simon, Heidelberg, (C) 2009-2019 matlab.2010(a)n(MINUS)simon.de
///
///      $JRev: R-M V:038 Sum:C/6JMzUYsYsc Date:19-May-2019 17:25:55 $
///      $License: BSD (use/copy/change/redistribute on own risk, mention the author) $
///      $UnitTest: uTest_getFullPath $
///      $File: Tools\GLFile\pm.sys.path.abs.m $
///      History:
///      001: 20-Apr-2010 22:28, Successor of Rel2AbsPath.
///      010: 27-Jul-2008 21:59, Consider leading separator in M-version also.
///      011: 24-Jan-2011 12:11, Cell strings, '~File' under linux.
///           Check of input types in the M-version.
///      015: 31-Mar-2011 10:48, BUGFIX: Accept [] as input as in the Mex version.
///           Thanks to Jiro Doke, who found this bug by running the test function for
///           the M-version.
///      020: 18-Oct-2011 00:57, BUGFIX: Linux version created bad results.
///           Thanks to Daniel.
///      024: 10-Dec-2011 14:00, Care for long names under Windows in M-version.
///           Improved the unittest function for Linux. Thanks to Paul Sexton.
///      025: 09-Aug-2012 14:00, In MEX: Paths starting with "\\" can be non-UNC.
///           The former version treated "\\?\C:\<longpath>\file" as UNC path and
///           replied "\\?\UNC\?\C:\<longpath>\file".
///      032: 12-Jan-2013 21:16, 'auto', 'lean' and 'fat' style.
///      038: 19-May-2019 17:25, BUGFIX, Thanks HHang Li, "File(7:..." -> "File(8:..."
///

Author:: Joshua Alexander Osborne, May 21 2024, 5:15 AM, University of Texas at Arlington
Fatemeh Bagheri, May 20 2024, 1:25 PM, NASA Goddard Space Flight Center (GSFC), Washington, D.C.
Amir Shahmoradi, May 16 2016, 9:03 AM, Oden Institute for Computational Engineering and Sciences (ICES), UT Austin

Functions

Function Documentation

◆ abs()