Implements UTF-8-enabled classes and routines.

lazutf8classes.pas implements UTF-8-enabled classes and routines, including: TFileStreamUTF8, TMemoryStreamUTF8, and TStringListUTF8. This file is part of the LazUtils package.

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.

TFileStream
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 following 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".

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

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

TStringListUTF8 has been marked as deprecated. Use TStringList instead.
TStringList
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.

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

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

TMemoryStreamUTF8 has been marked as deprecated. Use TMemoryStream instead.
TMemoryStream
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.

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

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

LoadStringsFromFileUTF8 has been marked as deprecated. Use the LoadFromFile method in TStrings instead.
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.

SaveStringsToFileUTF8 has been marked as deprecated. Use the SaveToFile method in TStrings instead.
String list to store in the specified file.
Name of the file where the content is stored.