# stack Specification Sheet

Portable Object Compiler (c) 1998. All Rights Reserved.

# Stack

Inherits from: Cltn

## Class Description

Stack instances are collections that maintain their entries in LIFO (last in first out) order. Although Stacks are most often controlled by the push: and pop methods, the class also provides for random access of the stack, through the at: and removeAt: methods. Note that the indices are relative to the top (last added) item on the stack, which is the opposite of how the OrdCltn class works.

## Method types

### Creation

- new
- new:
- copy
- deepCopy
- emptyYourself
- freeContents
- free

### Interrogation

- depth
- isEmpty
- eachElement
- topElement

### Adding

- push:
- pop
- swap
- at:
- removeAt:

### Printing

- printOn:

## Methods

### new

> +new

Returns a new empty stack.

### new:

> +new:(unsigned)n

Returns a new empty stack, that can hold n objects.

### copy

> -copy

Returns a new copy of the stack.

### deepCopy

> -deepCopy

Returns a new copy of the stack. The members in the new stack are deep copies of the members in the original stack.

### emptyYourself

> -emptyYourself

Removes all the members of the stack (without freeing them). Returns the receiver.

### freeContents

> -freeContents

Removes and frees all the members of the receiver, but doesn't free the receiver itself. Returns the receiver.

### free

> -free

Frees the stack, but not its contents. Returns nil. Do :

>     aCltn = [[aCltn freeContents] free];

if you want to free the collection and its contents.

### depth

> - (unsigned)depth

Returns the number of objects on the stack.

### isEmpty

> - (BOOL)isEmpty

Whether the number of objects on the stack is equal to zero.

### eachElement

> -eachElement

Returns a sequence of the elements in the collection.

>     aSeq = [myStack eachElement];
>     while ((anElement = [aSeq next])) {
>         /* do something */
>     }
>     aSeq = [aSeq free];

### topElement

> -topElement

Returns the top element on the stack, without removing it. Returns nil if there are no elements on the stack.

### push:

> -push:anObject

Pushes anObject on the stack, so that it becomes the top of the stack. Returns self.

### pop

> -pop

Pops the top of the stack and returns it. Returns nil if the stack is empty.

### swap

> -swap

Exchanges the top two stack items and returns the receiver. Generates an exception if the stack is not at least two items deep.

### at:

> -at:(unsigned )anOffset

Returns the object at anOffset. Note that the top of the stack is at offset 0.

### removeAt:

> -removeAt:(unsigned )anOffset

Removes the object at anOffset. Note that the top of the stack is at offset 0.

### printOn:

> -printOn:(IOD)aFile

Prints a list of the objects in the objects by sending each individual object a printOn: message. Returns the receiver.