# 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](https://alex-myznikov.gitbook.io/adsjs/api/position)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alex-myznikov.gitbook.io/adsjs/api/linked-lists/singly-linked-list.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.