stack.js

/**
 * Function constructor of a stack.
 * 
 * @example const Stack = require('dstructures').Stack; 
 * const myStack = new Stack();
 * @description In computer science, a stack is an abstract data type that serves as a 
 * collection of elements, with two principal operations:
 * push, which adds an element to the collection, and
 * pop, which removes the most recently added element that was not yet removed.
 * The order in which elements come off a stack gives rise to its alternative name, 
 * LIFO (last in, first out). Additionally, a peek operation may give access to the top without modifying the stack.
 * Full wikipedia article at: 
 * {@link https://en.wikipedia.org/wiki/Stack_(abstract_data_type)}
 * @public
 * @constructor
 */
  class Stack {
    constructor() {
      const container = [];
      let top = 0;

    this._getContainer = () => container;
    this._getTop = () => top;
    this._topPlus = () => top++;
    this._topMinus = () => --top;
    this._clearTop = () => top = 0;
  }
    /**
   * Adds element in a stack.
   * 
   * @param {any} element Given element.
   * @returns {Boolean|Void} Returns fasle if the given element is undefined.
   * @example [] Stack.push('Cat'); // ['Cat']
   * ['Cat'] Stack.push('Dog'); // ['Cat', 'Dog']         
   */     
  push (element) {
    if (element === undefined) {
      return false;
    }
    this._getContainer()[this._topPlus()] = element;
  }

  /**
   * Removes and returns the topmost element.
   * 
   * @returns {Boolean|Any} Returns the removed element if the stack is not empty. Otherwise returns false.
   * @example ['Cat', 'Dog', 'Deer'] Stack.pop(); // 'Deer'
   * ['Cat', 'Dog'] Stack.pop(); // 'Dog'
   */
  pop () {
    if (this._getTop() !== 0) {
      return this._getContainer()[this._topMinus()];
    }
    return false;
  }

  /**
   * Returns the topmost element of a stack.
   * 
   * @returns {Boolean|Void} Returns the topmost element if the stack is not empty. Otherwise returns falsse.
   * @example ['Cat', 'Dog'] Stack.peek(); // 'Dog'
   * ['Pig','Cat'] Stack.peek(); // 'Cat'
   */
  peek () {
    if (this._getTop() !== 0) {
      return this._getContainer()[this._getTop() - 1];
    }
    return false;
  }

  /**
   * Deletes all elements in a stack.
   * @example ['Cat', 'Dog'] Stack.clear(); // []
   */
  clear () {
    this._clearTop();
  }

  /**
   * Returns the length of a stack.
   * 
   * @returns {Number} Returns the length of a stack.
   * @example [] Stack.length(); // 0
   * ['Cat'] Stack.length(); // 1
   */
  length () {
    return this._getTop();
  }

  /**
   * Returns array representation of a stack.
   * 
   * @returns {Array} Returns array representation of a stack.
   */
  toArray () {
    return this._getContainer();
  }

}
module.exports = Stack;