Circle DS

A suite of circular data structures, including CircleStack, CircleQueue, and CircleDeque. Use circular buffers with ease and supported by a variety of operations.

Features

Install

Using npm:

npm install circle-ds

Using yarn:

yarn install circle-ds

API

Try it out on JSFiddle.

CircleStack

CircleStack is a LIFO (Last In, First Out) data structure with a fixed capacity.

Constructor

• CircleStack<T>(): Constructs an empty circular stack a capacity of zero.
• CircleStack<T>(capacity: number): Constructs an empty circular stack with the specified capacity.
• CircleStack<T>(items: Iterable<T>): Constructs a full circular stack with the given items.
• CircleStack<T>(...items: T[]): Constructs a full circular stack with the given items.

Static Methods

• from<T>(iterable: Iterable<T> | ArrayLike<T>): CircleStack<T>: Creates a new stack from an iterable or array-like object.

• of<T>(...elements: T[]): CircleStack<T>: Creates a new stack from a variable number of elements.

Properties

• capacity: number: The maximum size of the stack. Update to grow or shrink the stack.

• size: Readonly<number>: The number of items in the stack.

Methods

• clear(): void: Remove all items from the stack.

• entries(): IterableIterator<[number, T]>: Returns an iterator that allows iteration through [index, value] pairs of the stack.

• forEach(callbackFn: (value: T, index: number, stack: CircleStack<T>) => void, thisArg?: unknown): void: Executes the provided callbackFn function once for each element, in insertion order.

• has(value: T): boolean: Checks if the stack contains a specific value.

• keys(): IterableIterator<number>: Returns an iterator for the keys (indices) in the stack.

• pop(): T | undefined: Removes and returns the item at the top of the stack. Returns undefined if the stack is empty.

• push(...items: T[]): T[]: Adds items to the top of the stack. If the stack is full, the oldest items are overwritten and returned.

• top(): T | undefined: Returns the item at the top of the stack without removing it. Returns undefined if the stack is empty.

• values(): IterableIterator<T>: Returns an iterator for the values in the stack.

• [Symbol.iterator](): IterableIterator<T>: Returns the default iterator for the stack, which iterates through its values.

CircleQueue

CircleQueue is a FIFO (First In, First Out) data structure with a fixed size.

Constructor

• CircleQueue<T>(): Constructs an empty circular queue a capacity of zero.
• CircleQueue<T>(capacity: number): Constructs an empty circular queue with the specified capacity.
• CircleQueue<T>(items: Iterable<T>): Constructs a full circular queue with the given items.
• CircleQueue<T>(...items: T[]): Constructs a full circular queue with the given items.

Static Methods

• from<T>(iterable: Iterable<T> | ArrayLike<T>): CircleQueue<T>: Creates a new queue from an iterable or array-like object.

• of<T>(...elements: T[]): CircleQueue<T>: Creates a new queue from a variable number of elements.

Properties

• capacity: number: The maximum size of the queue. Update to grow or shrink the queue.

• size: Readonly<number>: The number of items in the queue.

Methods

• clear(): void: Remove all items from the queue.

• entries(): IterableIterator<[number, T]>: Returns an iterator that allows iteration through [index, value] pairs of the queue.

• forEach(callbackFn: (value: T, index: number, queue: CircleQueue<T>) => void, thisArg?: unknown): void: Executes the provided callbackFn function once for each element, in insertion order.

• front(): T | undefined: Returns the item at the front of the queue without removing it. Returns undefined if the queue is empty.

• has(value: T): boolean: Checks if the queue contains a specific value.

• keys(): IterableIterator<number>: Returns an iterator for the keys (indices) in the queue.

• push(...items: T[]): T[]: Adds items to the back of the queue. If the queue is full, the oldest items are overwritten and returned.

• shift(): T | undefined: Removes and returns the item at the front of the queue. Returns undefined if the queue is empty.

• values(): IterableIterator<T>: Returns an iterator for the values in the queue.

• [Symbol.iterator](): IterableIterator<T>: Returns the default iterator for the queue, which iterates through its values.

CircleDeque

CircleDeque is a double-ended queue that combines the features of stacks and queues, allowing insertion and removal at both ends.

Constructor

• CircleDeque<T>(): Constructs an empty circular deque a capacity of zero.
• CircleDeque<T>(capacity: number): Constructs an empty circular deque with the specified capacity.
• CircleDeque<T>(items: Iterable<T>): Constructs a full circular deque with the given items.
• CircleDeque<T>(...items: T[]): Constructs a full circular deque with the given items.

Static Methods

• from<T>(iterable: Iterable<T> | ArrayLike<T>): CircleDeque<T>: Creates a new deque from an iterable or array-like object.

• of<T>(...elements: T[]): CircleDeque<T>: Creates a new deque from a variable number of elements.

Properties

• capacity: number: The maximum size of the deque. Update to grow or shrink the deque.

• size: Readonly<number>: The number of items in the deque.

Methods

• clear(): void: Remove all items from the deque.

• entries(): IterableIterator<[number, T]>: Returns an iterator that allows iteration through [index, value] pairs of the deque.

• forEach(callbackFn: (value: T, index: number, deque: CircleDeque<T>) => void, thisArg?: unknown): void: Executes the provided callbackFn function once for each element, in insertion order.

• front(): T | undefined: Returns the item at the front of the deque without removing it. Returns undefined if the deque is empty.

• has(value: T): boolean: Checks if the deque contains a specific value.

• keys(): IterableIterator<number>: Returns an iterator for the keys (indices) in the deque.

• pop(): T | undefined: Removes and returns the item at the top of the deque. Returns undefined if the deque is empty.

• push(...items: T[]): T[]: Adds items to the back of the deque. If the deque is full, items at the front are overwritten and returned.

• shift(): T | undefined: Removes and returns the item at the front of the deque. Returns undefined if the deque is empty.

• top(): T | undefined: Returns the item at the top of the deque without removing it. Returns undefined if the deque is empty.

• unshift(...items: T[]): T[]: Adds items to the fron of the deque. If the deque is full, items at the back are overwritten and returned.

• values(): IterableIterator<T>: Returns an iterator for the values in the deque.

• [Symbol.iterator](): IterableIterator<T>: Returns the default iterator for the deque, which iterates through its values.

License

Copyright (C) 2024-2024 Michael Rojas dev.michael.rojas@gmail.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Made with ❤️ by Michael Rojas