[swift-evolution] [draft] Add `clamped(to:)` to the stdlib

Nicholas Maccharoli nmaccharoli at gmail.com
Sun Mar 12 12:16:53 CDT 2017


This is a draft of a proposal adding `clamped(to:)` as an extension on
For now I have only included a version of the `clamped(to:)` function that
accepts `ClosedRange` but if the community decided that it is feasible to
add a version that takes half open ranges I would also love to include that
as well in this proposal.

That you so much for the feedback so far and I am looking forward
to the community's feedback on this draft.

- Nick

Add clamp
(to:) to the stdlib

   - Proposal: SE-NNNN
   - Authors: Nicholas Maccharoli <https://github.com/Nirma>
   - Review Manager: TBD
   - Status: Awaiting review

*During the review process, add the following fields as needed:*

   - Decision Notes: Rationale
   <https://lists.swift.org/pipermail/swift-evolution/>, Additional
   Commentary <https://lists.swift.org/pipermail/swift-evolution/>
   - Bugs: SR-NNNN <https://bugs.swift.org/browse/SR-NNNN>, SR-MMMM
   - Previous Revision: 1
   - Previous Proposal: SE-XXXX


This proposal aims to add functionality to the standard library for
clamping a value to a ClosedRange. The proposed function would allow the
user to specify a range to clamp a value to where if the value fell within
the range, the value would be returned as is, if the value being clamped
exceeded the upper or lower bound in value the value of the boundary the
value exceeded would be returned.

Swift-evolution thread: Add a clamp function to Algorithm.swift

There have been quite a few times in my professional and personal
programming life where I reached for a clampedfunction and was disappointed
it was not part of the standard library.

Having functionality like clamped(to:) added to Comparable as a protocol
extension would benefit users of the Swift language who wish to guarantee
that a value is kept within bounds.

The solution proposed is simply that there be a clamped(to:) function added
to the Swift Standard Library. The function would behave much like its name

Given a clamped(to:) function existed it could be called in the following
way, yielding the results in the adjacent comments:

var foo = 100
foo.clamp(to: 0...50) // 50foo.clamp(to: 200...300) //
200foo.clamp(to: 0...150) // 100


The implementation for clamped(to:) as an extension to Comparable accepting
a range of type ClosedRange<Self>would look like the following:

extension Comparable {
    func clamped(to range: ClosedRange<Self>) -> Self {
        if self > range.upperBound {
            return range.upperBound
        } else if self < range.lowerBound {
            return range.lowerBound
        } else {
            return self


This feature is purely additive; it has no effect on source compatibility.
on ABI stability

This feature is purely additive; it has no effect on ABI stability.
on API resilience

The proposed function would become part of the API but purely additive.
clamped(to:) could be made a global function like min and max but a
protocol extension seems like a better choice.​
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170313/d4fcfc0c/attachment.html>

More information about the swift-evolution mailing list