Add fixed-capacity support to Deque with ring buffer semantics

[ekansh28]

Implements a complete fixed-capacity Deque feature (issue #309), providing ring buffer behavior backed by contiguous memory.

Core Features:

• Added Deque<T>(fixedCapacity:) initializer for bounded deques.
• Implemented ring buffer semantics: • append(_:) removes the oldest element when full. • prepend(_:) removes the newest element when full.
• Introduced helper properties: • maxCapacity • isFixedCapacity • isFull • remainingCapacity
• Ensured full backward compatibility — existing unbounded deques continue to function unchanged.

Behavior:

• Example: [1, 2, 3] → append(4) → [2, 3, 4]
• Example: [1, 2, 3] → prepend(0) → [0, 1, 2]

Test Coverage:

• Property validation (capacity, fullness, etc.)
• Append/prepend ring buffer behavior
• Precondition validation
• Integration tests with existing Deque functionality

This change delivers the requested feature for high-performance systems that need bounded memory collections. It follows Swift Collections’ coding and documentation conventions, while maintaining O(1) amortized performance guarantees.

Replace this paragraph with a description of your changes and rationale. Provide links to an existing issue or external references/discussions, if appropriate.

Checklist

• I've read the Contribution Guidelines
• My contributions are licensed under the Swift license.
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (if appropriate).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexplained benchmark regressions.
• I've updated the documentation if necessary.

[ekansh28]

@lorentey

[lorentey]

Thanks for working on this. Unfortunately it is unlikely we will land this in this form -- we're preparing to ship new, ownership aware Deque variants, including a fixed-capacity RigidDeque type that is likely to be a better approach overall.

A (somewhat outdated) work-in-progress draft of RigidDeque is available on the future branch; this type is designed to provide clients with full control over all aspects of allocation behavior.

The impending 1.3.0 release will ship RigidArray as the first step towards fleshing out a full suite of these Rigid* types; I hope a production-ready RigidDeque will quickly follow in a subsequent update.

[lorentey]

For RigidArray and RigidDeque (and later RigidSet, RigidDictionary etc) I've been using the name freeCapacity for the same property.

It feels like your name may be a better choice! I'll sleep on it -- we may want RigidArray to adopt this before we ship 1.3.0.

[lorentey]

D'oh, we have already established the freeCapacity name in the OutputSpan type that has shipped in Swift 6.2's stdlib.

Oh well; remainingCapacity feels better, but it's better to be consistent than perfect.

[aluco100]

could it better using !elements.isEmpty in the guard condition?

[lorentey]

No; we need to know the count to allocate enough storage.

When the collection happens to be empty, it does not matter whether we call count or isEmpty -- both operations have constant complexity in that case.

[lorentey]

Thanks for working on this. Unfortunately it is unlikely we will land this in this form -- we're preparing to ship new, ownership aware Deque variants, including a fixed-capacity RigidDeque type that is likely to be a better approach overall.

A (somewhat outdated) work-in-progress draft of RigidDeque is available on the future branch; this type is designed to provide clients with full control over all aspects of allocation behavior.

The impending 1.3.0 release will ship RigidArray as the first step towards fleshing out a full suite of these Rigid* types; I hope a production-ready RigidDeque will quickly follow in a subsequent update.

As foretold above, version 1.4.0 of swift-collections has shipped RigidDeque and UniqueDeque. RigidDeque provides a strict fixed-capacity ring buffer implementation, with API carefully designed specifically for that use case.

Thanks again for pushing this!