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

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. -

@@ -93,33 +90,14 @@ - Compares two file names to see whether they are equal. + CompareFileNames 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 (0) if files are equal, or when character values or file name lengths are not equal. + Returns zero if files are equal, or the index of differences, or the difference in length if filenames are not equal. @@ -136,7 +114,7 @@ - When True, file system links are searched to find the actual file(s) for the comparison. + ResolveLinks - if True, searches through links to find the actual file for comparison. @@ -160,7 +138,7 @@

- ExtractShortPathName + @@ -244,15 +222,8 @@ - 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. -

- + Expands the specified UTF-8-encoded UNC file name. + ExpandUNCFileName ExpandFileName @@ -318,117 +289,46 @@ - Checks whether the specified file name shares the path specified in Path. + FileIsInPath - checks that FileName refers to a file that exists within the given 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 the arguments share the same path information. + Returns True if a file named Filename exists within the given Path. - The name of the file examined in the routine. + The name of the file for checking. - The path name examined in the routine. + + The Path to be searched. + - 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. + FileIsInDirectory - checks whether a file with FileName exists within the given Directory.

-

- 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 and directory share the same paths. + Returns True if the file is in the directory. The name of the file to be checked. - The name of the directory compared to the file. + The name of the directory to be searched for the file. - Returns the file name without a file extension. + ExtractFileNameWithoutExt - returns just the name of the file without an extension. @@ -442,7 +342,7 @@ ShowMessage('File: ' + sFile + LineEnding + - Forms an absolute search path for files from values in BaseDirectory and SearchPath. + CreateAbsoluteSearchPath - concatenates BaseDirectory and SearchPath to form an absolute path to search for files.

@@ -497,21 +397,21 @@ ShowMessage('File: ' + sFile + LineEnding + - Gets the file mask representing all files in a file filter. + Gets the file mask representing all files suitable for showing in a file filter. - 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. + 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 '*'. - The All Files mask for the platform. + All files mask for the platform. - Returns the file extension (including the starting .) for an executable file on the platform. + GetExeExt - find the correct extension (including the starting .) for an executable file. @@ -742,55 +642,24 @@ ShowMessage('File: ' + sFile + LineEnding + - Finds the file name that most closely matches the specified file name. + FindDiskFilename - finds the file that best fits the supplied filename.

- 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. + FindDiskFilename finds the file that best fits the supplied filename. Searches for the filename case on disk. The file must exist.

- 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. + For example: If Filename='file' and there is only a 'File', then 'File' will be returned.

-

- 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 - - Resolved path and file name which is the case-insensitive match for the specified value. + Returns the best fitting filename from the disk (taking case into consideration). - The qualified path (optional) and file name to locate in the routine. + The name of the file for checking. @@ -1174,7 +1043,7 @@ AResult := FindDiskFileName(AFileName); - TMaskList +