如何实现将数值正确包裹在左闭右开[range)区间的函数？

问题背景 #

需要实现一个函数，将任意输入值包裹到**左闭右开区间（[lower, upper)）**内，输出结果必须始终落在该区间内。预期行为示例：

• 4.9.wrapped(within: 3..<5) 返回 4.9
• 5.wrapped(within: 3..<5) 返回 3

当前实现的算法在输入值大于等于区间下界时工作正常，但输入值小于下界时，输出会错误落入(lower, upper]区间（例如区间为[3,5)时，输入1得到的结果落在(3,5]范围内）。

当前实现代码 #

Swift 示例代码

public extension FloatingPoint {
    
    func wrapped(within range: Range<Self>) -> Self {
        
        let breadth = range.upperBound - range.lowerBound
        
        let offset: Self 
        if self < range.lowerBound {
            offset = breadth
        }
        else {
            offset = 0
        }
        
        let baseResult = (self - range.lowerBound).truncatingRemainder(dividingBy: breadth)

        return baseResult + range.lowerBound + offset
    }
}

伪代码示例

function (value: Number, rangeLowerBoundInclusive: Number, rangeUpperBoundExclusive: Number) returns Number {

    let breadth be (rangeUpperBoundExclusive - rangeLowerBoundInclusive)

    if (value is less than rangeLowerBoundInclusive)
        let offset be breadth
    else
        let offset be 0

    let baseResult be ((value - rangeLowerBoundInclusive) mod breadth)
    
    return baseResult + rangeLowerBoundInclusive + offset
}

输出问题表现 #

当区间为[3,5)，输入值从-10到10、步长0.1时，输出呈现锯齿状异常：

• 输入值≥3.0时，输出落在[3,5)区间，符合预期；
• 输入值<3.0时，输出落在(3,5]区间，区间开闭性翻转，不符合要求。

问题原因 #

问题根源在于负数取余的行为和错误的offset逻辑：

1. 当输入值小于区间下界时，self - range.lowerBound为负数，truncatingRemainder(dividingBy: breadth)会返回与被除数同符号的余数，范围是(-breadth, 0]；
2. 此时加上offset=breadth后，结果范围变为(0, breadth]，再加上区间下界就得到(lower, upper]，直接翻转了原区间的开闭性；
3. 极端情况如输入值刚好是下界减去整数倍区间长度时，会得到upper值（比如输入1，1-3=-2，取余2得0，加3加2得5），而upper是左闭右开区间的排除值，不符合要求。

修复方案 #

移除多余的offset判断逻辑，直接对取余后的结果进行归一化处理：如果余数为负，就加上区间长度breadth，将余数范围统一调整到[0, breadth)，再平移回原区间即可。

修正后的Swift代码 #

public extension FloatingPoint {
    func wrapped(within range: Range<Self>) -> Self {
        let lower = range.lowerBound
        let upper = range.upperBound
        let breadth = upper - lower
        
        let shifted = self - lower
        let remainder = shifted.truncatingRemainder(dividingBy: breadth)
        
        let normalizedRemainder = remainder >= 0 ? remainder : remainder + breadth
        return normalizedRemainder + lower
    }
}

逻辑说明 #

1. 平移区间：将输入值减去区间下界，把原区间[lower, upper)转换为以0为起点的[0, breadth)区间；
2. 取余运算：对平移后的值取余，得到范围在(-breadth, breadth)内的余数；
3. 归一化余数：将负余数加上breadth，确保所有余数落在[0, breadth)范围内；
4. 平移回原区间：将归一化后的余数加上区间下界，得到最终落在[lower, upper)内的结果。

验证示例 #

• 输入5：5-3=2 → 2%2=0 → 0+3=3（符合预期）
• 输入1：1-3=-2 → -2%2=0 → 0+3=3（符合预期）
• 输入2：2-3=-1 → -1%2=-1 → -1+2=1 → 1+3=4（在[3,5)内，符合预期）
• 输入4.9：4.9-3=1.9 → 1.9%2=1.9 → 1.9+3=4.9（符合预期）

内容的提问来源于stack exchange，提问作者Ky -