TStack.Extract Method

Remove top stack item.

Pascal

function Extract: T;

C++

__fastcall T Extract();

Description

Extract removes and returns the top element of the stack. Count is decremented by 1. If Count is already 0, an error is raised.

An OnNotify event occurs indicating an item was removed from the stack. Extract is the same as Pop except for the event code indicating an element was extracted rather than removed.

Extract functions similarly to Peek except that Extract removes an element from the stack.

Extract is similar to Pop and is provided so items may be removed without freeing.

This is a O(1) operation.

Delphi Examples:

Copy Code

{
This example demonstrates the usage of the generic TStack class.
}
procedure TForm3.Button1Click(Sender: TObject);
var
  Stack: TStack<String>;
begin
  { Create a new stack }
  Stack := TStack<String>.Create();

  { Register a notification call-back }
  Stack.OnNotify := StackChanged;

  { Push some items up the stack }
  Stack.Push('John');
  Stack.Push('Mary');
  Stack.Push('Bob');
  Stack.Push('Anna');
  Stack.Push('Erica');

  { Show the last pushed element without modifying the stack }
  MessageDlg('Last pushed element is: "' + Stack.Peek() + '".', mtInformation, [mbOK], 0);

  { Extract the top element: "John" }
  Stack.Extract();

  { Reduce the capacity }
  Stack.TrimExcess();

  { The remaining count of elements }
  MessageDlg('The stack contains ' + IntToStr(Stack.Count) + ' elements.', mtInformation, [mbOK], 0);

  { Show the last pushed element by modifying the stack }
  MessageDlg('Last pushed element is: "' + Stack.Pop() + '".', mtInformation, [mbOK], 0);

  { Clear the stack }
  Stack.Clear();

  { Destroy the stack completely }
  Stack.Free;
end;

procedure TForm3.StackChanged(Sender: TObject; const Item: String; Action: TCollectionNotification);
begin
  { This method is called by the Stack everytime a change occurs }
  if Action = cnAdded then
     MessageDlg('Element added: ' + Item, mtInformation, [mbOK], 0)
  else if Action = cnRemoved then
     MessageDlg('Element removed: ' + Item, mtInformation, [mbOK], 0)
  else if Action = cnExtracted then
     MessageDlg('Element extracted: ' + Item, mtInformation, [mbOK], 0)
end;