WideString Utilities Library 1.0.5

Delphi 5, 6, 7, and Kylix Implementation

by Dieter Köhler

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

Acknowledgment

Thanks to Karl Waclawek for providing the TUtilsWideStringStream class.

Introduction

The WideString Utilities Library contains helper functions for WideString. The latest version of this software is available at <http://www.philo.de/xml/>.

Using the unit

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

WideString Handling Routines and Classes

function CompareWideStr(const S1, S2: WideString): Integer;

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.

function EndsWideStr(const SubString, S: WideString): Boolean;

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.

function StartsWideStr(const SubString, S: WideString): Boolean;

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.

function TranslateWideString(const S, Pattern_1, Pattern_2: WideString): WideString;

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.

function TrimSpace(const S: WideString): WideString;

Returns the specified WideString S with leading and trailing space characters (#$20) removed.

TUtilsCustomWideStr = class

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

Public Properties

Length: Integer (readonly)
The length of the custom wide string.
WideChars[Index: Integer]: WideChar
Gives access to the WideChar on the indexth position in the custom wide string.

Public Methods

constructor Create;
Creates a new TUtilsCustomWideStr object
destructor Destroy; override;
Destroys a TUtilsCustomWideStr object. Do not call 'Destroy' directly, but use 'Free', inherited from TObject, instead. Free tests whether the TUtilsCustomWideStr has not already been freed, and only then calls 'Destroy'.
procedure AddUCS4Char(const CodePoint: Longint); virtual;
Adds an UCS-4 character of the specified code point to the end of the custom wide string.
```
      Parameters:
      - CodePoint
         The code point (Unicode scalar value) of the character to be added.
```
procedure AddWideChar(const C: WideChar) virtual;
Adds the specified WideChar to the end of the custom wide string.
```
      Parameters:
      - C
         The WideChar to be added.
```
procedure AddWideString(const S: WideString); virtual;
Adds the specified WideString to the end of the custom wide string.
```
      Parameters:
      - S
         The WideString to be added.
```

function EndsWith(const S: WideString): Boolean; virtual;
Tests whether the custom wide string ends with the specified WideString.

      Parameters:
      - S
         The WideString to be tested.

      Return value:
         'True' if the custom wide string end with
         the specified WideString, 'false' if not.

function IsEqual(const S: WideString): Boolean; virtual;
Tests whether the content of the custom wide string is byte by byte equivalent to the specified WideString.

      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.

procedure Clear; virtual;
Clears the custom wide string.

function StartsWith(const S: WideString): Boolean; virtual;
Tests whether the custom wide string starts with the specified WideString.

      Parameters:
      - S
         The WideString to be tested.

      Return value:
         'True' if the custom wide string startswith
         the specified WideString, 'false' if not.

function Value: WideString; virtual;
Returns the content of the custom wide string as a UTF-16 encoded WideString.
Since calling the Value function involves time consuming string copying, always use one of the other TUtilsCustomWideStr access functions, if possible, e.g. WideChars[Index] instead of Value[Index], IsEqual[S] instead of (Value = S), or Length instead of Length(Value).
```
      Return value:
         The content of the custom wide string as 
         a UTF-16 encoded WideString
```

WideString Lists and Trees

Auxilliary Types

TUtilsWideStringItem

  TUtilsWideStringItem = record
    FString: WideString;
    FObject: TObject;
  end;

TUtilsWideStringItem is a record internally used in the TUtilsWideStringList class to store WideString-Object pairs.

TUtilsWideStringItemList = array[0..MaxListSize] of TUtilsWideStringItem;

TUtilsWideStringItemList defines a list of TUtilsWideStringItem records.

PUtilsWideStringItemList = ^TUtilsWideStringItemList;

PUtilsWideStringItemList defines a pointer to a TUtilsWideStringItemList array. It is internally used in TUtilsWideStringList.

TUtilsWideStringList = class (TPersistent)

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:

function IndexOfLast(const S: WideString): Integer; virtual;
Returns the position of the last occurence of a WideString in the list.

      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.

TUtilsNameValueList = class (TPersistent)

A TUtilsNameValueList is used to store name-value pairs of WideStrings.

Public Properties

Capacity: Integer
The number of WideString pairs for which memory is reserved. This is equivalent to the Delphi VCL property 'TStringList.Capacity'.
Duplicates: TDuplicates
Specifies whether duplicate wideStrings can be added to sorted lists. The value of Duplicates should be one of the following:
- dupIgnore
  Ignore attempts to add duplicate WideStrings to the list (the default).
- dupError
  Raise an EStringListError exception when an attempt is made to add duplicate wideStrings to the sorted list.
- dupAccept
  Permit duplicate wideStrings in the sorted list.
Set Duplicates before adding any WideStrings to the list. Setting Duplicates to dupIgnore or dupError does nothing about duplicate WideStrings that are already in the list.
Note: Duplicates does nothing if the list is not sorted.
Length: Integer (readonly)
The number of WideStrings pairs in the list. This is equivalent to the Delphi VCL property 'TStringList.Count'.
Names[Index: Integer]: WideString (readonly)
The name part of the name-object pair on the indexth position in the list.
Objects[Index: Integer]: TObject
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.
Sorted: Boolean
Specifies whether the wideStrings in the list should be automatically sorted.
Set Sorted to 'True' to cause the wideStrings in the list to be automatically sorted in ascending order. Set Sorted to 'False' (the default) to allow strings to remain where they are inserted. When Sorted is 'False', the wideStrings 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 wideStrings to the list. Instead, use Add(), which will insert the new wideStrings in the appropriate position. When Sorted is 'False', use Insert() to add wideStrings to an arbitrary position in the list, or Add() to add wideStrings to the end of the list.
Values[Index: Integer]: WideString (readonly)
The value part of the name-object pair on the indexth position in the list.

Public Methods

constructor Create;
Creates a new TUtilsNameValueList object
destructor Destroy; override;
Destroys a TUtilsNameValueList object. Do not call 'Destroy' directly, but use 'Free', inherited from TObject, instead. Free tests whether the TUtilsNameValueList has not already been freed, and only then calls 'Destroy'.

function Add(const Name, Value: WideString): Integer; virtual;
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.

function AddObject(const Name, Value: WideString; AObject: TObject): Integer; virtual;
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.

procedure AddNameValueList(const Nvl: TUtilsNameValueList); virtual;
Adds a group of name-value pairs to the list.
Call AddNameValueList() to add the name-value pairs from another 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.
```
procedure Assign(Source: TPersistent); override;
Sets the name-value pairs in the list, and possibly associated objects, from a source object.
Use Assign() to set the value of the TUtilsNameValueList object from another object. If Source is of type TUtilsNameValueList, the list is set to the list of the source TUtilsNameValueList object, 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 TUtilsNameValueList object in its AssignTo() method.
```
      Parameters:
      - Source
         The object whose values shall be assigned.
```
procedure Clear; virtual;
Deletes all name-value pairs from the list.
procedure Delete(const Index: Integer); virtual;
Deletes a name-value pair from a specific position in the list.
```
      Parameters:
      - Item
         The list index of the name-value pair to be
         deleted.
```

procedure Exchange(const Index1, Index2: Integer); virtual;
Exchanges the position of the two specified name-value pairs in the list.

      Parameters:
      - Index1
         The list index of the first name-value pair.
      - Index2
         The list index of the second name-value pair.

function IndexOf(const Name, Value: WideString): Integer; virtual;
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 zero-based index of the specified name-value pair in the
         list, or -1 if no such pair exists.

function IndexOfLast(const Name, Value: WideString): Integer; virtual;
Returns the position of the last 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 zero-based index of the last occurrence of the 
         specified name-value pair in the list, or -1 if no 
         such pair exists.

function IndexOfLastName(const Name: WideString): Integer; virtual;
Returns the position of the last name-value pair in the list with the specified name part.

      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.

function IndexOfName(const Name: WideString): Integer; virtual;
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 no such
         pair exists.

procedure Insert(const Index: Integer; const Name, Value: WideString); virtual;
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.

function Find(const Name, Value: WideString; var Index: Integer): Boolean; virtual;
Returns the position of the first name-value pair in a sorted list with the specified name and value. Do not use this function on unsorted lists.

      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.

function FindOfName(const Name: WideString; var Index: Integer): Boolean; virtual;
Returns the position of the first name-value pair in a sorted list with the specified name part. Do not use this function on unsorted lists.

      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.

procedure Sort; virtual;
Sorts the wideStrings in the list in ascending order.
Call Sort() to sort the wideStrings in a list that has the Sorted property set to 'False'. WideString lists with the Sorted property set to 'True' are automatically sorted.

TUtilsNameValueTree = class(TUtilsNameValueList)

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.

Properties

property Capacity: Integer

      The number of wideString pairs for which memory is
      reserved. This is equivalent to the Delphi VCL
      property 'TStringList.Capacity'.

property Children[Index: Integer]: TUtilsNameValueTree (readonly)

      The TUtilsNameValueTree associated with the
      wideString pair on the indexth position in
      the list.

property Duplicates: TDuplicates

      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.

property Length: Integer (readonly)

      The number of wideStrings pairs in the list.
      This is equivalent to the Delphi VCL property
      'TStringList.count'.

property Names[Index: Integer]: WideString (readonly)

      The 'name' part of the wideString pair on the indexth
      position in the list.

property Objects[Index: Integer]: WideString

      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.

property ParentTree: TUtilsNameValueTree

      The parent tree if this TUtilsNameValueTree is
      the subtree of another TUtilsNameValueTree, or
      nil otherwise.

property Sorted: Boolean

      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.

property Values[Index: Integer]: WideString (readonly)

      The 'value' part of the wideString pair on the indexth
      position in the list.

Public methods

constructor Create;

      Creates a new TUtilsNameValueTree object.

destructor Destroy; override;

      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;

function Add(const Name, Value: WideString): Integer; virtual;

      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.

function AddChild(const Name, Value: WideString; const Child: TUtilsNameValueTree): Integer; virtual;

      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.

function AddChildObject(const Name, Value: wideString; const Child: TUtilsNameValueTree; const AObject: TObject): Integer; virtual;

      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.

function AddObject(const Name, Value: wideString; AObject: TObject): Integer; virtual;

      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.

procedure AddNameValueList(const Nvl: TUtilsNameValueList); virtual;

      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.

procedure Assign(Source: TPersistent); override;

      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.

procedure Clear; override;

      Deletes all name-value pair from the list, and destroys
      any child TUtilsNameValueTree objects.

procedure Delete(const Item: integer); override;

      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.

procedure Exchange(const Index1, Index2: integer); virtual;

      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.

function IndexOf(const Name, Value: wideString): Integer; virtual;

      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.

function IndexOfChild(const Child: TUtilsNameValueTree): Integer; virtual;

      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.

function IndexOfName(const Name: WideString): Integer; virtual;

      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.

procedure Insert(const Index: integer; const Name, Value: wideString); virtual;

      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.

procedure InsertChild(const Index: Integer; const Name, Value: WideString; const Child: TUtilsNameValueTree); virtual;

      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.

function IsDescendantOf(const Nvtree: TUtilsNameValueTree): Boolean; virtual;

      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.

function ReplaceChild(const Index: integer; const NewChild: TUtilsNameValueTree): TUtilsNameValueTree; virtual;

      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.

procedure Sort; virtual;

      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.

WideString Streaming

TUtilsWideStringStream = class (TStream)

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.

Public Properties

Capacity: Integer
The currently allocated size of the stream.
StringLength: Integer
The length of the stream in terms of WideChars.
StringPosition: Integer
The stream position in terms of WideChars.
DataString: WideString (readonly)
The content of the stream as a WideString.

Public Methods

constructor Create(const AString: WideString);
Creates a new TUtilsWideStringStream object and initializes it with the specified WideString.
destructor Destroy; override;
Destroys a TUtilsWideStringStream object. Do not call 'Destroy' directly, but use 'Free', inherited from TObject, instead. Free tests whether the TUtilsWideStringStream has not already been freed, and only then calls 'Destroy'.
function ReadString(Count: Longint): WideString;
Reads a WideString of the specified length from the stream.
procedure WriteString(const AString: WideString);
Writes the specified WideString to the Stream.