Skip to main content

InsertObject

procedure InsertObject(Index: Integer; S: string; AObject: TObject);

Example​

procedure InsertContext(const Items: TStringList; const Context: TObject);
begin
  if not Items.Sorted then
    Items.InsertObject(0, 'Context', Context);
end;

Usage​

Call InsertObject to insert a string and associated TObject reference at a requested zero-based index. The object is not cloned, and later items shift position.

  • Do not use this method on sorted TStringList; use AddObject.
  • Decide and document who owns the object before associating it.
  • Insertion shifts later indexes.

Usage guidance​

  • Do not use this method on sorted TStringList; use AddObject.
  • Decide and document who owns the object before associating it.
  • Insertion shifts later indexes.
  • Other TStrings string lists can use the base two-step path and may be partially changed on setter failure.

Additional Technical Info​

InsertObject is declared by hidden ancestor TStrings and is normally used through a concrete visible descendant such as TStringList. The association remains subject to the descendant's ownership policy.

Source-backed behaviour​

The base implementation calls virtual Insert and then sets Objects[Index], so a failure in the second step can leave text inserted without the object. TStringList overrides the method and inserts the pair together.

For TStringList, the index range is 0..Count, and Sorted=True raises instead of accepting an explicit position. The parameterless script-created list borrows AObject; no clone or lifetime check is performed.

AddObject lets the descendant choose the index. IndexOfObject searches associations by identity.

Official RTL references​

Created 2026-07-15