View Issue Details

ID Project Category View Status Date Submitted Last Update 0038532 Lazarus Documentation public 2021-02-22 16:09 2021-02-24 10:30 Don Siders Juha Manninen normal minor N/A closed fixed 2.1 (SVN) 0038532: Documentation updates for LCL, LazUtils LazUtils modified files: * docs/xml/lazutils/lazfileutils.xml * docs/xml/lazutils/lazstringutils.xml See attached: docs-lazutils.diff LCL modified files: * docs/xml/lcl/imglist.xml * docs/xml/lcl/interfacebase.xml * docs/xml/lcl/valedit.xml See attached: docs-lcl.diff No tags attached. r64658 - Attached Files

Activities

 2021-02-22 16:09 reporter docs-lazutils.diff (53,680 bytes)    Index: docs/xml/lazutils/lazfileutils.xml =================================================================== --- docs/xml/lazutils/lazfileutils.xml (revision 64651) +++ docs/xml/lazutils/lazfileutils.xml (working copy) @@ -19,7 +19,6 @@ - Gets the relative sort order for the specified file names @@ -45,22 +44,18 @@ - Relative sort order for the specified file names - First file name for the comparison - Second file name for the comparison - Gets the relative sort order for case-insensitive file names @@ -86,23 +81,16 @@ - - Relative sort order for the file names - - First file name for the comparison - - Second file name for the comparison - Performs a sort order comparison for the specified file name and extension @@ -221,11 +209,25 @@ Ext can contain the '.' (Period) character used in the extension, but it is not required.

- CaseSensitive indicates if case-sensitivity is used when comparing parameter values. When set to True, the comparision is limited to values in the ASCII character set. StrLComp or StrLIComp is called to compare the values in Filename to the values in Ext. + CaseSensitive indicates if case-sensitivity is used when comparing parameter values. When set to True, the comparison is limited to values in the ASCII character set. StrLComp or StrLIComp is called to compare the values in Filename to the values in Ext.

- The return value is True when Filename uses the file extension in Ext. The return value is False when Filename is an empty string (''), does not include a '.' character that marks the start of the file extension, or does not use the file extension in Ext. + The return value is True when Filename uses the file extension in Ext. The return value is False for the following conditions:

+
+
• + Filename is an empty string (''). +
• +
• + Filename does not have a '.' character that marks the start of the file extension. +
• +
• + The extension in Filename has a different length than Ext. +
• +
• + Filename has a different file extension than Ext. +
• +
@@ -245,7 +247,7 @@
- Determies if the file name uses one of the specified file extensions + Determines if the file name uses one of the specified file extensions

FilenameExtIn is a Boolean function used to determine if the file name in the Filename parameter uses one of the file extension in Exts. @@ -361,9 +363,7 @@

On Windows, the FilenameIsWinAbsolute function is called in the implementation. FilenameIsWinAbsolute takes Device identifiers into consideration when examining the value in TheFilename. For example:

- - D:\db\employee.fdb - + D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.

@@ -370,18 +370,13 @@
- - True when the file name is not a relative path - - Path and file name to use in the function - Determines if the specified value is an absolute file path (not a relative one) @@ -393,9 +388,7 @@

On Windows, the FilenameIsWinAbsolute function is called in the implementation of FilenameIsAbsolute. FilenameIsWinAbsolute takes Device identifiers into consideration when examine the value in TheFilename. For example:

- - D:\db\employee.fdb - + D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.

@@ -402,18 +395,13 @@
- - True when the file name is not a relative path - - Path and file name to use in the function - Determines if the specified value is an absolute file path (not a relative one) @@ -428,13 +416,9 @@ - - True when the file name is not a relative path - - Path and file name to use in the function @@ -445,7 +429,7 @@

- ForceDirectory is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in DirectoryName prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path. + ForceDirectory is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in DirectoryName prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.

Each directory in the specified path is validated by calling DirPathExists. ForceDirectory calls CreateDirUTF8 if a directory does not exist, and may exit with a return value of False if directory creation is not successful. @@ -467,7 +451,6 @@ Path information for the operation - Examines the specified file to see if it is executable @@ -523,13 +506,10 @@ - - File name to examine - Determines if the specified file name is executable @@ -541,13 +521,9 @@ - - True if the file is executable on the platform or OS - - File name to examine @@ -601,7 +577,6 @@ File name examined in the routine - Indicates if the specified file name is readable @@ -616,18 +591,13 @@ FpAccess - - True when the specified file name is readable - - File name to examine - Indicates if the specified file name is writable @@ -634,23 +604,18 @@

- FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file. + FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.

- - True when the specified file name is writable - - File name to examine - Determines if the specified file contains plain text content @@ -657,7 +622,7 @@

- FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file. + FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.

FileIsText calls FileOpenUtf8 for the specified file name. The return value is False is the file handle contains feInvalidHandle. @@ -676,28 +641,21 @@ - - True when the file contains plain text content - - File name to examine in the function - - Indicates if the specified file was successfully opened and read -

- FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters. + FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.

Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols. @@ -705,34 +663,25 @@ - - False when the file name needs to trimmed - - File name to examine in the function - - PChar with the file name value - - Length of the file name - Removes leading and trailing spaces, and resolves special characters - TrimFilename is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//'). + TrimFilename is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//'). @@ -744,13 +693,9 @@ - - New value for the path and file name - - Path and file name for the operation @@ -772,7 +717,6 @@ File name examined in the routine - Removes whitespace and resolves special characters in the specified file name @@ -779,23 +723,18 @@

- CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string (''). + CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').

- - File name with whitespace removed and special characters resolved - - File name to examine in the function - Removes whitespace and resolves special characters in the specified path @@ -810,20 +749,15 @@
- - Path information after removing whitespace and resolving special characters - - Path information for the function - Cleans and resolves a file path to the specified base directory name @@ -838,23 +772,16 @@ - - Cleaned and resolved file path - - File name for the function - - Base directory name used for a relative file path - Cleans and resolves a relative path to a base directory @@ -872,23 +799,16 @@ - - Path information cleaned and resolved to the specified base directory - - Path information for the function - - Base directory used to resolve a relative path - Creates a relative path from BaseDirectory to Filename @@ -906,23 +826,15 @@ - - Relative path from the base directory for the file name - - File name for the operation - - Base directory for the relative path - - True if '.' (current directory symbol) is prepended to the relative path @@ -929,7 +841,6 @@ - Returns True if Filename exists in the specified Path @@ -953,18 +864,12 @@ - - True when the file exists in the specified path - - File name to locate - - Path used for the operation @@ -1012,7 +917,7 @@ - Shortened version of the specifed file name + Shortened version of the specified file name File name examined in the routine @@ -1091,7 +996,6 @@ File name examined in the function - Adds a trailing path delimiter when needed @@ -1103,18 +1007,13 @@ - - Path value with a trailing path delimiter - - Path value to examine - Removes a trailing path delimiter from the specified value @@ -1126,13 +1025,9 @@ - - Path information after removing the trailing path delimiter - - Path information for the function @@ -1392,7 +1287,6 @@ Length in characters for the search paths list - Indicates if the specified file name exists @@ -1405,17 +1299,14 @@ - True when the specified file name exists - UTF-8-encoded file name to locate in the local file system - Returns the last modification time for the file in FileDate format @@ -1433,18 +1324,13 @@ - - Last modification time for the file in FileDate format - - File name examined in the function - Determine if the specified path exists on the local file system @@ -1456,18 +1342,13 @@ - - True when the directory exists in the file system - - Directory name to locate in the file system - Expands the values in FileName and BaseDir to an absolute file name @@ -1486,23 +1367,16 @@ - - The file name with an absolute path - - File name examined in the function - - Base directory used to resolve a relative path - Starts searching for files matching the specified path value @@ -1523,28 +1397,19 @@ FindFirst - - Last error number encountered in the function - - Path and/or file name to locate - - File attributes to include in the search - - Search record for the first matching file - Locates another file matching the search criteria @@ -1562,18 +1427,13 @@ - - Last error number - - Search criteria for the function - Frees resources allocated to the specified search record @@ -1586,12 +1446,10 @@ - Search record to free in the procedure - Sets the last modification time for the file @@ -1609,23 +1467,16 @@ - - Last error number in the function - - File name to update in the function - - New value for the last modification time - Gets the value of file attributes for the specified file name @@ -1666,18 +1517,13 @@ - - File attribute value for the specified file name - - File name for the function - Sets the file attribute value for the specified file name @@ -1721,23 +1567,16 @@ - - Last error number from the function - - File name to update in the function - - File attribute value for the specified file name - Deletes the specified file name @@ -1755,18 +1594,13 @@ - - True if the specified file name is deleted - - File name to delete in the function - Renames a file to the specified value @@ -1785,23 +1619,16 @@ - - True if the file is successfully renamed to the new value - - Existing name for the file - - New name for the file - Searches for a file with the specified name in the list of directory paths @@ -1822,23 +1649,16 @@ - - Path and file name for the matching file, or an empty string - - File name to locate in the list of directory paths - - The delimited list of directory paths to search - Determines if the specified file is marked as read-only @@ -1850,18 +1670,13 @@ - - True when the file is marked as read-only - - File name to examine in the function - Gets the name for the current directory @@ -1881,13 +1696,10 @@ GetCurrentDir - - Name for the current directory - Sets the current directory to the specified name @@ -1916,18 +1728,13 @@ - - True if the current directory was successfully changed to the new value - - Directory name to use as the current directory - Creates a new directory with the specified name @@ -1947,18 +1754,13 @@ - - True if the new directory is successfully created - - Name for the new directory - Removes the directory with the specified name @@ -1981,18 +1783,13 @@ RemoveDir - - True when the directory is successfully removed - - Name of the directory to remove in the function - Creates the specified directories if they do not already exist @@ -1999,7 +1796,7 @@

- ForceDirectories is a Boolean function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function. + ForceDirectories is a Boolean function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.

ForceDirectories raises an EInOutError exception with the message in SCannotCreateEmptyDir when Dir contains an empty string (''). @@ -2020,15 +1817,11 @@ - - True when directories exist or are successfully created in the function - - Path information to examine the function @@ -2110,9 +1903,7 @@

For UNIX-like environments, the return value can contain information that indicates the permissions for the user, group, and owner of the file as returned from the FPStat routine. It also includes the file user and group IDs, file size, and modification timestamp. For example:

- -ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn - + ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn
l
@@ -2150,9 +1941,7 @@

For the Amiga platform, the content in the return value is derived using a TFileInfoBlock for a shared lock on the file. The return value can be an empty string if the file could not be locked using a shared lock on the file system. It can contain values like the following:

- - asperwd - + asperwd
a
File is an archived (unchanged) file
@@ -2172,9 +1961,7 @@

For Windows platforms, the return value contains only the modification date/time for the file using the format:

- -Modified: MM/DD/YYYY hh:mm - + Modified: MM/DD/YYYY hh:mm

The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.

@@ -2414,7 +2201,7 @@ If the directory does not exist and Create contains True, the ForceDirectoriesUTF8 routine is called to create any missing directories for the path. An EInOutError exception is raised if any missing directory in the path cannot be created.

- GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp). + GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp).

@@ -2504,9 +2291,7 @@

GetTempFileNameUTF8 signals the OnGetTempFile event handler (when assigned) to get the value used as the temporary file name. When OnGetTempFile has not been assigned, a string is constructed using the path information in Dir and a numeric suffix to make the file name unique. For example:

- -/usr/tmp/TMP0.tmp - + /usr/tmp/TMP0.tmp

GetTempFileNameUTF8 examines the files in the specified directory to determine if a file already exists which starts with the value in Prefix. If a file is located in the directory, a numeric suffix (starting at 0) is appended to the base file name in Prefix to build a temporary file name which does not already exist in the directory.

@@ -2532,11 +2317,11 @@

The implementation of IsUNCPath is platform- and/or OS-specific. For the Windows platform, IsUNCPath checks Path to see if it begins with the double backslash notation used for a UNC path. For example:

- - \\C:\directory\ - \\?\C:\directory\ - \\?\UNC\volume\directory\ - + +\\C:\directory\ +\\?\C:\directory\ +\\?\UNC\volume\directory\ +

For UNIX-like environments, as well as the Amiga platform, the return value is always False. UNC paths are not used on those platforms.

@@ -2562,17 +2347,17 @@

The return value contains information needed to access shared resources by their host and volume names, and contains one of the following formats:

- - \\server-name\shared-resource-path-name\ - \\mypc\nas-drive\ - \\?\c:\ - \\?\UNC\c:\ - + +\\server-name\shared-resource-path-name\ +\\mypc\nas-drive\ +\\?\c:\ +\\?\UNC\c:\ +

ExtractUNCVolume calls the IsUNCPath function to determine if the value in Path starts with the UNC naming delimiters. The return value is an empty string (''), and no additional actions are performed in the function, when Path does not use UNC notation.

- ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters '\\?\' or '\\?\UNC\' followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as '\\mypc\nas-drive\'. + ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters '\\?\' or '\\?\UNC\' followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as '\\mypc\nas-drive\'.

@@ -2595,10 +2380,10 @@

When FileName uses Universal Naming Convention (UNC), the return value will contain any server and share/volume information included in the parameter. For example:

- - \\server-name\share-name\ - \\?\C:\ - + +\\server-name\share-name\ +\\?\C:\ +

For UNIX-like environments (as well as WinCE), an initial path delimiter marks the root directory in the file system.

@@ -2608,9 +2393,7 @@

For the Windows platform, a drive designation up to and including the first path delimiter are used as the root directory. For example:

- -C:\ - + C:\ @@ -2739,7 +2522,6 @@ Command line option examined in the function - Specifies the event signalled for an invalid file state in the file cache @@ -2755,12 +2537,10 @@ - File name for the event notification - Implements the event handler for a file with an invalid file state @@ -2778,7 +2558,6 @@
- Signals the OnInvalidateFileStateCache event handler Index: docs/xml/lazutils/lazstringutils.xml =================================================================== --- docs/xml/lazutils/lazstringutils.xml (revision 64651) +++ docs/xml/lazutils/lazstringutils.xml (working copy) @@ -81,10 +81,10 @@ - A case-insensitive version of the Pos routine + A case-insensitive optimized version of the Pos routine

- PosI implements a case-insensitive version of the Pos routine found the RTL system unit. It only accepts String values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types. + PosI implements a case-insensitive optimized version of the Pos routine found the RTL system unit. It only accepts String values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.

It is also an alternative to the ContainsText routine in the RTL StrUtils unit, which has a very slow implementation. @@ -105,7 +105,7 @@ - Positionof the sub-string witin the searched value, or 0 when not found + Position of the sub-string within the searched value, or 0 when not found Value to locate in the searched value @@ -236,7 +236,9 @@ - Converts CR or LF characters in a string to the specified delimiter character + + Converts CR or LF characters in a string to the specified delimiter character + @@ -251,11 +253,13 @@ - + Deprecated Deprecated. Use LineBreaksToSystemLineBreaks instead. - + + + @@ -437,7 +441,9 @@

BeautifyLineXY is a String function used to combine the values in the Filename, Line, X and Y arguments into a formatted message. The message is in the form:

-LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s). + + LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s). +

Filename contains a file name used at the start of the formatted message.

@@ -634,19 +640,25 @@
- Stores the specified string as lines in a TStrings instance + Stores a multi-line string as seperate lines in a TStrings instance

- LF (#10) characters found in s control when a line of text is added in the TStrings instance. The end-of-line character is not stored in the TStrings instance. If no end-of-line characters are found in S, then a single line of text is added to the string list. + StringToStringList is a procedure used to convert the multi-line String in S to separate lines of text in a TStrings instance.

+

+ The LF (#10) character is used to mark the end of a line in S, and causes the preceeding text to be added to the string list in List. The LF character is not included in the value added to the string list. +

+

+ If no end-of-line characters are found in S, then a single line of text is added to the string list. +

- String with values extracted and stored in the method + String with values extracted and stored in the string list - TStrings instance where values are stored in the method + TStrings instance where values are stored in the routine @@ -723,24 +735,48 @@ - - - + Finds the next occurrence of a specific value in a delimited list + +

+ FindNextDelimitedItem is a String function used to find the next occurrence of a specific value in a delimited list of values. +

+

+ List is the list with the delimited values searched in the routine. +

+

+ Delimiter is the character used to separate the values in List. +

+

+ Position is a variable parameter with the character index in List where the find operation is started. Position is 1-based, like using indexed access to the values in a String. +

+

+ FindItem is the value to locate in List starting at the given position. +

+

+ FindNextDelimitedItem calls the GetNextDelimitedItem routine to get the individual delimited values in List. GetNextDelimitedItem updates the value in Position when an item is retrieved. The value in Position is set to Len(List)+1 if FindItem is not found in the routine. +

+

+ The return value is set to the value in FindItem if it is found in List. The return value is an empty string ('') if FindItem is not found in the List starting at the given position. +

+
+ + +
- + The value in FindItem when found, or an empty string - + List with delimited values examined in the routine - + Character used to separate values in the list - + Starting position for the values examined in the routine - + Item value to locate in List @@ -847,7 +883,7 @@ - Replaces (or appends) values the specified number of bytes at a give position + Replaces (or appends) the specified number of bytes at a given position

ReplaceSubstring is a procedure used to replace a portion of a string with the specified value. @@ -977,10 +1013,18 @@ IsValidIdent - - - - + + + + + + + + + + + + Defines the maximum length for shortened or "ellipsified" text @@ -996,6 +1040,5 @@ -  docs-lazutils.diff (53,680 bytes)    docs-lcl.diff (691,621 bytes) 2021-02-22 21:55 developer   ~0129108 There is: -LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s). + + LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s). + Many of the changes only add or remove newlines, like : xxx vs.   xxx or xxx vs.   xxx What triggers such a change? 2021-02-23 02:09 reporter   ~0129113 I'm using the Atom editor. It's a by-product of Atom reflowing text blocks. 2021-02-23 08:26 developer   ~0129114 Sounds like a bug in Atom editor if you didn't change any settings. It would be nice to have only real documentation changes in a patch. What do you say about this :  LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s) I guess an automatic doc generator marked such an error and then it stayed. I don't even know what generator was used. 2021-02-23 12:31 reporter   ~0129120 Let me look at this again. I'll submit new patches. 2021-02-23 15:50 reporter   ~0129122 > Sounds like a bug in Atom editor if you didn't change any settings. Yeah, it has bugs too. > It would be nice to have only real documentation changes in a patch. I have regenerated the diffs to avoid any gratuitous white space changes, The ones in interfacebase.xml are content changes. Micro-managing line endings and whitespace changes isn't much fun. And yes, I remove the useless XML comments for type visibility. They are always wrong when code gets refactored. New diffs are attached. > What do you say about this : > LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s) > I guess an automatic doc generator marked such an error and then it stayed. > I don't even know what generator was used. Its just an example of the output from the method. Perhaps it should have tagged using PRE. I changed it so it looks less like a real error message, and more like a contrived example. docs-lazutils-new.diff (49,158 bytes)    Index: docs/xml/lazutils/lazfileutils.xml =================================================================== --- docs/xml/lazutils/lazfileutils.xml (revision 64652) +++ docs/xml/lazutils/lazfileutils.xml (working copy) @@ -19,7 +19,6 @@ - Gets the relative sort order for the specified file names @@ -45,22 +44,18 @@ - Relative sort order for the specified file names - First file name for the comparison - Second file name for the comparison - Gets the relative sort order for case-insensitive file names @@ -86,23 +81,16 @@ - - Relative sort order for the file names - - First file name for the comparison - - Second file name for the comparison - Performs a sort order comparison for the specified file name and extension @@ -221,11 +209,25 @@ Ext can contain the '.' (Period) character used in the extension, but it is not required.

- CaseSensitive indicates if case-sensitivity is used when comparing parameter values. When set to True, the comparision is limited to values in the ASCII character set. StrLComp or StrLIComp is called to compare the values in Filename to the values in Ext. + CaseSensitive indicates if case-sensitivity is used when comparing parameter values. When set to True, the comparison is limited to values in the ASCII character set. StrLComp or StrLIComp is called to compare the values in Filename to the values in Ext.

- The return value is True when Filename uses the file extension in Ext. The return value is False when Filename is an empty string (''), does not include a '.' character that marks the start of the file extension, or does not use the file extension in Ext. + The return value is True when Filename uses the file extension in Ext. The return value is False for the following conditions:

+
+
• + Filename is an empty string (''). +
• +
• + Filename does not have a '.' character that marks the start of the file extension. +
• +
• + The extension in Filename has a different length than Ext. +
• +
• + Filename has a different file extension than Ext. +
• +
@@ -245,7 +247,7 @@
- Determies if the file name uses one of the specified file extensions + Determines if the file name uses one of the specified file extensions

FilenameExtIn is a Boolean function used to determine if the file name in the Filename parameter uses one of the file extension in Exts. @@ -362,7 +364,7 @@ On Windows, the FilenameIsWinAbsolute function is called in the implementation. FilenameIsWinAbsolute takes Device identifiers into consideration when examining the value in TheFilename. For example:

- D:\db\employee.fdb +D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment. @@ -370,18 +372,13 @@ - - True when the file name is not a relative path - - Path and file name to use in the function - Determines if the specified value is an absolute file path (not a relative one) @@ -394,7 +391,7 @@ On Windows, the FilenameIsWinAbsolute function is called in the implementation of FilenameIsAbsolute. FilenameIsWinAbsolute takes Device identifiers into consideration when examine the value in TheFilename. For example:

- D:\db\employee.fdb +D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment. @@ -402,18 +399,13 @@ - - True when the file name is not a relative path - - Path and file name to use in the function - Determines if the specified value is an absolute file path (not a relative one) @@ -428,13 +420,9 @@ - - True when the file name is not a relative path - - Path and file name to use in the function @@ -445,7 +433,7 @@

- ForceDirectory is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in DirectoryName prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path. + ForceDirectory is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in DirectoryName prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.

Each directory in the specified path is validated by calling DirPathExists. ForceDirectory calls CreateDirUTF8 if a directory does not exist, and may exit with a return value of False if directory creation is not successful. @@ -467,7 +455,6 @@ Path information for the operation - Examines the specified file to see if it is executable @@ -523,13 +510,10 @@

- - File name to examine - Determines if the specified file name is executable @@ -541,13 +525,9 @@ - - True if the file is executable on the platform or OS - - File name to examine @@ -601,7 +581,6 @@ File name examined in the routine - Indicates if the specified file name is readable @@ -616,18 +595,13 @@ FpAccess - - True when the specified file name is readable - - File name to examine - Indicates if the specified file name is writable @@ -634,23 +608,18 @@

- FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file. + FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.

- - True when the specified file name is writable - - File name to examine - Determines if the specified file contains plain text content @@ -657,7 +626,7 @@

- FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file. + FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.

FileIsText calls FileOpenUtf8 for the specified file name. The return value is False is the file handle contains feInvalidHandle. @@ -676,28 +645,21 @@ - - True when the file contains plain text content - - File name to examine in the function - - Indicates if the specified file was successfully opened and read -

- FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters. + FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.

Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols. @@ -705,34 +667,25 @@ - - False when the file name needs to trimmed - - File name to examine in the function - - PChar with the file name value - - Length of the file name - Removes leading and trailing spaces, and resolves special characters - TrimFilename is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//'). + TrimFilename is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//'). @@ -744,13 +697,9 @@ - - New value for the path and file name - - Path and file name for the operation @@ -772,7 +721,6 @@ File name examined in the routine - Removes whitespace and resolves special characters in the specified file name @@ -779,23 +727,18 @@

- CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string (''). + CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').

- - File name with whitespace removed and special characters resolved - - File name to examine in the function - Removes whitespace and resolves special characters in the specified path @@ -810,20 +753,15 @@ - - Path information after removing whitespace and resolving special characters - - Path information for the function - Cleans and resolves a file path to the specified base directory name @@ -838,23 +776,16 @@ - - Cleaned and resolved file path - - File name for the function - - Base directory name used for a relative file path - Cleans and resolves a relative path to a base directory @@ -872,23 +803,16 @@ - - Path information cleaned and resolved to the specified base directory - - Path information for the function - - Base directory used to resolve a relative path - Creates a relative path from BaseDirectory to Filename @@ -906,23 +830,15 @@ - - Relative path from the base directory for the file name - - File name for the operation - - Base directory for the relative path - - True if '.' (current directory symbol) is prepended to the relative path @@ -929,7 +845,6 @@ - Returns True if Filename exists in the specified Path @@ -953,18 +868,12 @@ - - True when the file exists in the specified path - - File name to locate - - Path used for the operation @@ -1012,7 +921,7 @@ - Shortened version of the specifed file name + Shortened version of the specified file name File name examined in the routine @@ -1091,7 +1000,6 @@ File name examined in the function - Adds a trailing path delimiter when needed @@ -1103,18 +1011,13 @@ - - Path value with a trailing path delimiter - - Path value to examine - Removes a trailing path delimiter from the specified value @@ -1126,13 +1029,9 @@ - - Path information after removing the trailing path delimiter - - Path information for the function @@ -1392,7 +1291,6 @@ Length in characters for the search paths list - Indicates if the specified file name exists @@ -1405,17 +1303,14 @@ - True when the specified file name exists - UTF-8-encoded file name to locate in the local file system - Returns the last modification time for the file in FileDate format @@ -1433,18 +1328,13 @@ - - Last modification time for the file in FileDate format - - File name examined in the function - Determine if the specified path exists on the local file system @@ -1456,18 +1346,13 @@ - - True when the directory exists in the file system - - Directory name to locate in the file system - Expands the values in FileName and BaseDir to an absolute file name @@ -1486,23 +1371,16 @@ - - The file name with an absolute path - - File name examined in the function - - Base directory used to resolve a relative path - Starts searching for files matching the specified path value @@ -1523,28 +1401,19 @@ FindFirst - - Last error number encountered in the function - - Path and/or file name to locate - - File attributes to include in the search - - Search record for the first matching file - Locates another file matching the search criteria @@ -1562,18 +1431,13 @@ - - Last error number - - Search criteria for the function - Frees resources allocated to the specified search record @@ -1586,12 +1450,10 @@ - Search record to free in the procedure - Sets the last modification time for the file @@ -1609,23 +1471,16 @@ - - Last error number in the function - - File name to update in the function - - New value for the last modification time - Gets the value of file attributes for the specified file name @@ -1666,18 +1521,13 @@ - - File attribute value for the specified file name - - File name for the function - Sets the file attribute value for the specified file name @@ -1721,23 +1571,16 @@ - - Last error number from the function - - File name to update in the function - - File attribute value for the specified file name - Deletes the specified file name @@ -1755,18 +1598,13 @@ - - True if the specified file name is deleted - - File name to delete in the function - Renames a file to the specified value @@ -1785,23 +1623,16 @@ - - True if the file is successfully renamed to the new value - - Existing name for the file - - New name for the file - Searches for a file with the specified name in the list of directory paths @@ -1822,23 +1653,16 @@ - - Path and file name for the matching file, or an empty string - - File name to locate in the list of directory paths - - The delimited list of directory paths to search - Determines if the specified file is marked as read-only @@ -1850,18 +1674,13 @@ - - True when the file is marked as read-only - - File name to examine in the function - Gets the name for the current directory @@ -1881,13 +1700,10 @@ GetCurrentDir - - Name for the current directory - Sets the current directory to the specified name @@ -1916,18 +1732,13 @@ - - True if the current directory was successfully changed to the new value - - Directory name to use as the current directory - Creates a new directory with the specified name @@ -1947,18 +1758,13 @@ - - True if the new directory is successfully created - - Name for the new directory - Removes the directory with the specified name @@ -1981,18 +1787,13 @@ RemoveDir - - True when the directory is successfully removed - - Name of the directory to remove in the function - Creates the specified directories if they do not already exist @@ -1999,7 +1800,7 @@

- ForceDirectories is a Boolean function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function. + ForceDirectories is a Boolean function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.

ForceDirectories raises an EInOutError exception with the message in SCannotCreateEmptyDir when Dir contains an empty string (''). @@ -2020,15 +1821,11 @@ - - True when directories exist or are successfully created in the function - - Path information to examine the function @@ -2151,7 +1948,7 @@ For the Amiga platform, the content in the return value is derived using a TFileInfoBlock for a shared lock on the file. The return value can be an empty string if the file could not be locked using a shared lock on the file system. It can contain values like the following:

- asperwd +asperwd
a
@@ -2172,9 +1969,7 @@

For Windows platforms, the return value contains only the modification date/time for the file using the format:

- -Modified: MM/DD/YYYY hh:mm - + Modified: MM/DD/YYYY hh:mm

The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.

@@ -2414,7 +2209,7 @@ If the directory does not exist and Create contains True, the ForceDirectoriesUTF8 routine is called to create any missing directories for the path. An EInOutError exception is raised if any missing directory in the path cannot be created.

- GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp). + GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp).

@@ -2572,7 +2367,7 @@ ExtractUNCVolume calls the IsUNCPath function to determine if the value in Path starts with the UNC naming delimiters. The return value is an empty string (''), and no additional actions are performed in the function, when Path does not use UNC notation.

- ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters '\\?\' or '\\?\UNC\' followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as '\\mypc\nas-drive\'. + ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters '\\?\' or '\\?\UNC\' followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as '\\mypc\nas-drive\'.

@@ -2739,7 +2534,6 @@ Command line option examined in the function - Specifies the event signalled for an invalid file state in the file cache @@ -2755,12 +2549,10 @@ - File name for the event notification - Implements the event handler for a file with an invalid file state @@ -2778,7 +2570,6 @@
- Signals the OnInvalidateFileStateCache event handler Index: docs/xml/lazutils/lazstringutils.xml =================================================================== --- docs/xml/lazutils/lazstringutils.xml (revision 64652) +++ docs/xml/lazutils/lazstringutils.xml (working copy) @@ -81,10 +81,10 @@ - A case-insensitive version of the Pos routine + A case-insensitive optimized version of the Pos routine

- PosI implements a case-insensitive version of the Pos routine found the RTL system unit. It only accepts String values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types. + PosI implements a case-insensitive optimized version of the Pos routine found the RTL system unit. It only accepts String values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.

It is also an alternative to the ContainsText routine in the RTL StrUtils unit, which has a very slow implementation. @@ -105,7 +105,7 @@ - Positionof the sub-string witin the searched value, or 0 when not found + Position of the sub-string within the searched value, or 0 when not found Value to locate in the searched value @@ -236,7 +236,9 @@ - Converts CR or LF characters in a string to the specified delimiter character + + Converts CR or LF characters in a string to the specified delimiter character + @@ -251,11 +253,13 @@ - + Deprecated Deprecated. Use LineBreaksToSystemLineBreaks instead. - + + + @@ -437,7 +441,7 @@

BeautifyLineXY is a String function used to combine the values in the Filename, Line, X and Y arguments into a formatted message. The message is in the form:

-LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s). +examplefile.pas (123, 1) The error message goes here.

Filename contains a file name used at the start of the formatted message.

@@ -634,19 +638,25 @@
- Stores the specified string as lines in a TStrings instance + Stores a multi-line string as seperate lines in a TStrings instance

- LF (#10) characters found in s control when a line of text is added in the TStrings instance. The end-of-line character is not stored in the TStrings instance. If no end-of-line characters are found in S, then a single line of text is added to the string list. + StringToStringList is a procedure used to convert the multi-line String in S to separate lines of text in a TStrings instance.

+

+ The LF (#10) character is used to mark the end of a line in S, and causes the preceeding text to be added to the string list in List. The LF character is not included in the value added to the string list. +

+

+ If no end-of-line characters are found in S, then a single line of text is added to the string list. +

- String with values extracted and stored in the method + String with values extracted and stored in the string list - TStrings instance where values are stored in the method + TStrings instance where values are stored in the routine @@ -723,24 +733,48 @@ - - - + Finds the next occurrence of a specific value in a delimited list + +

+ FindNextDelimitedItem is a String function used to find the next occurrence of a specific value in a delimited list of values. +

+

+ List is the list with the delimited values searched in the routine. +

+

+ Delimiter is the character used to separate the values in List. +

+

+ Position is a variable parameter with the character index in List where the find operation is started. Position is 1-based, like using indexed access to the values in a String. +

+

+ FindItem is the value to locate in List starting at the given position. +

+

+ FindNextDelimitedItem calls the GetNextDelimitedItem routine to get the individual delimited values in List. GetNextDelimitedItem updates the value in Position when an item is retrieved. The value in Position is set to Len(List)+1 if FindItem is not found in the routine. +

+

+ The return value is set to the value in FindItem if it is found in List. The return value is an empty string ('') if FindItem is not found in the List starting at the given position. +

+
+ + +
- + The value in FindItem when found, or an empty string - + List with delimited values examined in the routine - + Character used to separate values in the list - + Starting position for the values examined in the routine - + Item value to locate in List @@ -847,7 +881,7 @@ - Replaces (or appends) values the specified number of bytes at a give position + Replaces (or appends) the specified number of bytes at a given position

ReplaceSubstring is a procedure used to replace a portion of a string with the specified value.  docs-lazutils-new.diff (49,158 bytes)    docs-lcl-new.diff (622,677 bytes) 2021-02-24 09:35 developer   ~0129136 Applied, thanks. Ok, I understand the example output line now. :)

Issue History

2021-02-22 16:09 Don Siders New Issue
2021-02-22 16:09 Don Siders File Added: docs-lazutils.diff
2021-02-22 16:09 Don Siders File Added: docs-lcl.diff
2021-02-22 21:47 Juha Manninen Assigned To => Juha Manninen
2021-02-22 21:47 Juha Manninen Status new => assigned
2021-02-22 21:55 Juha Manninen Note Added: 0129108
2021-02-23 02:09 Don Siders Note Added: 0129113
2021-02-23 08:26 Juha Manninen Note Added: 0129114
2021-02-23 12:31 Don Siders Note Added: 0129120
2021-02-23 15:50 Don Siders Note Added: 0129122
2021-02-23 15:50 Don Siders File Added: docs-lazutils-new.diff
2021-02-23 15:50 Don Siders File Added: docs-lcl-new.diff
2021-02-24 09:35 Juha Manninen Status assigned => resolved
2021-02-24 09:35 Juha Manninen Resolution open => fixed
2021-02-24 09:35 Juha Manninen Fixed in Revision => r64658
2021-02-24 09:35 Juha Manninen LazTarget => -
2021-02-24 09:35 Juha Manninen Note Added: 0129136
2021-02-24 10:30 Don Siders Status resolved => closed