Skip to main content

Sort

procedure Sort;

Example​

procedure ScriptEvent(var Value: variant);
var
  Names: TStringList;
begin
  Names := TStringList.Create;
  try
    Names.Add('Gamma');
    Names.Add('Alpha');
    Names.Add('Beta');
    Names.Sort;
    Value := Names.Strings[0];  // Alpha
  finally
    Names.Free;
  end;
end;

Usage​

Performs a one-time unstable comparator sort while deliberately leaving the list in unsorted insertion mode.

Additional Technical Info​

Sort calls the native default CustomSort with the list's current String comparator. When Sorted is false and Count > 1, it invokes OnChanging once, performs an in-place quicksort, then invokes OnChange once.

The method intentionally does not set Sorted=True. It changes current physical order only. Later Add calls append at the end and can make the list unordered again. Set the Sorted property to true when maintained ordering and Duplicates enforcement are required.

When Sorted=True, or when the list contains zero or one entry, Sort is a no-op and fires no events. To re-sort a list whose sorted flag is true but whose order was corrupted, first set Sorted=False, then set it true again.

The quicksort is not stable. Strings that compare equal can change relative order, and their associated Objects move with them as intact pairs. Do not depend on original order among duplicates or retain indexes across the call.

An exception from OnChanging occurs before sorting. An exception from OnChange occurs after sorting. A failure during comparison could leave a partially rearranged list without the post-change callback; the method provides no rollback. Event handlers must not re-enter mutations on the same list.

Average runtime is O(n log n), worst case depends on partition behavior, and the implementation sorts the backing array in place. Locale-aware comparison cost grows with String length. The operation is mutable and not thread-safe.

The source-reviewed example uses one-time sorting intentionally and frees the caller-owned list. It was not executed by the documentation workflow.

External references

Created 2026-07-15