From bfaf9cd6ebc48d931162774ae3b12703af963b72 Mon Sep 17 00:00:00 2001
From: Daniel Imms <daimms@microsoft.com>
Date: Wed, 21 Dec 2016 02:39:21 -0800
Subject: [PATCH] Doc and testing

---
 src/utils/CircularList.test.ts | 28 ++++++++++++++++++++++++++++
 src/utils/CircularList.ts      | 32 +++++++++++++++++++++++++++-----
 2 files changed, 55 insertions(+), 5 deletions(-)

diff --git a/src/utils/CircularList.test.ts b/src/utils/CircularList.test.ts
index 3b2520ab..41bb8299 100644
--- a/src/utils/CircularList.test.ts
+++ b/src/utils/CircularList.test.ts
@@ -128,4 +128,32 @@ describe('CircularList', () => {
       assert.equal(list.get(2), '2');
     });
   });
+
+  describe('trimStart', () => {
+    it('should remove items from the beginning of the list', () => {
+      const list = new CircularList<string>(5);
+      list.push('1');
+      list.push('2');
+      list.push('3');
+      list.push('4');
+      list.push('5');
+      list.trimStart(1);
+      assert.equal(list.length, 4);
+      assert.deepEqual(list.get(0), '2');
+      assert.deepEqual(list.get(1), '3');
+      assert.deepEqual(list.get(2), '4');
+      assert.deepEqual(list.get(3), '5');
+      list.trimStart(2);
+      assert.equal(list.length, 2);
+      assert.deepEqual(list.get(0), '4');
+      assert.deepEqual(list.get(1), '5');
+    });
+
+    it('should remove all items if the requested trim amount is larger than the list\'s length', () => {
+      const list = new CircularList<string>(5);
+      list.push('1');
+      list.trimStart(2);
+      assert.equal(list.length, 0);
+    });
+  });
 });
diff --git a/src/utils/CircularList.ts b/src/utils/CircularList.ts
index ce79e35c..1056c21e 100644
--- a/src/utils/CircularList.ts
+++ b/src/utils/CircularList.ts
@@ -92,12 +92,23 @@ export class CircularList<T> {
     }
   }
 
+  /**
+   * Removes and returns the last value on the list.
+   * @return The popped value.
+   */
   public pop(): T {
-    // TODO: This isn't popping from the array, only returning
     return this._array[this._getCyclicIndex(this._length-- - 1)];
   }
 
-  // TODO: Warn there's no error handling and that this is a slow operation
+  /**
+   * Deletes and/or inserts items at a particular index (in that order). Unlike
+   * Array.prototype.splice, this operation does not return the deleted items as a new array in
+   * order to save creating a new array. Note that this operation may shift all values in the list
+   * in the worst case.
+   * @param start The index to delete and/or insert.
+   * @param deleteCount The number of elements to delete.
+   * @param items The items to insert.
+   */
   public splice(start: number, deleteCount: number, ...items: T[]): void {
     if (deleteCount) {
       for (let i = start; i < this._length - deleteCount; i++) {
@@ -122,13 +133,24 @@ export class CircularList<T> {
     }
   }
 
+  /**
+   * Trims a number of items from the start of the list.
+   * @param count The number of items to remove.
+   */
   public trimStart(count: number): void {
-    // TODO: Error handling
-    // TODO: Testing (if we need this)
+    if (count > this._length) {
+      count = this._length;
+    }
     this._startIndex += count;
-    this._length--;
+    this._length -= count;
   }
 
+  /**
+   * Gets the cyclic index for the specified regular index. The cyclic index can then be used on the
+   * backing array to get the element associated with the regular index.
+   * @param index The regular index.
+   * @returns The cyclic index.
+   */
   private _getCyclicIndex(index: number): number {
     return (this._startIndex + index) % this.maxLength;
   }