From eaa9b98eee405feb82f8393d20013afe20aac115 Mon Sep 17 00:00:00 2001 From: mattias Date: Tue, 29 Jan 2019 19:13:32 +0000 Subject: [PATCH] docs: documentation of lazutf8classes, issue #34968, from Don Siders git-svn-id: branches/fixes_2_0@60243 - --- .gitattributes | 1 - docs/xml/lazutils/lazutf8classes.xml | 456 +++++++++++++++++++-------- docs/xml/lcl/lazutf8classes.xml | 154 --------- 3 files changed, 326 insertions(+), 285 deletions(-) delete mode 100644 docs/xml/lcl/lazutf8classes.xml diff --git a/.gitattributes b/.gitattributes index ff7aa00e1b..074e7861db 100644 --- a/.gitattributes +++ b/.gitattributes @@ -5952,7 +5952,6 @@ docs/xml/lcl/lazfreetypeintfdrawer.xml svneol=native#text/plain docs/xml/lcl/lazhelphtml.xml svneol=native#text/plain docs/xml/lcl/lazhelpintf.xml svneol=native#text/plain docs/xml/lcl/lazregions.xml svneol=native#text/plain -docs/xml/lcl/lazutf8classes.xml svneol=native#text/plain docs/xml/lcl/lcl.xml svneol=LF#text/plain eol=lf docs/xml/lcl/lclbase.xml svneol=native#text/plain docs/xml/lcl/lclclasses.xml svneol=LF#text/xml eol=lf diff --git a/docs/xml/lazutils/lazutf8classes.xml b/docs/xml/lazutils/lazutf8classes.xml index 1ce6ef2cf6..e445b50066 100644 --- a/docs/xml/lazutils/lazutf8classes.xml +++ b/docs/xml/lazutils/lazutf8classes.xml @@ -1,154 +1,350 @@ - + - + + + + Implements UTF-8-enabled classes and routines + + +

+ lazutf8classes implements UTF-8-enabled classes and routines, including: TFileStreamUTF8, TMemoryStreamUTF8, and TStringListUTF8. +

+ + lazutf8classes has an implementation dependency on the lazfileutils unit. + + - - - - + + + + Implements a file stream with support for UTF-8-encoded file names + + +

+ TFileStreamUTF8 is a TFileStream descendant which implements a file stream with support for UTF-8-encoded content file names. TFileStreamUTF8 provides constructors which create or open the file for the stream using UTF-8 encoding. +

+ + + - - - - - - - - - - + + - - - - - - - - + + + + Constructor for the class instance + + +

+ Create is the overloaded constructor for the class instance. +

+

+ AFilename contains the name for the file (created using FileCreateUTF8 or opened using FileOpenUTF8). +

+

+ Mode is the File Mode for the specified file and contains one of the follwing values: +

+
+
fmCreate
+
Creates a new file if needed.
+
fmOpenRead
+
Opens a file with read-only access.
+
fmOpenWrite
+
Opens a file with write-only access.
+
fmOpenReadWrite
+
Opens a file with read-write access.
+
+

+ All file mode constants (except fmCreate) can be OR-ed with the following to specify how sharing and file locking is handled: +

+
+
fmShareCompat
+
Open file in DOS share-compatibility mode.
+
fmShareExclusive
+
Lock file for exclusive use.
+
fmShareDenyWrite
+
Lock file so other processes can only read.
+
fmShareDenyRead
+
Lock file so other processes cannot read.
+
fmShareDenyNone
+
Do not lock file.
+
+

+ Please note that sharing is advisory on Unix-like platforms. +

+

+ Rights is the file rights for the specified file. The default value is 438 (Decimal) or &666 (Octal) and indicates that the owner, group, and others can read and/or write to the file. The value in Rights is ignored on the Windows platform. +

+

+ Create instantiates a THandleStream (owned by the current class instance) which uses the valid file handle. +

+ + Please note that Create can raise an exception if the file handle from FileCreateUTF8 or FileOpenUTF8 is invalid (contains feInvalidHandle). + + + +
+
EFCreateError
+
+ Raised when Mode contains fmCreate and the file handle is invalid; raised with the message "Unable to create file "%s". +
+
EFOpenError
+
+ Raised when the file handle is invalid when opening the file; raised with the message "Unable to open file "%s". +
+
+ + + - - - - - - - - - - + + + File name where stream content is read or written + - - - - + + + File mode for the file + - - - - + + + File rights for the file (ignored on Windows) + - - - - + + + + Name of the file where stream content is read or written + + + FIleName is a read-only String property that contains the name of the file where stream content is read or written. FileName can contain UTF-8-encoded characters. + + + - - - - - - - - - - + + + + Implements a UTF-8-enabled string list + + +

+ TStringListUTF8 is a TStringList descendant that implements a string list that can store data which uses UTF-8 encoding. TStringListUTF8 provides an overridden method used to sort items in the list using UTF-8 string comparisons. TStringListUTF8 can also load and save files which have UTF-8-encoded file names. +

+ + + - - - - - - - - + + + + Compares UTF-8-encoded lines in the string list + + +

+ DoCompareText is PtrInt function used to compare the specified values using UTF-8 string comparison routines. DoCompareText uses the value in CaseSensitive to determine the routine used for the comparison. When CaseSensitive contains True, the UTF8CompareStr is used. Otherwise, UTF8CompareText is called. The return value contains the result from the routine. +

+ + + - - - - - - - - - - + + + Value from the string comparison + - - - - - - - - - - + + + First string value for the comparison + - - - - + + + Second string value for the comparison + - - - - + + + + Loads the content in the string list from the specified file + + +

+ LoadFromFile is a procedure used to load the content in the string list from the specified file name. FileName can contain UTF-8-encoded characters. LoadFromFile uses a TFileStreamUTF8 instance to open and read the contents of FileName, and calls LoadFromStream to store the values in the string list. +

+ + + - - - - + + + File name with content for the string list + - - - - - - - - - - + + + + Saves the content in the string to the specified file name + + +

+ SaveToFile is a procedure used to save the content in the string list to the specified file name. FileName can contain UTF-8-encoded characters. SaveToFile uses a TFileStreamUTF8 instance to create the file specified in FIleName, and calls the SaveToStream method to store values from the string list. +

+ + + - - - - + + + File name where content in the string list is stored + - - - - - - - - - - + + + + Implements a memory stream which supports file names with UTF-8 encoding + + +

+ TMemoryStreamUTF8 is a TMemoryStream descendant that stores its data in memory. TMemoryStreamUTF8 extends the ancestor to include methods used to load and save its memory content using files names that may contain UTF-8-encoded characters. +

+ + + - - - - + + + + Loads the content in the stream from the specified file + + +

+ LoadFromFile is a procedure used to load the content for the stream from the specified file name. LoadFromFile uses a TFileStreamUTF8 instance to open the file specified in FileName, and calls LoadFromStream to store the contents in the memory stream. +

+ + + - + + + File name where where content for the stream is stored + - + + + + Stores the content in the stream to the specified file + + +

+ SaveToFile is a procedure used to store the content in the memory stream to the specified file name. SaveToFile uses a TFileStreamUTF8 instance to create the file in FileName, and calls SaveToStream to write the content in the memory stream. +

+ + + + + + + File name where content in the stream is stored + + + + + + Loads the content for a TStringList from the specified file name + + +

+ LoadStringsFromFileUTF8 is a procedure used to load the content for a string list from the specified file name. List is the TStrings decendant where the content from FileName is stored. FIleName can contain UTF-8-encoded characters. LoadStringsFromFileUTF8 creates an internal TStringListUTF8 instance (when needed) that is used to load the content in FileName, and calls the Assign method in List to store the values. +

+ + + + + + + TStrings descendant where the content is stored + + + + + File name with the content to load in the string list + + + + + + Saves the content in the TStringList to the specified file name + + +

+ SaveStringsToFileUTF8 is a procedure used to save the content in the List to the specified file name. List is a TStrings desccendant with the content to store in the specified file name. FileName can contaIn UTF-8-encoded character values. SaveStringsToFileUTF8 uses a TStringListUTF8 (when needed) to store the content in the string list to the specified FileName. +

+ + + + + + + String list to store in the specified file + + + + + Name of the file where the content is stored + + + + + + Performs lowercase comparison of values in a string list + + +

+ CompareStringListItemsUTF8LowerCase is an Integer function used to perform lowercase comparison of string values in a string list. List is the TStrings descendant with values for the comparison. Index1 and Index2 specify the ordinal positions in List for strings used in the comparison. +

+

+ CompareStringListItemsUTF8LowerCase converts the string values to lowercase using UTF8LowerCase, and calls the CompareStr function to perform the comparison. The return vaue is in the following ranges: +

+
+
<0
+
String at Index1 comes before String at Index2
+
0
+
Strings have the same value
+
>0
+
String at Index1 comes after String at Index2
+
+ + + + + + + Relative order for the compared values + + + + + String list with values for the comparison + + + + + + Ordinal position for the first string value + + + + + Ordinal position for the second string value + + + + + + diff --git a/docs/xml/lcl/lazutf8classes.xml b/docs/xml/lcl/lazutf8classes.xml deleted file mode 100644 index 1446964c63..0000000000 --- a/docs/xml/lcl/lazutf8classes.xml +++ /dev/null @@ -1,154 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -