Class Path String

Path String is an extended interface for the String class that adds path manipulation capability.

The following functions analyze or change Path Strings to various ends. None of these functions require that a specified file exists, test whether a given path refers to a directory or to a file, or retrieve the current directory.  The functions listed here interpret paths according to the following guidelines:

1. It is valid for a filename to have multiple dots.
2. A dot at the very beginning of a filename does not divide the base filename from the extension; this would imply that there is no base filename.  Also, Unix/Linux systems use a dot at the beginning of the filename to indicate the file should be hidden.
3. Except as restricted by (2), The text after the last dot of the filename is considered to be the extension.  If there is no dot, or if there is just one dot at the beginning of the filename, the file is considered to have no extension.
4. A filename wholly consisting of a single dot is considered to be a redundant reference to the current directory.
5. A filename wholly consisting of a two adjacent dots is considered to be a reference to the parent directory.
6. A path separator is one of these single characters: a slash (/), a backslash (\), or the character returned from PathSeparator.
7. Paths may have a "drive specification".  This term refers not only to DOS drive letter specifications (C:, etc.) but to protocol specifications such as http:.  A drive specification is identified by a series of characters (not including a path separator) followed by a colon (:)
8. An absolute path is denoted by one or two path separator character(s) at either:
   • The beginning of the string, or
   • Immediately after the colon in the drive specification.

The following are syntax errors in paths:

1. Spaces before or after the path, or adjacent to a colon or path separator.
2. Two or more adjacent path separators.  There is one exception: At the very beginning of the path string, or immediately after a colon character, two path separators may be adjacent.
3. A colon, located anywhere after a path separator or another colon.

How an individual function handles these errors is undefined if unless specified by the description of the function. Some function descriptions mention This, which refers to the object on which the function is called.

Function AddPath (Path2: String @);

Trims the paths of whitespace on either side of This and Path2 (without modifying the original strings) and adds Path2 to This. If Path2 is an absolute path, its contents replace This. The standard current- and previous-directory strings (., ..) are recognized. Forward and backward slashes are recognized; when the function inserts a path separator, it uses the operating-system default. Examples:

Before          Path2           After
C:\             DOS             C:\DOS
C:Windows       Run\Slowly      C:Windows\Run\Slowly
My Files        Diary\Mine.doc  My Files\Diary\Mine.doc
\\X\Y\          Z\A             \\X\Y\Z\A
\C\D\E          \AbsPath        \AbsPath
\X\Q\..\        Y\.\Z\G\..      \X\Y\Z

Function RemoveLastPath (): Boolean;

Removes the last path component from the string. Returns False on failure. Examples:

Before          After           Return Value
\\              \\              False
C:\             C:\             False
Alpha\Beta      Alpha\          True
C:\DOS\Run.txt  C:\DOS\         True
\X\Y\..\Z\..    \X\Y\..\Z\      True

Function CollapsePath (): Boolean;

Trims unnecessary spaces from the path, including spaces adjacent to path separators. Removes . and .. directories from the path.  Returns True if any changes were made to the path. Examples:

Before          After           Return Value
C:\DOS          C:\DOS          False
.                               True
..              ..              False
\X\..           \               True
  A \ B         A\B             True
A\..\B\.\C\..   B               True

Static Function PathSeparator(): Char;

Returns the path separator appropriate for the current operating system.

Function FindNamePos (): Integer;
Function FindExtPos (): Integer;

These functions find the index within This where the filename or extension portion of the path begins. If there is no filename or extension in the specified path, the index of the end of the string is returned. Examples:

This                      FindNamePos Returns   FindExtPos Returns
C:\DOS                    3                     6
\\File.Txt                2                     7
\Dir\.File                5                     10
\Dir.ext\Multi.dot.file   11                    21

Function ChangeExt (NewExt: String @);

This function adds, removes, or changes a file's extension. Examples:

Before                    New ext.  After
File.doc                  TXT       File.TXT
\Dir.ext\Multi.dot.file   bile      \Dir.ext\Multi.dot.bile
.hiddenfile               txt       .hiddenfile.txt
my.file.bmp                         my.file

Function MakeRelativePath (Path2: String @; StopAtRoot: Boolean(True)): String;

This function creates a relative path string from two absolute paths (This and Path2), such that when the return value is added to This, the equivalent to Path2 results. In other words, MakeRelativePath generates a relative path that will go from This to Path2.  If This or Path2 are relative paths, MakeRelativePath does not have enough information to generate the relative path and so simply returns Path2.  If This and Path2 are on different drives, or if one has a drive specification and the other does not, there is no way to generate a relative path that will go from one place to the other.  Therefore, Path2 is returned unchanged.  StopAtRoot, if true, tells the function not to generate a relative path when the two paths branch from two different root directories, or when Path2 is in the root directory, and thus returns Path2 unchanged.

Path1               Path2               StopAtRoot  Return Value
C:\Files\Base Dir   C:\Files            Irrelevant  ..
C:\A.B              C:\A.B\C.D\E.F      Irrelevant  C.D\E.F
\A\B\C              \A\Q\Z              Irrelevant  ..\..\Q\Z
C:\DOS\Run          P:\Electric\Fence   Irrelevant  P:\Electric\Fence
\\Primary\Dir\File  \\Secondary\A\B     True        \\Secondary\A\B
\\Primary\Dir\File  \\Secondary\A\B     False       ..\..\..\Secondary\A\B
\\a\b               \C\D                Irrelevant  \C\D
\bin\ls             \dev\hda1           True        \dev\hda1
\bin\ls             \dev\hda1           False       ..\..\dev\hda1
a\b                 \c\d                Irrelevant  \c\d
\a\b                c\d                 Irrelevant  c\d

Function ConvertPathSeparators (PathSeparator: Char('\0')): Boolean;

This function searches for path separator characters in the path and replaces them with the specified path separator.  If PathSeparator is '\0', the default path separator is used.  This function may test that PathSeparator is a valid path separator character through the use of an assertion.

Function IsPathValid (NoticeInvalidChars: Boolean (True)): Boolean;

This function determines whether a path is valid according to the guidelines listed at the beginning of this section.  NoticeInvalidChars specifies whether to search the path string for characters that are invalid for files in the current operating system.  The function returns True if the path is valid, False if it is not.

Under Windows, the following characters are invalid in a filename: < > | " * ? :