From 55fe97bcdcd2328e05500b18d777734cccda0b75 Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 7 Mar 2022 17:23:34 +0000 Subject: [PATCH] Docs: LazUtils/fileutil. Updates topic content and links. --- docs/xml/lazutils/fileutil.xml | 191 +++++++++++++++++++++++++++------ 1 file changed, 161 insertions(+), 30 deletions(-) diff --git a/docs/xml/lazutils/fileutil.xml b/docs/xml/lazutils/fileutil.xml index 3dbd5ca217..d79a371744 100644 --- a/docs/xml/lazutils/fileutil.xml +++ b/docs/xml/lazutils/fileutil.xml @@ -20,6 +20,9 @@

This unit contains basic functions similar to those in the RTL, but use UTF-8 instead of the default system encoding. Please note that AnsiToUTF8 and UTF8ToAnsi need a widestring manager under Linux, BSD, and macOS. Normally these operating systems use UTF-8 as the system encoding so the WideStringManager is not needed.

+

+ fileutil.pas is part of the LazUtils package. +

@@ -90,14 +93,33 @@ - CompareFileNames compares two file names to see whether they are equal. + Compares two file names to see whether they are equal. - - + +

+ CompareFileNames is an Integer function used to compare the specified file names (and lengths). +

+

+ The Filename1 and Filename2 arguments are PChar types with pointers to the first character in each of the compared file names.The Len1 and Len2 arguments contain the length (or number of characters) for the pointers. If a length value is omitted, it implies the corresponding file name argument is empty. +

+

+ ResolveLinks indicates whether file system or symbolic links are resolved before comparing the file name arguments. When set to True, the ComparePhysicalFilenames routine is called to resolve the file system links to actual path and file names for the comparison. For platforms where NotLiteralFilenames is defined, the file names are copied to a temporary string before resolving the file names. +

+

+ Otherwise, the CompareFileNames routine (in LazFileUtils) is used to compare the file names and to get the return value. +

+

+ The return value is 0 (zero) when the file names contain (or resolve to) the same files on the local file system. It is set to the difference between the lengths in Len1 and Len2 when one of the arguments has been omitted. For platforms where NotLiteralFilenames is not defined, it contains the initial difference between the ordinal values in the file names. Otherwise, it is set to the value from CompareFilenames (in LazFIleUtils) or ComparePhysicalFilenames. +

+ + + + CompareFilenames + - Returns zero if files are equal, or the index of differences, or the difference in length if filenames are not equal. + Returns zero (0) if files are equal, or when character values or file name lengths are not equal. @@ -114,7 +136,7 @@ - ResolveLinks - if True, searches through links to find the actual file for comparison. + When True, file system links are searched to find the actual file(s) for the comparison. @@ -138,7 +160,7 @@

- + ExtractShortPathName @@ -222,8 +244,15 @@ - Expands the specified UTF-8-encoded UNC file name. - + Expands the specified UTF-8-encoded UNC file name to an absolute UNC file name. + +

+ ExpandUNCFileNameUTF8 is a String function used to expand the UNC file name in the FileName argument to an absolute UNC file name. It is the UTF-8-enabled equivalent of the ExpandUNCFileName routine from the FPC RTL. +

+

+ ExpandUNCFileNameUTF8 calls the ExpandUNCFileName routine in RTL to get the return value for the method. Drive letters which are mapped to shared disks are replaced with the UNC device name for the mapped drive. The return value is an empty string ('') if an error occurs in ExpandUNCFileName. +

+ ExpandUNCFileName ExpandFileName @@ -289,46 +318,117 @@ - FileIsInPath - checks that FileName refers to a file that exists within the given Path. + Checks whether the specified file name shares the path specified in Path. + +

+ FileIsInPath is a Boolean function used to determine whether the file in FileName is located in the specified Path. FileIsInPath calls the CleanAndExpandFilename and CleanAndExpandDirectory routines to resolve drive letters or relative path information included in the arguments. +

+

+ The return value is True when the resolved paths for the arguments contain the same values. FileIsInPath does not verify whether Path or FileName actually exist on the local file system. It compares the specified string values only. +

+

+ Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists on the local file system. +

+

+ Use FileExists or FileExistsUTF8 to determine whether a file exists on the local file system. +

+

+ Example: +

+ +// uses FileUtil; +// ... +// var +// sDir, sFile: String; +// bResult: Boolean; +// ... +// neither the file nor the directory exist on the file system +sDir := 'q:\bogus\path\'; +sFile := 'q:\bogus\path\..\path\filename.ext'; +bResult := FileIsInPath(sFile, sDir); + +ShowMessage('File: ' + sFile + LineEnding + + 'is in Path: ' + sDir + '?' + LineEnding + + 'FileIsInPath() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.'); + + + + + CleanAndExpandFilename + CleanAndExpandDirectory + CompareFileNames + - Returns True if a file named Filename exists within the given Path. + Returns True the arguments share the same path information. - The name of the file for checking. + The name of the file examined in the routine. - - The Path to be searched. - + The path name examined in the routine. - FileIsInDirectory - checks whether a file with FileName exists within the given Directory. + Checks whether the specified file name shares the path specified in Directory.

- FileIsInDirectory - checks whether a file with FileName exists within the given Directory. + FileIsInDirectory is a Boolean function used to determine whether the file in FileName is located in Directory. FileIsInDirectory calls the CleanAndExpandFilename and CleanAndExpandDirectory routines to resolve drive letters or relative path information included in the arguments.

+

+ The return value is True when the resolved paths for the arguments contain the same values. FileIsInDirectory does not verify whether Directory or FileName actually exist on the local file system. It compares the specified string values only. +

+

+ Use DirectoryExists or DirectoryExistsUTF8 to determine whether a path exists on the local file system. +

+

+ Use FileExists or FileExistsUTF8 to determine whether a file exists on the local file system. +

+

+ Example: +

+ +// uses FileUtil; +// ... +// var +// sDir, sFile: String; +// bResult: Boolean; +// ... +// neither the file nor the directory exist on the file system +sDir := 'q:\bogus\path\'; +sFile := 'q:\bogus\path\..\path\filename.ext'; +bResult := FileIsInDirectory(sFile, sDir); + +ShowMessage('File: ' + sFile + LineEnding + + 'is in Directory: ' + sDir + '?' + LineEnding + + 'FileIsInDirectory() result is: ' + bResult.ToString(TUseBoolStrs.True) + '.'); + + + + CleanAndExpandFilename + CleanAndExpandDirectory + CompareFileNames + - Returns True if the file is in the directory. + Returns True if the file and directory share the same paths. The name of the file to be checked. - The name of the directory to be searched for the file. + The name of the directory compared to the file. - ExtractFileNameWithoutExt - returns just the name of the file without an extension. + Returns the file name without a file extension. @@ -342,7 +442,7 @@ - CreateAbsoluteSearchPath - concatenates BaseDirectory and SearchPath to form an absolute path to search for files. + Forms an absolute search path for files from values in BaseDirectory and SearchPath.

@@ -397,21 +497,21 @@ - Gets the file mask representing all files suitable for showing in a file filter. + Gets the file mask representing all files in a file filter. - GetAllFilesMask returns a File Mask suitable for showing in a filter of a Open File Dialog. For Windows, '*.*' is returned; on other operating systems just '*'. + GetAllFilesMask returns a File Mask suitable for showing in a filter for a Open File Dialog. For Windows, '*.*' is returned; on other operating systems '*' is used. - All files mask for the platform. + The All Files mask for the platform. - GetExeExt - find the correct extension (including the starting .) for an executable file. + Returns the file extension (including the starting .) for an executable file on the platform. @@ -642,24 +742,55 @@ - FindDiskFilename - finds the file that best fits the supplied filename. + Finds the file name that most closely matches the specified file name.

- FindDiskFilename finds the file that best fits the supplied filename. Searches for the filename case on disk. The file must exist. + FindDiskFilename is a String function used to get the file name which most closely matches the value in the FileName argument. It does not use case-sensitivity when comparing file names - regardless of the platform. In addition, the file must exist on the local file system.

- For example: If Filename='file' and there is only a 'File', then 'File' will be returned. + FileName can include a fully-qualified path including a drive letter on Windows platforms. A drive letter in the value is always converted to uppercase. The path to the file is extracted and sanitized to resolve relative path references.

+

+ The file path is used to locate and compare all files in the directory by calling FindFirstUTF8 and FindNextUTF8. Each file entry is examined using CompareFilenamesIgnoreCase for a case-insensitive match for the specified file name. When a single match is found, its fully qualified path and file name are assigned as the return value. If more than one file is a match, the result is ambiguous and the resolved value for the original FileName argument is returned. +

+ + The "All Files" mask for the platform is used to find the files in the path. This can be time consuming when a folder has a large number of files. + +

+ Example: +

+ +// uses FileUtil; +// var AFileName, AResult: String; +// ... + +// Windows +AFileName := 'c:\WINDOWS\WIN.INI'; +AResult := FindDiskFileName(AFileName); +// AResult contains: 'C:\Windows\win.ini'; + +// UNIX-like platforms +AFileName := '/ETC/FONTS/FONTS.CONF'; +AResult := FindDiskFileName(AFileName); +// AResult contains: '/etc/fonts/fonts.conf'; + + + + + + ResolveDots + CompareFilenamesIgnoreCase + - Returns the best fitting filename from the disk (taking case into consideration). + Resolved path and file name which is the case-insensitive match for the specified value. - The name of the file for checking. + The qualified path (optional) and file name to locate in the routine. @@ -1043,7 +1174,7 @@ - + TMaskList