LICENSE
The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at "http://www.mozilla.org/MPL/"
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is "WideStringUtils.pas".
The Initial Developer of the Original Code is Dieter Köhler (Heidelberg, Germany, "http://www.philo.de/"). Portions created by the Initial Developer are Copyright (C) 2003-2007 Dieter Köhler. All Rights Reserved.
Alternatively, the contents of this file may be used under the terms of the GNU General Public License Version 2 or later (the "GPL"), in which case the provisions of the GPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the GPL, and not to allow others to use your version of this file under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under the terms of any one of the MPL or the GPL.
Thanks to Karl Waclawek for providing the TUtilsWideStringStream class.
The WideString Utilities Library contains helper functions for WideString. The latest version of this software is available at <http://www.philo.de/xml/>.
The WideString Utilities Library does not contain any components to be registered. So using it from inside your own projects is very simple: Add "WideStringUtils" to the uses clause of your unit and make sure that the path to the location of the WideStringUtils.pas file is included in Delphi's list of library paths. To include it go to the Library section of Delphi's Environment Options dialog (see the menu item: "Tools/Environment Options ...").
CompareWideStr compares S1 to S2, with case-sensitivity. The return value is less than 0 if S1 is less than S2, 0 if S1 equals S2, or greater than 0 if S1 is greater than S2. The compare operation is based on the 16-bit ordinal value of each character and is not affected by the current locale. Also UTF-16 surrogates are not recognized as such, but treated according to the 16-bit ordinal value of their constituents ($D800..$DFFF), i.e. they are arranged before $E000.
Indicates whether one wideString is a (case-sensitive) suffix of another. The return value is True if S ends with SubString, otherwise False is returned. The comparison is based on the 16-bit ordinal value of each character and is not affected by the current locale.
Indicates whether one wideString is a (case-sensitive) prefix of another. The return value is True if S starts with SubString, otherwise False is returned. The comparison is based on the 16-bit ordinal value of each character and is not affected by the current locale.
Returns S with occurrences of characters in Pattern_1 replaced by the character at the corresponding position in Pattern_2. For example translateWideString('bar', 'abc', 'ABC') returns the wideString 'BAr'. If there is a character in Pattern_1 with no character at a corresponding position in Pattern_2 (because Pattern_1 is longer than Pattern_2), then occurrences of that character in S are removed. For example translateWideString('--aaa--', 'abc-', "ABC") returns 'AAA'. If a character occurs more than once in Pattern_1, then the first occurrence determines the replacement character. If Pattern_2 is longer than Pattern_1, then excess characters are ignored.
Returns the specified WideString S with leading and trailing space characters (#$20) removed.
TUtilsCustomWideStr can be used to improve the performance of concating WideStrings. In Delphi, concating WideStrings may lead to performance critical memory allocation ans string copying. Consider the following example:
var S: WideString; I: Intger; begin for I := 0 to 99 do S := S + '.'; end;
Each time a new point is added to S, new memory sufficient for the expanted WideString is allocated, the bytes from the previous memory area are copied to the freshly allocated memory, the point character is added, and finally the previous memory used for S is deallocated. So the above loop triggers 100 of these allocation, copying and deallocation processes.
TUtilsCustomWideStr is a class that allows an easy to handle solution to this problem: The object uses an internal buffer that requires only occasionally to allocated new memory: It starts with a memory buffer of 64 byte; each time the memory buffer is full, it is automatically expanded by 25 %.
Parameters: - CodePoint The code point (Unicode scalar value) of the character to be added.
Parameters: - C The WideChar to be added.
Parameters: - S The WideString to be added.
Parameters: - S The WideString to be tested. Return value: 'True' if the custom wide string end with the specified WideString, 'false' if not.
Parameters: - S The WideString to be tested for equivalence. Return value: 'True' if the custom wide string is equivalent to the specified WideString, 'false' if not.
Parameters: - S The WideString to be tested. Return value: 'True' if the custom wide string startswith the specified WideString, 'false' if not.
Return value: The content of the custom wide string as a UTF-16 encoded WideString
TUtilsWideStringItem = record FString: WideString; FObject: TObject; end;
TUtilsWideStringItem is a record internally used in the TUtilsWideStringList class to store WideString-Object pairs.
TUtilsWideStringItemList defines a list of TUtilsWideStringItem records.
PUtilsWideStringItemList defines a pointer to a TUtilsWideStringItemList array. It is internally used in TUtilsWideStringList.
Under Delphi for Win32 TUtilsWideStringList is a WideString equivalent for the Delphi VCL TStringList class. In particular TUtilsWideStringList defines the following public methods and properties equivalent to TStringList (not all TStringList methods have an equivalent in TUtilsWideStringList):
destructor Destroy; override; function Add(S: WideString): Integer; virtual; function AddObject(S: WideString; AObject: TObject): Integer; virtual; procedure AddWideStrings(Strings: TUtilsWideStringList); virtual; procedure Append(S: WideString); virtual; procedure Assign(Source: TPersistent); override; procedure BeginUpdate; virtual; procedure Clear; virtual; procedure Delete(Index: Integer); virtual; procedure EndUpdate; virtual; procedure Exchange(Index1, Index2: Integer); virtual; function Find(const S: WideString; var Index: Integer): Boolean; virtual; function IndexOf(const S: WideString): Integer; virtual; procedure Insert(Index: Integer; const S: WideString); virtual; procedure InsertObject(Index: Integer; const S: WideString; AObject: TObject); virtual; procedure Sort; virtual; property Capacity: Integer read GetCapacity write SetCapacity; property Count: Integer read GetCount; property Duplicates: TDuplicates read FDuplicates write FDuplicates default dupIgnore; property Objects[Index: Integer]: TObject read GetObject write PutObject; property Sorted: Boolean read FSorted write SetSorted default False; property WideStrings[Index: Integer]: WideString read Get write Put; default; property OnChange: TNotifyEvent read FOnChange write FOnChange; property OnChanging: TNotifyEvent read FOnChanging write FOnChanging;
The following public methods of TUtilsWideStringList have no equivalent in TStringList:
Parameters: - S The WideString whose position is to be determined. Return value: The zero-based index of the last occurence of S in the list, or -1 if S does not occure in the list.
Under Delphi for .NET the string type maps to the WideString class. Thus TUtilsWideStringList is inherited from the TStringList which it extents with the following methods and properties:
procedure AddWideStrings(Strings: TUtilsWideStringList); virtual; function IndexOfLast(const S: WideString): Integer; virtual; property WideStrings[Index: Integer]: WideString read Get write Put; default;
A TUtilsNameValueList is used to store name-value pairs of WideStrings.
Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. Return value: The index of the newly added name-value pair in the list.
Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. - AObject The object to be associated. Return value: The index of the newly added name-value pair in the list.
Parameters: - Nvl The TUtilsNameValueList object that contains the group of name-value pairs to be added.
Parameters: - Source The object whose values shall be assigned.
Parameters: - Item The list index of the name-value pair to be deleted.
Parameters: - Index1 The list index of the first name-value pair. - Index2 The list index of the second name-value pair.
Parameters: - Name The name part of the name-value pair. - Value The value part of the name-value pair. Return value: The zero-based index of the specified name-value pair in the list, or -1 if no such pair exists.
Parameters: - Name The name part of the name-value pair. - Value The value part of the name-value pair. Return value: The zero-based index of the last occurrence of the specified name-value pair in the list, or -1 if no such pair exists.
Parameters: - Name The name part of the name-value pair. Return value: The zero-based index of the last occurrence of the name-value pair in the list with the specified name, or -1 if no such pair exists.
Parameters: - Name The name part of the name-value pair. Return value: The index of the first name-value pair in the list with the specified name, or -1 if no such pair exists.
Parameters: - Index The position where the name-value pair is to be inserted. - Name The name part of the name-value pair to be inserted. - Value The value part of the name-value pair to be inserted.
Parameters: - Name The name part of the name-value pair. - Value The value part of the name-value pair. Return Parameter: - Index The index of the specified name-value pair in the list, or -1 if no such pair exists. Return value: 'True' if the specified name-value pair exists in the list, 'False' otherwise.
Parameters: - Name The name part of the name-value pair. Return Parameter: - Index The index of the first name-value pair in the list with the specified name, or -1 if no such pair exists. Return value: 'True' if a name-value with the specified name was fount in the list, 'False' otherwise.
A TUtilsNameValueTree object is used to store name-value pairs of WideStrings together with an optional reference to a subtree which must also be of type TUtilsNameValueTree.
The TUtilsNameValueTree object owns the TUtilsNameValueTree subtrees added to it. When the TUtilsNameValueTree is cleared or destroyed, all subtrees are recursively destroyed, too.
The number of wideString pairs for which memory is reserved. This is equivalent to the Delphi VCL property 'TStringList.Capacity'.
The TUtilsNameValueTree associated with the wideString pair on the indexth position in the list.
Specifies whether name-value pairs with duplicate names can be added to sorted lists. The value of Duplicates should be one of the following: dupIgnore Ignore attempts to add duplicate names to the list. dupError Raise an EStringListError exception when an attempt is made to add duplicate names to the sorted list. dupAccept Permit duplicate wideStrings in the sorted list. Set Duplicates before adding any name-value pairs to the list. Setting Duplicates to dupIgnore or dupError does nothing about duplicate name-value pairs that are already in the list. Note: Duplicates does nothing if the list is not sorted.
The number of wideStrings pairs in the list. This is equivalent to the Delphi VCL property 'TStringList.count'.
The 'name' part of the wideString pair on the indexth position in the list.
An objects that is associated with the name-value pair on the indexth position in the list. Note: The list does not own the objects in the Objects array. Objects added to the Objects array still exist even if the list is destroyed. They must be explicitly destroyed by the application.
The parent tree if this TUtilsNameValueTree is the subtree of another TUtilsNameValueTree, or nil otherwise.
Specifies whether the name-value pairs in the list should be automatically sorted by name. Set Sorted to 'True' to cause the name-value pairs in the list to be automatically sorted by name in ascending order. Set Sorted to 'False' to allow name-value pairs to remain where they are inserted. When Sorted is 'False', the name-value pairs in the list can be put in ascending order at any time by calling the Sort() method. When Sorted is 'True', do not use Insert() to add name-value pairs to the list. Instead, use Add(), which will insert the new name-value pairs in the appropriate position. When Sorted is 'False', use Insert() to add wideStrings to an arbitrary position in the list, or Add() to add name-value pairs to the end of the list.
The 'value' part of the wideString pair on the indexth position in the list.
Creates a new TUtilsNameValueTree object.
Destroys a TUtilsNameValueTree object and all its subtrees recursively. Do not call 'destroy' directly, but use 'free', inherited from TObject, instead. Free tests whether the TUtilsNameValueTree has not already been freed, and only then calls 'destroy'. When the TUtilsNameValueTree object is a subtree in another TUtilsNameValueTree object it is automatically removed from its parent tree before it is destroyed. Hint: Since this involves a list lookup for the index of the subtree in the context of its parent tree, it is usually faster to remove it from the its parent tree before destroying it if its index is known. For example MyNameValueTree.Children[5].Free; should be replaced by MySubTree:= MyNameValueTree.ReplaceChild[5,nil]; if Assigned(MySubTree) then MySubTree.Free;
Adds a name-value pair to the list. Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. Return value: The index of the newly added name-value pair in the list.
Adds a name-value pair to the list, and attaches a TUtilsNameValueTree object to the pair. Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. - Child The TUtilsNameValueTree object to attach to this name-value pair. Return value: The index of the newly added name-value pair and child TUtilsNameValueTree object in the list. Exceptions: - EStringListError This Delphi VCL exception is raised if this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object or the specified TUtilsNameValueTree object is in use elsewhere.
Adds a name-value pair to the list, attaches a TUtilsNameValueTree object to the pair, and associates an object with the pair. Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. - Child The TUtilsNameValueTree object to attach to this name-value pair. - AObject The object to associate with this name-value pair. Return value: The index of the newly added name-value pair and child TUtilsNameValueTree object and attached object in the list. Exceptions: - EStringListError This Delphi VCL exception is raised if this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object or the specified TUtilsNameValueTree object is in use elsewhere.
Adds a name-value pair and an associated object to the list. Parameters: - Name The 'name' part of the name-value pair to be added. - Value The 'value' part of the name-value pair to be added. - AObject The object to be associated. Return value: The index of the newly added name-value pair in the list.
Adds a group of name-value pairs to the list. Call AddNameValueList() to add the name-value pairs from a TUtilsNameValueList object to the list. If there are objects associated with the name-value pairs, references to the associated objects will be added as well. Parameters: - Nvl The TUtilsNameValueList object that contains the group of name-value pairs to be added.
Sets the name-value pairs in the list, and possibly associated objects, from a source object. Use Assign() to set the value of the TUtilsNameValueTree object from another object. If Source is of type TUtilsNameValueTree, the list is set to the list of the source TUtilsNameValueTree object and child TUtilsNameValueTree objects are recursively copyed too, and if there are objects associated with the name-value pairs, references to the associated objects will be copied as well. If Source is any other type of object, Assign() calls the inherited method, which will copy the list from any object that specifies how to copy to a TUtilsNameValueTree object in its AssignTo() method. Parameters: - Source The object whose values shall be assigned.
Deletes all name-value pair from the list, and destroys any child TUtilsNameValueTree objects.
Deletes a name-value pair from the list. If a child TUtilsNameValueTree object is associated with this pair it is destroyed. Parameters: - Item The list index of the name-value pair to be deleted.
Exchanges the position of the two specified name-value pair in the list. Parameters: - Index1 The list index of the first name-value pair. - Index2 The list index of the second name-value pair.
Returns the position of the first name-value pair in the list with the specified name and value. Parameters: - Name The 'name' part of the name-value pair. - Value The 'value' part of the name-value pair. Return value: The index of the specified name-value pair in the list, or -1 if non such pair exists.
Returns the position of the first name-value pair in the list with the specified TUtilsNameValueTree object associated. Parameters: - Child The associated TUtilsNameValueTree object. Return value: The index of the specified name-value pair in the list, or -1 if non such pair exists.
Returns the position of the first name-value pair in the list with the specified 'name' part. Parameters: - Name The 'name' part of the name-value pair. Return value: The index of the first name-value pair in the list with the specified name, or -1 if non such pair exists.
Inserts a name-value pair at the specified position in the list. Parameters: - Index The position where the name-value pair is to be inserted. - Name The 'name' part of the name-value pair to be inserted. - Value The 'value' part of the name-value pair to be inserted.
Inserts a name-value pair at the specified position in the list, and associates a TUtilsNameValueTree object with the pair. Parameters: - Index The position where the name-value pair is to be inserted. - Name The 'name' part of the name-value pair to be inserted. - Value The 'value' part of the name-value pair to be inserted. - Child The TUtilsNameValueTree object to associate with the name-value pair. Exceptions: - EStringListError This Delphi VCL exception is raised if this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object or the specified TUtilsNameValueTree object is in use elsewhere.
Tests whether this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object. Parameters: - Nvtree The TUtilsNameValueTree object to be tested for being a direct or indirect parent object. Return value: 'True' if this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object, 'false' otherwise.
Replaces the associated TUtilsNameValueTree object at the specified position in the list with a new TUtilsNameValueTree object. Parameters: - Index The position where the associated TUtilsNameValueTree object is to be replaced. - NewChild The new TUtilsNameValueTree object to associate with the name-value pair, or nil if it should be associated with no TUtilsNameValueTree object. Return value: The previously associated TUtilsNameValueTree object, or nil if there was no such object. Exceptions: - EStringListError This Delphi VCL exception is raised if this TUtilsNameValueTree object is a descendant of the specified TUtilsNameValueTree object or the specified TUtilsNameValueTree object is in use elsewhere.
Sorts the name-value pairs in the list in ascending name order. Call Sort() to sort a list that has the Sorted property set to 'False'. Lists with the Sorted property set to 'True' are automatically sorted.
TdomWideStringStream is a stream interface for WideStrings. Its purpose is to avoid excessive memory re-allocations that occur with WideStrings because they are not reference counted. Note that when the DataString property is accesses, the complete WideString will be copied out. Under Delphi for Win32 it inherits from the TStream class, under Delphi for .NET from the TMemoryStream class.