Skip to content

Commit

Permalink
docs: fix documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@joachimdekker
joachimdekker committed Jun 12, 2024
1 parent be8714a commit 0de528c
Showing 1 changed file with 145 additions and 97 deletions.
242 changes: 145 additions & 97 deletions Aplib.Core/Collections/ExposedQueue.cs
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;

namespace Aplib.Core.Collections
{
Expand All @@ -17,24 +16,54 @@ namespace Aplib.Core.Collections
/// </remarks>
public class ExposedQueue<T> : ICollection<T>
{
/// <summary>
/// The length of the array.
/// </summary>
public int MaxCount { get; private set; }

/// <summary>
/// Actual number of elements in the array.
/// </summary>
public int Count { get; private set; }

/// <inheritdoc/>
/// <inheritdoc />
public bool IsReadOnly => false;

/// <summary>
/// The length of the array.
/// </summary>
public int MaxCount { get; }

private readonly T[] _array;
private int _head;

/// <summary>
/// Initializes a new empty instance of the <see cref="ExposedQueue{T}"/> class.
/// Gets the element at the specified index. Throws an exception if the index is out of bounds.
/// </summary>
/// <param name="index">The index of the element to get.</param>
/// <returns>The element at the specified index.</returns>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the index is out of range.
/// </exception>
public T this[int index]
{
get
{
if (index < 0 || index >= Count)
{
throw new ArgumentOutOfRangeException(nameof(index));
}

return _array[(index + _head + 1) % MaxCount];
}
private set
{
if (index < 0 || index >= Count)
{
throw new ArgumentOutOfRangeException(nameof(index));
}

_array[(index + _head + 1) % MaxCount] = value;
}
}

/// <summary>
/// Initializes a new empty instance of the <see cref="ExposedQueue{T}" /> class.
/// </summary>
/// <param name="size">The maximum size of the queue.</param>
public ExposedQueue(int size)
Expand All @@ -45,20 +74,23 @@ public ExposedQueue(int size)
_head = MaxCount - 1;
}


/// <summary>
/// Initializes a new instance of the <see cref="ExposedQueue{T}" /> class
/// with an array to use as basis for the queue.
/// By default, assumes the array is filled.
/// Initializes a new instance of the <see cref="ExposedQueue{T}" /> class with an array.
/// </summary>
/// <param name="array">An array to use as the circular array.</param>
/// <param name="maxCount">The number of actual elements in the array.</param>
/// <param name="array">The array to initialize the queue with.</param>
/// <param name="maxCount">The maximum count of the queue.</param>
/// <remarks>
/// The MaxCount of the queue will be set to the length of the array.
/// If the array is not fully filled, the Count should be specified.
/// The array will be copied to the queue, and the head will be set to the last element of the array.
/// This method expects the array to be filled.
/// </remarks>
/// <exception cref="ArgumentOutOfRangeException">Thrown when the max count is negative.</exception>
public ExposedQueue(T[] array, int maxCount)
{
if (maxCount < 0) throw new ArgumentOutOfRangeException(nameof(maxCount), "Count cannot be negative.");
if (maxCount < 0)
{
throw new ArgumentOutOfRangeException(nameof(maxCount), "Count cannot be negative.");
}

MaxCount = maxCount;
Count = Math.Min(array.Length, maxCount);
Expand All @@ -75,53 +107,34 @@ public ExposedQueue(T[] array)
{
}

/// <summary>
/// Gets the element at the specified index. Throws an exception if the index is out of bounds.
/// </summary>
/// <param name="index">The index of the element to get.</param>
/// <returns>The element at the specified index.</returns>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when the index is out of range.
/// </exception>
public T this[int index]
/// <inheritdoc />
public void Add(T item) => Put(item);

/// <inheritdoc />
public void Clear()
{
get
{
if (index < 0 || index >= Count) throw new ArgumentOutOfRangeException(nameof(index));
return _array[(index + _head + 1) % MaxCount];
}
private set
for (int i = 0; i < MaxCount; i++)
{
if (index < 0 || index >= Count) throw new ArgumentOutOfRangeException(nameof(index));
_array[(index + _head + 1) % MaxCount] = value;
_array[i] = default!;
}
}

/// <summary>
/// Puts an element at the start of the queue.
/// </summary>
/// <param name="value">The element to add to the queue.</param>
public void Put(T value)
{
_array[_head] = value;
DecrementHead();
if (Count < MaxCount) Count++;
_head = MaxCount - 1;
Count = 0;
}

/// <inheritdoc/>
public void Add(T item) => Put(item);

/// <summary>
/// Gets the element at the end of the queue.
/// </summary>
/// <returns>The element at the end of the queue.</returns>
public T GetLast() => _array[_head];
/// <inheritdoc />
public bool Contains(T item)
{
for (int i = 0; i < Count; i++)
{
if (this[i]!.Equals(item))
{
return true;
}
}

/// <summary>
/// Gets the first element of the queue.
/// </summary>
/// <returns>The first element of the queue.</returns>
public T GetFirst() => this[0];
return false;
}

/// <summary>
/// Copies the ExposedQueue to an array.
Expand All @@ -134,57 +147,63 @@ public void Put(T value)
/// <returns>The ExposedQueue as a regular array.</returns>
public void CopyTo(T[] array, int arrayIndex, int endIndex)
{
if (arrayIndex < 0 || arrayIndex >= Count) throw new ArgumentOutOfRangeException(nameof(arrayIndex));
if (endIndex < 0 || endIndex >= Count) throw new ArgumentOutOfRangeException(nameof(endIndex));
if (arrayIndex < 0 || arrayIndex >= Count)
{
throw new ArgumentOutOfRangeException(nameof(arrayIndex));
}

if (endIndex < 0 || endIndex >= Count)
{
throw new ArgumentOutOfRangeException(nameof(endIndex));
}

if (arrayIndex > endIndex)
{
throw new ArgumentException("Start index must be less than or equal to end index.");
}

for (int i = 0; i < endIndex - arrayIndex + 1; i++) array[i] = this[arrayIndex + i];
for (int i = 0; i < endIndex - arrayIndex + 1; i++)
{
array[i] = this[arrayIndex + i];
}
}

/// <inheritdoc/>
/// <inheritdoc />
public void CopyTo(T[] array, int arrayIndex) => CopyTo(array, arrayIndex, arrayIndex + Count - 1);

/// <summary>
/// Converts the ExposedQueue to an array.
/// </summary>
/// <param name="start">The start index of the range to convert.</param>
/// <param name="end">The end index of the range to convert.</param>
/// <returns>An array containing the elements within the specified range.</returns>
public T[] ToArray(int start, int end)
/// <inheritdoc />
public IEnumerator<T> GetEnumerator()
{
if (start < 0 || start >= Count)
throw new ArgumentOutOfRangeException(nameof(start),
"Start index must be within the bounds of the array."
);
if (end < 0 || end >= Count)
throw new ArgumentOutOfRangeException(nameof(end), "End index must be within the bounds of the array.");
T[] result = new T[end - start + 1];
CopyTo(result, start, end);
return result;
for (int i = 0; i < Count; i++)
{
yield return this[i];
}
}

/// <summary>
/// Converts the ExposedQueue to an array. Only returns the used slots.
/// Gets the first element of the queue.
/// </summary>
/// <returns>An array containing the elements within the specified range.</returns>
public T[] ToArray() => ToArray(0, Count - 1);
/// <returns>The first element of the queue.</returns>
public T GetFirst() => this[0];

/// <inheritdoc/>
public void Clear()
{
for (int i = 0; i < MaxCount; i++) _array[i] = default!;
_head = MaxCount - 1;
Count = 0;
}
/// <summary>
/// Gets the element at the end of the queue.
/// </summary>
/// <returns>The element at the end of the queue.</returns>
public T GetLast() => _array[_head];

/// <inheritdoc/>
public bool Contains(T item)
/// <summary>
/// Puts an element at the start of the queue.
/// </summary>
/// <param name="value">The element to add to the queue.</param>
public void Put(T value)
{
for (int i = 0; i < Count; i++)
if (this[i]!.Equals(item))
return true;
return false;
_array[_head] = value;
DecrementHead();
if (Count < MaxCount)
{
Count++;
}
}

/// <summary>
Expand All @@ -210,27 +229,56 @@ public bool Remove(T item)
return false;
}

/// <inheritdoc/>
public IEnumerator<T> GetEnumerator()
/// <summary>
/// Converts the ExposedQueue to an array.
/// </summary>
/// <param name="start">The start index of the range to convert.</param>
/// <param name="end">The end index of the range to convert.</param>
/// <returns>An array containing the elements within the specified range.</returns>
public T[] ToArray(int start, int end)
{
for (int i = 0; i < Count; i++) yield return this[i];
if (start < 0 || start >= Count)
{
throw new ArgumentOutOfRangeException(nameof(start),
"Start index must be within the bounds of the array."
);
}

if (end < 0 || end >= Count)
{
throw new ArgumentOutOfRangeException(nameof(end), "End index must be within the bounds of the array.");
}

T[] result = new T[end - start + 1];
CopyTo(result, start, end);
return result;
}

IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
/// <summary>
/// Converts the ExposedQueue to an array. Only returns the used slots.
/// </summary>
/// <returns>An array containing the elements within the specified range.</returns>
public T[] ToArray() => ToArray(0, Count - 1);

/// <summary>
/// Decrements the head of the array.
/// </summary>
private void DecrementHead() => _head = (_head - 1 + MaxCount) % MaxCount;

IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();

/// <summary>
/// Removes the element at the specified index.
/// Shifts all other elements to the left.
/// </summary>
/// <param name="index">The index of the element to remove.</param>
private void RemoveAt(int index)
{
for (int i = index; i < Count - 1; i++) this[i] = this[i + 1];
for (int i = index; i < Count - 1; i++)
{
this[i] = this[i + 1];
}

Count--;
}
}
Expand Down

0 comments on commit 0de528c

Please sign in to comment.