> For the complete documentation index, see [llms.txt](https://alex-myznikov.gitbook.io/adsjs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alex-myznikov.gitbook.io/adsjs/api/linked-lists/singly-linked-list.md).

# SinglyLinkedList

Positional linked list with elements linked in one direction from head to tail.

#### Generic types (only for TS):

*T* - Type of elements stored in the list.

### new SinglyLinkedList()

```typescript
/**
 * Creates an instance of SinglyLinkedList.
 *
 * @param elements Array of elements to create the new linked list with.
 */
constructor(elements: T[] = [])
```

> Creating a SinglyLinkedList with elements 1->2->3:

```typescript
new SinglyLinkedList([1, 2, 3]);
```

### length

```typescript
/**
 * Number of elements in the list.
 *
 * @readonly
 */
get length(): number
```

> Adding element increases list length:

```typescript
const list = new SinglyLinkedList();

list.length === 0; // true
list.addFirst(1);
list.length === 1; // true
```

### addAfter()

```typescript
/**
 * Adds element after the specified position in the list. Throws an error if the position
 * does not belong to this list or its element has been removed from the list. Running time is O(1).
 *
 * @param position Position in the list.
 * @param element Element to add after the position.
 * @returns Position of the added element.
 */
addAfter(position: Position<T, Node<T>>, element: T): Position<T, Node<T>>
```

> Adding element after the specified position:

```typescript
const list = new SinglyLinkedList();

list.addFirst(1);
list.addAfter(list.getFirst(), 2); // list now is 1->2
```

### addFirst()

```typescript
/**
 * Adds element at the front of the list. Running time is O(1).
 *
 * @param element Element to add.
 * @returns Position of the added element.
 */
addFirst(element: T): Position<T, Node<T>>
```

> Adding element at the front of a list:

```typescript
const list = new SinglyLinkedList();

list.addFirst(1); // list now is 1
list.addFirst(2); // list now is 2->1
```

### addLast()

```typescript
/**
 * Adds element at the back of the list. Running time is O(1).
 *
 * @param element Element to add.
 * @returns Position of the added element.
 */
addLast(element: T): Position<T, Node<T>>
```

> Adding element at the back of a list:

```typescript
const list = new SinglyLinkedList();

list.addLast(1); // list now is 1
list.addLast(2); // list now is 1->2
```

### clear()

```typescript
/**
 * Clears the list. If instant set TRUE it takes O(1) time but does not deprecate existing positions.
 *
 * @param instant TRUE to deprecate all existing positions, FALSE to skip deprecation (client code cares of it).
 */
clear(instant?: boolean): void;
```

> Deep clearing:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);

list.length === 3; // true
list.clear(); // O(n)
list.length === 0; // true
```

> Fast clearing:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);
const position = list.getFirst(); // Position of 1

list.clear(true); // O(1)
list.length === 0; // true
list.addAfter(position, 4); // list now is 4, error not thrown
```

### getAfter()

```typescript
/**
 * Gets position after the specified position in the list. Throws an error if the position
 * does not belong to this list or its element has been removed. Running time is O(1).
 *
 * @param position Position in the list.
 * @returns Position of the element next to the specified or undefined if the specified position is the last.
 */
getAfter(position: Position<T, Node<T>>): Position<T, Node<T>> | undefined
```

> Getting position after the specified:

```typescript
const list = new SinglyLinkedList([1, 2]);

list.getAfter(list.getFirst()); // Position of 2
```

### getFirst()

```typescript
/**
 * Gets position of the first element in the list. Running time is O(1).
 *
 * @returns Position of the element or undefined if the list is empty.
 */
getFirst(): Position<T, Node<T>> | undefined
```

> Getting position of the first element:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);

list.getFirst(); // Position of 1
```

### getLast()

```typescript
/**
 * Gets position of the last element in the list. Running time is O(1).
 *
 * @returns Position of the element or undefined if the list is empty.
 */
getLast(): Position<T, Node<T>> | undefined
```

> Getting position of the last element:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);

list.getLast(); // Position of 3
```

{% hint style="info" %}
getLast() and getFirst() return positions of the same element if list has only one element. These positions won't be the same object however.
{% endhint %}

### isEmpty()

```typescript
/**
 * Checks whether the list is empty or not. Running time is O(1).
 *
 * @returns TRUE if the list is empty, FALSE otherwise.
 */
isEmpty(): boolean
```

> Adding element makes list not empty:

```typescript
const list = new SinglyLinkedList();

list.isEmpty(); // true
list.addFirst(1);
list.isEmpty(); // false
```

### removeFirst()

```typescript
/**
 * Removes the first element from the list and returns it. Deprecates all positions pointing to that element.
 * Throws an error if the list is empty. Running time is O(1).
 *
 * @throws {ADSError} List is empty.
 * @returns Removed element.
 */
removeFirst(): T
```

> Removing element deprecates its position:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);
const position = list.getFirst();

list.removeFirst() === 1; // true, list now is 2->3
list.getAfter(position); // throws 'ADSError: Position is deprecated'
```

### replace()

```typescript
/**
 * Replaces element at the specified position. Throws an error if the position
 * does not belong to this list or its element has been removed. Running time is O(1).
 *
 * @param position Position in the list.
 * @param element Element to replace the existing with.
 * @returns Replaced element.
 */
replace(position: Position<T, Node<T>>, element: T): T
```

> Replacing element takes effect for all positions pointing to it:

```typescript
const list = new SinglyLinkedList([1]);
const position = list.getFirst();

list.replace(list.getFirst(), 2);
position.element;// element now is 2
```

### \[Symbol.iterator]\()

```typescript
[Symbol.iterator](): IterableIterator<T>
```

> Building an array from list:

```typescript
const list = new SinglyLinkedList([1, 2, 3]);

Array.from(list); // [1, 2, 3]
```

### See also

[Position](/adsjs/api/position.md)