@stdlib/dstructs-doubly-linked-list 0.1.0

package/README.md

@@ -0,0 +1,628 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2018 The Stdlib Authors.
+
+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
+
+   http://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.
+
+-->
+
+
+<details>
+  <summary>
+    About stdlib...
+  </summary>
+  <p>We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.</p>
+  <p>The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.</p>
+  <p>When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.</p>
+  <p>To join us in bringing numerical computing to the web, get started by checking us out on <a href="https://github.com/stdlib-js/stdlib">GitHub</a>, and please consider <a href="https://opencollective.com/stdlib">financially supporting stdlib</a>. We greatly appreciate your continued support!</p>
+</details>
+
+# Doubly Linked List
+
+[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
+
+> Doubly linked list constructor.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="installation">
+
+## Installation
+
+```bash
+npm install @stdlib/dstructs-doubly-linked-list
+```
+
+</section>
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var doublyLinkedList = require( '@stdlib/dstructs-doubly-linked-list' );
+```
+
+#### doublyLinkedList()
+
+Returns a new doubly linked list instance.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+```
+
+##### list.clear()
+
+Clears a list.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Peek at the first value:
+var v = list.first().value;
+// returns 'foo'
+
+// Examine the list length:
+var len = list.length;
+// returns 2
+
+// Clear all list items:
+list.clear();
+
+// Peek at the first value:
+v = list.first();
+// returns undefined
+
+// Examine the list length:
+len = list.length;
+// returns 0
+```
+
+##### list.first()
+
+Returns the first `node`. If the list is currently empty, the returned value is `undefined`.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Peek at the first value:
+var v = list.first().value;
+// returns 'foo'
+```
+
+##### list.insert( node, value\[, location] )
+
+Inserts a `value` into the list either before or after a provided list `node`.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' ).push( 'beep' );
+
+// Determine the list length:
+var len = list.length;
+// returns 3
+
+// Get the second node:
+var node = list.first().next;
+
+// Insert a value after the second node:
+list.insert( node, 'boop' );
+
+// Determine the list length:
+len = list.length;
+// returns 4
+
+// Return a list of values:
+var values = list.toArray();
+// returns [ 'foo', 'bar', 'boop', 'beep' ]
+```
+
+The method supports the following insertion locations:
+
+-   `'before'`: insert a `value` into the list **before** a provided list `node`.
+-   `'after'`: insert a `value` into the list **after** a provided list `node`.
+
+By default, the method inserts a `value` into the list **after** a provided list `node`. To insert a value **before** a provided list `node`, invoke the method with the `location` argument equal to `'before'`.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' ).push( 'beep' );
+
+// Determine the list length:
+var len = list.length;
+// returns 3
+
+// Get the second node:
+var node = list.first().next;
+
+// Insert a value before the second node:
+list.insert( node, 'boop', 'before' );
+
+// Determine the list length:
+len = list.length;
+// returns 4
+
+// Return a list of values:
+var values = list.toArray();
+// returns [ 'foo', 'boop', 'bar', 'beep' ]
+```
+
+##### list.iterator( \[direction] )
+
+Returns an iterator for iterating over a list. If an environment supports `Symbol.iterator`, the returned iterator is iterable.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Create an iterator:
+var it = list.iterator();
+
+// Iterate over the list...
+var v = it.next().value;
+// returns 'foo'
+
+v = it.next().value;
+// returns 'bar'
+
+var bool = it.next().done;
+// returns true
+```
+
+The method supports the following iteration directions:
+
+-   `'forward'`: iterate over a list from the first value until the last value.
+-   `'reverse'`: iterate over a list from the last value until the first value.
+
+By default, the method returns an iterator which iterates over a list from the first value until the last value. To return an iterator which iterates in reverse order, invoke the method with the `direction` argument equal to `'reverse'`.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Create an iterator:
+var it = list.iterator( 'reverse' );
+
+// Iterate over the list...
+var v = it.next().value;
+// returns 'bar'
+
+v = it.next().value;
+// returns 'foo'
+
+var bool = it.next().done;
+// returns true
+```
+
+**Note**: in order to prevent confusion arising from list mutation during iteration, a returned iterator **always** iterates over a list "snapshot", which is defined as the list of list elements at the time of `list.iterator()` invocation.
+
+##### list.last()
+
+Returns the last `node`. If the list is currently empty, the returned value is `undefined`.
+
+```javascript
+var list = doublyLinkedList();
+// returns <DoublyLinkedList>
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Peek at the last value:
+var v = list.last().value;
+// returns 'bar'
+```
+
+##### list.length
+
+List length.
+
+```javascript
+var list = doublyLinkedList();
+
+// Examine the initial list length:
+var len = list.length;
+// returns 0
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Retrieve the current list length:
+len = list.length;
+// returns 2
+```
+
+##### list.pop()
+
+Removes a value from the end of the list. If the list is currently empty, the returned value is `undefined`.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Remove the last value:
+var v = list.pop();
+// returns 'bar'
+
+// Add a new value to the list:
+list.push( 'beep' );
+
+// Remove the last value:
+v = list.pop();
+// returns 'beep'
+```
+
+##### list.push( value )
+
+Adds a value to the end of the list.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Remove the last value:
+var v = list.pop();
+// returns 'bar'
+
+// Add a new value to the list:
+list.push( 'beep' );
+
+// Remove the last value:
+v = list.pop();
+// returns 'beep'
+```
+
+##### list.remove( node )
+
+Removes a `node` from the list.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' ).push( 'beep' );
+
+// Determine the list length:
+var len = list.length;
+// returns 3
+
+// Get the second node:
+var node = list.first().next;
+
+// Remove the second node:
+var v = list.remove( node );
+// returns 'bar'
+
+// Determine the list length:
+len = list.length;
+// returns 2
+```
+
+##### list.shift()
+
+Removes a value from the beginning of the list. If the list is currently empty, the returned value is `undefined`.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Remove the first value:
+var v = list.shift();
+// returns 'foo'
+
+// Add a new value to the list:
+list.push( 'beep' );
+
+// Remove the first value:
+v = list.shift();
+// returns 'bar'
+```
+
+##### list.toArray()
+
+Returns an array of list values.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Get an array of list values:
+var vals = list.toArray();
+// returns [ 'foo', 'bar' ]
+```
+
+##### list.toJSON()
+
+Serializes a list as JSON.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.push( 'foo' ).push( 'bar' );
+
+// Serialize to JSON:
+var o = list.toJSON();
+// returns { 'type': 'doubly-linked-list', 'data': [ 'foo', 'bar' ] }
+```
+
+**Note**: `JSON.stringify()` implicitly calls this method when stringifying a list instance.
+
+##### list.unshift( value )
+
+Adds a value to the beginning of the list.
+
+```javascript
+var list = doublyLinkedList();
+
+// Add values to the list:
+list.unshift( 'foo' ).unshift( 'bar' );
+
+// Remove the last value:
+var v = list.pop();
+// returns 'foo'
+
+// Add a new value to the list:
+list.unshift( 'beep' );
+
+// Remove the last value:
+v = list.pop();
+// returns 'bar'
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+-   To manually traverse a list, use list node `next` and `prev` properties.
+
+    ```javascript
+    var list = doublyLinkedList();
+
+    // Add values to the list:
+    list.push( 'foo' ).push( 'bar' ).push( 'beep' ).push( 'boop' );
+
+    // Get the first list node:
+    var n = list.first();
+
+    // Walk the list forward...
+    while ( n ) {
+        console.log( n.value );
+        n = n.next;
+    }
+
+    // Get the last list node:
+    n = list.last();
+
+    // Walk the list backward...
+    while ( n ) {
+        console.log( n.value );
+        n = n.prev;
+    }
+    ```
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var doublyLinkedList = require( '@stdlib/dstructs-doubly-linked-list' );
+
+var list;
+var iter;
+var len;
+var v;
+var i;
+
+// Create a new doubly linked list:
+list = doublyLinkedList();
+
+// Add some values to the list:
+list.push( 'foo' );
+list.push( 'bar' );
+list.push( 'beep' );
+list.push( 'boop' );
+
+// Peek at the first and last list values:
+v = list.first().value;
+// returns 'foo'
+
+v = list.last().value;
+// returns 'boop'
+
+// Inspect the list length:
+len = list.length;
+// returns 4
+
+// Remove the last list value:
+v = list.pop();
+// returns 'boop'
+
+// Inspect the list length:
+len = list.length;
+// returns 3
+
+// Iterate over the list:
+iter = list.iterator();
+for ( i = 0; i < len; i++ ) {
+    console.log( 'List value #%d: %s', i+1, iter.next().value );
+}
+
+// Clear the list:
+list.clear();
+
+// Inspect the list length:
+len = list.length;
+// returns 0
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/dstructs-linked-list`][@stdlib/dstructs/linked-list]</span><span class="delimiter">: </span><span class="description">linked list.</span>
+-   <span class="package-name">[`@stdlib/dstructs-stack`][@stdlib/dstructs/stack]</span><span class="delimiter">: </span><span class="description">stack.</span>
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+
+<section class="main-repo" >
+
+* * *
+
+## Notice
+
+This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.
+
+For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib].
+
+#### Community
+
+[![Chat][chat-image]][chat-url]
+
+---
+
+## License
+
+See [LICENSE][stdlib-license].
+
+
+## Copyright
+
+Copyright &copy; 2016-2026. The Stdlib [Authors][stdlib-authors].
+
+</section>
+
+<!-- /.stdlib -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[npm-image]: http://img.shields.io/npm/v/@stdlib/dstructs-doubly-linked-list.svg
+[npm-url]: https://npmjs.org/package/@stdlib/dstructs-doubly-linked-list
+
+[test-image]: https://github.com/stdlib-js/dstructs-doubly-linked-list/actions/workflows/test.yml/badge.svg?branch=v0.1.0
+[test-url]: https://github.com/stdlib-js/dstructs-doubly-linked-list/actions/workflows/test.yml?query=branch:v0.1.0
+
+[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/dstructs-doubly-linked-list/main.svg
+[coverage-url]: https://codecov.io/github/stdlib-js/dstructs-doubly-linked-list?branch=main
+
+<!--
+
+[dependencies-image]: https://img.shields.io/david/stdlib-js/dstructs-doubly-linked-list.svg
+[dependencies-url]: https://david-dm.org/stdlib-js/dstructs-doubly-linked-list/main
+
+-->
+
+[chat-image]: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
+[chat-url]: https://stdlib.zulipchat.com
+
+[stdlib]: https://github.com/stdlib-js/stdlib
+
+[stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors
+
+[umd]: https://github.com/umdjs/umd
+[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+
+[deno-url]: https://github.com/stdlib-js/dstructs-doubly-linked-list/tree/deno
+[deno-readme]: https://github.com/stdlib-js/dstructs-doubly-linked-list/blob/deno/README.md
+[umd-url]: https://github.com/stdlib-js/dstructs-doubly-linked-list/tree/umd
+[umd-readme]: https://github.com/stdlib-js/dstructs-doubly-linked-list/blob/umd/README.md
+[esm-url]: https://github.com/stdlib-js/dstructs-doubly-linked-list/tree/esm
+[esm-readme]: https://github.com/stdlib-js/dstructs-doubly-linked-list/blob/esm/README.md
+[branches-url]: https://github.com/stdlib-js/dstructs-doubly-linked-list/blob/main/branches.md
+
+[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/dstructs-doubly-linked-list/main/LICENSE
+
+<!-- <related-links> -->
+
+[@stdlib/dstructs/linked-list]: https://www.npmjs.com/package/@stdlib/dstructs-linked-list
+
+[@stdlib/dstructs/stack]: https://www.npmjs.com/package/@stdlib/dstructs-stack
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+> Policy for reporting security vulnerabilities.
+
+See the security policy [in the main project repository](https://github.com/stdlib-js/stdlib/security).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="../docs/types/index.d.ts" />
+import DoublyLinkedList from '../docs/types/index';
+export = DoublyLinkedList;

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";var v=function(s,t){return function(){return t||s((t={exports:{}}).exports,t),t.exports}};var c=v(function(L,p){"use strict";var o=require("@stdlib/utils-define-property");function A(s){return o(this,"next",{configurable:!1,enumerable:!0,get:function(){return this._next}}),o(this,"prev",{configurable:!1,enumerable:!0,get:function(){return this._prev}}),this.value=s,o(this,"_next",{configurable:!1,enumerable:!1,writable:!0,value:null}),o(this,"_prev",{configurable:!1,enumerable:!1,writable:!0,value:null}),this}p.exports=A});var d=v(function(S,y){"use strict";var l=require("@stdlib/utils-define-nonenumerable-read-only-property"),E=require("@stdlib/utils-define-nonenumerable-read-only-accessor"),g=require("@stdlib/symbol-iterator"),x=require("@stdlib/string-format"),_=c();function n(){return this instanceof n?(this._length=0,this._first=null,this._last=null,this):new n}l(n.prototype,"clear",function(){return this._length=0,this._first=null,this._last=null,this});l(n.prototype,"first",function(){if(this._length)return this._first});l(n.prototype,"insert",function(t,e,i){var a,r;if(arguments.length>2){if(a=i,a!=="before"&&a!=="after")throw new Error(x("invalid argument. Third argument must be a recognized location. Value: `%s`.",a))}else a="after";if(a==="after"&&t===this._last)return this.push(e);if(a==="before"&&t===this._first)return this.unshift(e);for(r=this._first;r!==this._last&&r!==t;)r=r._next;if(r===this._last&&r!==t)throw new Error("invalid argument. The list does not contain the provided list node.");return r=new _(e),a==="after"?(t._next._prev=r,r._next=t._next,t._next=r,r._prev=t):(t._prev._next=r,r._prev=t._prev,t._prev=r,r._next=t),this._length+=1,this});l(n.prototype,"iterator",function(t){var e,i,a,r,h,f,u;if(arguments.length){if(h=t,h!=="forward"&&h!=="reverse")throw new Error(x("invalid argument. Must provide a recognized iteration direction. Value: `%s`.",h))}else h="forward";return a=this,h==="forward"?(u=-1,f=1):(u=this._length,f=-1),e=this.toArray(),i={},l(i,"next",w),l(i,"return",m),g&&l(i,g,b),i;function w(){return u+=f,r||u<0||u>=e.length?{done:!0}:{value:e[u],done:!1}}function m(q){return r=!0,arguments.length?{value:q,done:!0}:{done:!0}}function b(){return a.iterator()}});l(n.prototype,"last",function(){if(this._length)return this._last});E(n.prototype,"length",function(){return this._length});l(n.prototype,"pop",function(){var t;return this._length&&(t=this._last.value,this._last._prev?(this._last=this._last._prev,this._last._next=null):(this._first=null,this._last=null),this._length-=1),t});l(n.prototype,"push",function(t){var e;return e=new _(t),this._length===0?(this._first=e,this._last=e):(e._prev=this._last,this._last._next=e,this._last=e),this._length+=1,this});l(n.prototype,"remove",function(t){var e,i;if(t===this._first)return this.shift();if(t===this._last)return this.pop();for(e=t.value,i=this._first;i!==this._last&&i!==t;)i=i._next;if(i===this._last)throw new Error("invalid argument. The list does not contain the provided list node.");return t._prev._next=t._next,t._next._prev=t._prev,this._length-=1,e});l(n.prototype,"shift",function(){var t;return this._length&&(t=this._first.value,this._first._next?(this._first=this._first._next,this._first._prev=null):(this._first=null,this._last=null),this._length-=1),t});l(n.prototype,"toArray",function(){var t,e,i;for(e=[],t=this._first,i=0;i<this._length;i++)e.push(t.value),t=t.next;return e});l(n.prototype,"toJSON",function(){var t={};return t.type="doubly-linked-list",t.data=this.toArray(),t});l(n.prototype,"unshift",function(t){var e;return e=new _(t),this._length===0?(this._first=e,this._last=e):(e._next=this._first,this._first._prev=e,this._first=e),this._length+=1,this});y.exports=n});var N=d();module.exports=N;
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2018 The Stdlib Authors.
+*
+* 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
+*
+*    http://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.
+*/
+//# sourceMappingURL=index.js.map