CodeSnip Old Code (SVN)

{
 * ULists.pas
 *
 * Defines various classes that maintain lists of data of various types.
 *
 * $Rev$
 * $Date$
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * 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 ULists.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2009 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit ULists;


interface


uses
  // Delphi
  Contnrs;


type

  {
  TObjectListEnum:
    Enumerator for object lists.
  }
  TObjectListEnum = class(TObject)
  strict private
    var
      fList: TObjectList; // Reference to object list being enumerated
      fIndex: Integer;    // Index of current object in enumeration
  public
    constructor Create(const List: TObjectList);
      {Class constructor. Initialises enumeration.
        @param List [in] Object to be enurmerated.
      }
    function GetCurrent: TObject;
      {Gets current object in enumeration.
        @return Required object.
      }
    function MoveNext: Boolean;
      {Moves to next item in enumeration.
        @return True if there is a next item, False if beyond last item.
      }
    property Current: TObject read GetCurrent;
      {Current object in enumeration}
  end;

  {
  TObjectListEx:
    Extended version of TObjectList that adds extra features.
  }
  TObjectListEx = class(TObjectList)
  public
    function IsEmpty: Boolean;
      {Checks if list is empty.
        @return True if empty, False otherwise.
      }
    function Contains(const Obj: TObject): Boolean;
      {Checks if the list contains an object.
        @param Obj [in] Object being checked for.
        @return True if list contains Obj, False otherwise.
      }
    function GetEnumerator: TObjectListEnum;
      {Gets an enumerator for the list.
        @return Required enumerator.
      }
  end;

  {
  TIntegerList:
    Maintains a list of integers and associated objects.
  }
  TIntegerList = class(TObject)
  strict private
    type
      {
      TListItem:
        Wrapper object for items stored in list.
      }
      TListItem = class(TObject)
      strict private
        var
          fValue: Integer;  // Value of Value property
          fObj: TObject;    // Value of Obj property
      public
        constructor Create(const Value: Integer; const Obj: TObject = nil);
          {Class constructor. Sets up object represent an integer and any
          associated object.
          }
        property Value: Integer read fValue;
          {Integer value of list item}
        property Obj: TObject read fObj;
          {Object associated with Value, or nil if no such object}
      end;
    type
      {
      TEnumerator:
        List enumerator.
      }
      TEnumerator = class(TObject)
      strict private
        var
          fIndex: Integer;      // Index of current item in enumeration
          fList: TIntegerList;  // List being eumerated
      public
        function GetCurrent: Integer;
          {Gets current integer in enumeration.
            @return Current integer.
          }
        function MoveNext: Boolean;
          {Moves to next item in enumeration.
            @return True if there is a next item, False if enumeration
              completed.
          }
        property Current: Integer read GetCurrent;
          {Current item in enumeration}
        constructor Create(const List: TIntegerList);
          {Class constructor. Sets up enumerator for a list.
            @param List [in] List to be enumerated.
          }
      end;
    var
      fItems: TObjectListEx;  // Stores list items
    function GetItem(Idx: Integer): Integer;
      {Read accessor for Items[] property.
        @param Idx [in] Index of required item.
        @return Requested integer.
      }
    function GetCount: Integer;
      {Read accessor for Count property.
        @return Number of items in list.
      }
    function GetObject(Idx: Integer): TObject;
      {Read accessor for Objects[] property.
        @param Idx [in] Index of required object.
        @return Requested object reference.
      }
  public
    constructor Create;
      {Class constructor. Sets up object.
      }
    destructor Destroy; override;
      {Class destructor Tears down object.
      }
    function Add(const Value: Integer; const Obj: TObject = nil): Integer;
      {Adds an integer with optional associated object to the list.
        @param Value [in] Integer to be added.
        @param Obj [in] Object associated with integer or nil.
        @return Index of new list item.
      }
    function IndexOf(const Value: Integer): Integer;
      {Finds index of an integer in list.
        @param Value [in] Value to be found.
        @return Index of Value in list, or -1 if not found.
      }
    function FindObject(const Value: Integer): TObject;
      {Finds object associated with a integer in list.
        @param Value [in] Integer value assoicated with object.
        @return Required object reference or nil if not found or no object
          associated with Value.
      }
    function GetEnumerator: TEnumerator;
      {Gets an enumerator for the list.
        @return Enumerator instance.
      }
    property Items[Idx: Integer]: Integer read GetItem; default;
      {Accesses all integers in list by index}
    property Objects[Idx: Integer]: TObject read GetObject;
      {Accesses all associated objects in list by index}
    property Count: Integer read GetCount;
      {Number of items in list}
  end;

  {
  TObjectCompare:
    Type of comparison method used to order objects in TSortedObjectList
    objects.
      @param Obj1 [in] First object to be compared.
      @param Obj2 [in] Second object to be compared.
      @return -ve if Obj1 < Obj2, 0 if Obj1 = Obj2 or +ve if Obj1 > Obj2.
  }
  TObjectCompare = function(const Obj1, Obj2: TObject): Integer of object;

  {
  TSortedObjectList:
    Class that maintains a sorted list of objects. Caller must provide a
    comparison method that determines sort order of objects. Objects must be
    unique (i.e. comparison method must not evaluate to zero for two objects in
    the list which means that two distinct objects can be determined to be
    equal).
  }
  TSortedObjectList = class(TObject)
  strict private
    var
      fItems: TObjectListEx;    // Maintains list of objects
      fCompare: TObjectCompare; // Comparison method.
    function GetItem(Idx: Integer): TObject;
      {Read accessor for Items property.
        @param Idx [in] Index of required item.
        @return Required object.
      }
    function GetCount: Integer;
      {Read accessor for Count property.
        @return Number of objects in list.
      }
    function GetOwnsObjects: Boolean;
      {Read accessor for OwnsObjects property.
        @return True list owns list item objects, False if not.
      }
  strict protected
    function Find(const SearchObj: TObject; out Index: Integer): Boolean;
      overload;
      {Finds an object in list.
        @param SearchObj [in] Object to be searched for.
        @param Index [out] Index of object in list if found, undefined if not
          found.
        @return True if object found, False if not.
      }
  public
    constructor Create(const OwnsObjects: Boolean;
      const CompareFn: TObjectCompare);
      {Class constructor. Sets up object.
        @param OwnsObjects [in] Flag indicating if list owns the objects added
          to it. When True objects are freed when list is freed. When False
          objects are not freed.
        @param CompareFn [in] Method used to compare objects in list.
      }
    destructor Destroy; override;
      {Class detructor. Tears down object. Frees object in list if list owns
      objects.
      }
    function Add(const Obj: TObject): Integer;
      {Adds an object to the list, maintaining list's sort order.
        @param Obj [in] Object to be added to list.
        @return Index where object was inserted in list.
        @except EBug raised if attempt made to add duplicate to list.
      }
    function Contains(const Obj: TObject): Boolean;
      {Checks if list contains an object.
        @param Obj [in] Object to be checked.
        @return True if Obj is in the list, False if not.
      }
    function Find(const SearchObj: TObject): TObject; overload;
      {Finds a matching object in list.
        @param SearchObj [in] Object to be searched for.
        @return Reference to found object or nil if not found. Returned object
          may or may not not be the same instance as SearchObj, may be a
          different object that compares the same.
      }
    function IndexOf(const SearchObj: TObject): Integer;
      {Gets index of a matching object in list.
        @param SearchObj [in] Object to be searched for.
        @return Index of matching object in list or -1 if not in list.
      }
    function GetEnumerator: TObjectListEnum;
      {Creates an enumerator for this object.
        @return Reference to new enumerator. Caller is repsonsible for freeing
          this object.
      }
    property Items[Idx: Integer]: TObject read GetItem; default;
      {Indexed array of objects in list. Maintained in sort order}
    property Count: Integer read GetCount;
      {Number of objects in list}
    property OwnsObjects: Boolean read GetOwnsObjects;
      {Flag indicates whether list owns, and frees, objects in list}
  end;

  {
  TSortedObjectDictionary:
    Dictionary mapping key objects onto associated value objects. Keys are
    maintained in an order determined by compare method passed to constructor.
  }
  TSortedObjectDictionary = class(TObject)
  strict private
    var
      fKeys: TSortedObjectList; // list of key objects
      fValues: TObjectListEx;   // list of value objects
    function GetKey(Idx: Integer): TObject;
      {Read accessor for Keys[] property.
        @param Idx [in] Index of required key.
        @return Requested key object.
      }
    function GetValue(Key: TObject): TObject;
      {Read accessor for Values[] property. Retrieves value associated with a
      key.
        @param Key [in] Key associated with required value.
        @return Associated value or nil if Key is not found.
      }
    function GetCount: Integer;
      {Read accessor for Count property.
        @return Number of key / value pairs in dictionary.
      }
  public
    constructor Create(const KeyCompare: TObjectCompare;
      const OwnsKeys: Boolean = False; const OwnsValues: Boolean = False);
      {Class constructor. Sets up object.
        @param KeyCompare [in] Method used to compare key objects in list.
        @param OwnsKeys [in] Whether dictionary owns key objects and frees them
          when deleted. If True no object may be used more than once, either as
          a key or a value, otherwise an access violation may occur.
        @param OwnsValues [in] Whether dictionary owns value objects and frees
          them when deleted. If True no object may be used more than once, either
          as a key or a value, otherwise an access violation may occur.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object and frees keys and / or values if
      required.
      }
    function Add(const Key, Value: TObject): Integer;
      {Adds a key/value pair to the dictionary, maintaining key sort order.
        @param Key [in] Object representing key.
        @param Value [in] Object value associated with key.
      }
    function IndexOf(const Key: TObject): Integer;
      {Gets index of a key in dictionary.
        @param Key [in] Key to locate in dictionary.
        @return Index of Key in dictionary or -1 if not found.
      }
    function KeyExists(const Key: TObject): Boolean;
      {Checks whether a key is present in dictionary.
        @param Key [in] Key to be checked.
        @return True if a matching key is present in dictionary, False if not.
      }
    function GetEnumerator: TObjectListEnum;
      {Gets enumerator for dictionary keys.
        @return Required enumerator.
      }
    property Keys[Idx: Integer]: TObject read GetKey;
      {Indexed ordered array of dictionary keys}
    property Values[Key: TObject]: TObject read GetValue;
      {List of values indexed by keys}
    property Count: Integer read GetCount;
      {Number of entries in dictionary}
  end;


implementation


uses
  // Delphi
  SysUtils,
  // Project
  UExceptions;


{ TObjectListEnum }

constructor TObjectListEnum.Create(const List: TObjectList);
  {Class constructor. Initialises enumeration.
    @param List [in] Object to be enurmerated.
  }
begin
  inherited Create;
  fList := List;
  fIndex := -1;
end;

function TObjectListEnum.GetCurrent: TObject;
  {Gets current object in enumeration.
    @return Required object.
  }
begin
  Result := fList[fIndex];
end;

function TObjectListEnum.MoveNext: Boolean;
  {Moves to next item in enumeration.
    @return True if there is a next item, False if beyond last item.
  }
begin
  Result := fIndex < Pred(fList.Count);
  if Result then
    Inc(fIndex);
end;

{ TObjectListEx }

function TObjectListEx.Contains(const Obj: TObject): Boolean;
  {Checks if the list contains an object.
    @param Obj [in] Object being checked for.
    @return True if list contains Obj, False otherwise.
  }
begin
  Result := IndexOf(Obj) >= 0;
end;

function TObjectListEx.GetEnumerator: TObjectListEnum;
  {Gets an enumerator for the list.
    @return Required enumerator.
  }
begin
  Result := TObjectListEnum.Create(Self);
end;

function TObjectListEx.IsEmpty: Boolean;
  {Checks if list is empty.
    @return True if empty, False otherwise.
  }
begin
  Result := Count = 0;
end;

{ TIntegerList }

function TIntegerList.Add(const Value: Integer; const Obj: TObject): Integer;
  {Adds an integer with optional associated object to the list.
    @param Value [in] Integer to be added.
    @param Obj [in] Object associated with integer or nil.
    @return Index of new list item.
  }
begin
  Result := fItems.Add(TListItem.Create(Value, Obj));
end;

constructor TIntegerList.Create;
  {Class constructor. Sets up object.
  }
begin
  inherited Create;
  fItems := TObjectListEx.Create(True);
end;

destructor TIntegerList.Destroy;
  {Class destructor Tears down object.
  }
begin
  FreeAndNil(fItems); // frees owned TListItem objects
  inherited;
end;

function TIntegerList.FindObject(const Value: Integer): TObject;
  {Finds object associated with a integer in list.
    @param Value [in] Integer value assoicated with object.
    @return Required object reference or nil if not found or no object
      associated with Value.
  }
var
  Idx: Integer; // loops thru list items
begin
  Idx := IndexOf(Value);
  if Idx >= 0 then
    Result := Objects[Idx]
  else
    Result := nil;
end;

function TIntegerList.GetCount: Integer;
  {Read accessor for Count property.
    @return Number of items in list.
  }
begin
  Result := fItems.Count;
end;

function TIntegerList.GetEnumerator: TEnumerator;
  {Gets an enumerator for the list.
    @return Enumerator instance.
  }
begin
  Result := TEnumerator.Create(Self);
end;

function TIntegerList.GetItem(Idx: Integer): Integer;
  {Read accessor for Items[] property.
    @param Idx [in] Index of required item.
    @return Requested integer.
  }
begin
  Result := (fItems[Idx] as TListItem).Value;
end;

function TIntegerList.GetObject(Idx: Integer): TObject;
  {Read accessor for Objects[] property.
    @param Idx [in] Index of required object.
    @return Requested object reference.
  }
begin
  Result := (fItems[Idx] as TListItem).Obj;
end;

function TIntegerList.IndexOf(const Value: Integer): Integer;
  {Finds index of an integer in list.
    @param Value [in] Value to be found.
    @return Index of Value in list, or -1 if not found.
  }
var
  Idx: Integer; // loops all items in list
begin
  Result := -1;
  for Idx := 0 to Pred(Count) do
  begin
    if Items[Idx] = Value then
    begin
      Result := Idx;
      Break;
    end;
  end;
end;

{ TIntegerList.TListItem }

constructor TIntegerList.TListItem.Create(const Value: Integer;
  const Obj: TObject);
  {Class constructor. Sets up object represent an integer and any associated
  object.
  }
begin
  inherited Create;
  fValue := Value;
  fObj := Obj;
end;

{ TIntegerList.TEnumerator }

constructor TIntegerList.TEnumerator.Create(const List: TIntegerList);
  {Class constructor. Sets up enumerator for a list.
    @param List [in] List to be enumerated.
  }
begin
  inherited Create;
  fList := List;
  fIndex := -1;
end;

function TIntegerList.TEnumerator.GetCurrent: Integer;
  {Gets current integer in enumeration.
    @return Current integer.
  }
begin
  Result := fList[fIndex];
end;

function TIntegerList.TEnumerator.MoveNext: Boolean;
  {Moves to next item in enumeration.
    @return True if there is a next item, False if enumeration completed.
  }
begin
  Result := fIndex < Pred(fList.Count);
  if Result then
    Inc(fIndex);
end;

{ TSortedObjectList }

function TSortedObjectList.Add(const Obj: TObject): Integer;
  {Adds an object to the list, maintaining list's sort order.
    @param Obj [in] Object to be added to list.
    @return Index where object was inserted in list.
    @except EBug raised if attempt made to add duplicate to list.
  }
var
  Idx: Integer; // loops thru list
  Cmp: Integer; // result of comparison of snippet names
begin
  // Assume adding to end of list
  Result := Count;
  // Loop thru existing items searching for location to insert
  for Idx := 0 to Pred(Count) do
  begin
    // compare new item to current item
    Cmp := fCompare(Obj, Items[Idx]);
    if Cmp = 0 then
      // don't allow duplicates
      raise EBug.CreateFmt('%s.Add: Duplicate object', [ClassName]);
    if Cmp < 0 then
    begin
      // current item is greater than new one: insert before it
      Result := Idx;
      Break;
    end;
  end;
  // add the new item
  fItems.Insert(Result, Obj);
end;

function TSortedObjectList.Contains(const Obj: TObject): Boolean;
  {Checks if list contains an object.
    @param Obj [in] Object to be checked.
    @return True if Obj is in the list, False if not.
  }
var
  Dummy: Integer; // index of object in list: unused
begin
  Result := Find(Obj, Dummy);
end;

constructor TSortedObjectList.Create(const OwnsObjects: Boolean;
  const CompareFn: TObjectCompare);
  {Class constructor. Sets up object.
    @param OwnsObjects [in] Flag indicating if list owns the objects added to
      it. When True objects are freed when list is freed. When False objects are
      not freed.
    @param CompareFn [in] Method used to compare objects in list.
  }
begin
  Assert(Assigned(CompareFn), ClassName + '.Create: CompareFn not assigned');
  inherited Create;
  fItems := TObjectListEx.Create(OwnsObjects);
  fCompare := CompareFn;
end;

destructor TSortedObjectList.Destroy;
  {Class detructor. Tears down object. Frees object in list if list owns
  objects.
  }
begin
  FreeAndNil(fItems); // frees contained objects if specified
  inherited;
end;

function TSortedObjectList.Find(const SearchObj: TObject): TObject;
  {Finds a matching object in list.
    @param SearchObj [in] Object to be searched for.
    @return Reference to found object or nil if not found. Returned object may
      or may not not be the same instance as SearchObj, may be a different
      object that compares the same.
  }
var
  Idx: Integer; // index of match of SearchObj in list if present
begin
  if Find(SearchObj, Idx) then
    Result := fItems[Idx]
  else
    Result := nil;
end;

function TSortedObjectList.Find(const SearchObj: TObject;
  out Index: Integer): Boolean;
  {Finds an object in list.
    @param SearchObj [in] Object to be searched for.
    @param Index [out] Index of object in list if found, undefined if not found.
    @return True if object found, False if not.
  }
var
  Low, High: Integer;   // low and high bounds of search
  Cur: Integer;         // current item to be tested
  Cmp: Integer;         // result of comparing two items
begin
  // Uses binary search: based on TStringList.Find from Delphi Classes unit
  // Initialise
  Result := False;
  Low := 0;
  High := Count - 1;
  // Perform binary search
  while Low <= High do
  begin
    // Choose item to be compared: mid point of range
    Cur := (Low + High) shr 1;
    // Compare chosen
    Cmp := fCompare(Items[Cur], SearchObj);
    if Cmp < 0 then
      // Current item < required: search above current item
      Low := Cur + 1
    else
    begin
      // Current item >= required: search below current item
      High := Cur - 1;
      if Cmp = 0 then
      begin
        // We found it: set Low to Cur because Cur > High => loop will terminate
        Result := True;
        Low := Cur;
      end;
    end;
  end;
  // Set index (Low = Cur if found)
  Index := Low;
end;

function TSortedObjectList.GetCount: Integer;
  {Read accessor for Count property.
    @return Number of objects in list.
  }
begin
  Result := fItems.Count;
end;

function TSortedObjectList.GetEnumerator: TObjectListEnum;
  {Creates an enumerator for this object.
    @return Reference to new enumerator. Caller is repsonsible for freeing
      this object.
  }
begin
  Result := fItems.GetEnumerator;
end;

function TSortedObjectList.GetItem(Idx: Integer): TObject;
  {Read accessor for Items property.
    @param Idx [in] Index of required item.
    @return Required object.
  }
begin
  Result := fItems[Idx];
end;

function TSortedObjectList.GetOwnsObjects: Boolean;
  {Read accessor for OwnsObjects property.
    @return True list owns list item objects, False if not.
  }
begin
  Result := fItems.OwnsObjects;
end;

function TSortedObjectList.IndexOf(const SearchObj: TObject): Integer;
  {Gets index of a matching object in list.
    @param SearchObj [in] Object to be searched for.
    @return Index of matching object in list or -1 if not in list.
  }
begin
  if not Find(SearchObj, Result) then
    Result := -1;
end;

{ TSortedObjectDictionary }

function TSortedObjectDictionary.Add(const Key, Value: TObject): Integer;
  {Adds a key/value pair to the dictionary, maintaining key sort order.
    @param Key [in] Object representing key.
    @param Value [in] Object value associated with key.
  }
begin
  Result := fKeys.Add(Key);
  fValues.Insert(Result, Value);
end;

constructor TSortedObjectDictionary.Create(const KeyCompare: TObjectCompare;
  const OwnsKeys, OwnsValues: Boolean);
  {Class constructor. Sets up object.
    @param KeyCompare [in] Method used to compare key objects in list.
    @param OwnsKeys [in] Whether dictionary owns key objects and frees them
      when deleted. If True no object may be used more than once, either as
      a key or a value, otherwise an access violation may occur.
    @param OwnsValues [in] Whether dictionary owns value objects and frees
      them when deleted. If True no object may be used more than once, either
      as a key or a value, otherwise an access violation may occur.
  }
begin
  inherited Create;
  fKeys := TSortedObjectList.Create(OwnsKeys, KeyCompare);
  fValues := TObjectListEx.Create(OwnsValues);
end;

destructor TSortedObjectDictionary.Destroy;
  {Class destructor. Tears down object and frees keys and / or values if
  required.
  }
begin
  FreeAndNil(fValues);
  FreeAndNil(fKeys);
  inherited;
end;

function TSortedObjectDictionary.GetCount: Integer;
  {Read accessor for Count property.
    @return Number of key / value pairs in dictionary.
  }
begin
  Result := fKeys.Count;
end;

function TSortedObjectDictionary.GetEnumerator: TObjectListEnum;
  {Gets enumerator for dictionary keys.
    @return Required enumerator.
  }
begin
  Result := fKeys.GetEnumerator;
end;

function TSortedObjectDictionary.GetKey(Idx: Integer): TObject;
  {Read accessor for Keys[] property.
    @param Idx [in] Index of required key.
    @return Requested key object.
  }
begin
  Result := fKeys[Idx];
end;

function TSortedObjectDictionary.GetValue(Key: TObject): TObject;
  {Read accessor for Values[] property. Retrieves value associated with a key.
    @param Key [in] Key associated with required value.
    @return Associated value or nil if Key is not found.
  }
var
  Index: Integer; // index of Key in list
begin
  Index := fKeys.IndexOf(Key);
  if Index >= 0 then
    Result := fValues[Index]
  else
    Result := nil;
end;

function TSortedObjectDictionary.IndexOf(const Key: TObject): Integer;
  {Gets index of a key in dictionary.
    @param Key [in] Key to locate in dictionary.
    @return Index of Key in dictionary or -1 if not found.
  }
begin
  Result := fKeys.IndexOf(Key);
end;

function TSortedObjectDictionary.KeyExists(const Key: TObject): Boolean;
  {Checks whether a key is present in dictionary.
    @param Key [in] Key to be checked.
    @return True if a matching key is present in dictionary, False if not.
  }
begin
  Result := fKeys.Contains(Key);
end;

end.