Function clamp_dec 

pub fn clamp_dec(x: f64) -> f64

Clamps an angle to [-pi/2, +pi/2] radians (i.e., [-90, +90] degrees).

Unlike wrapping, clamping saturates at the limits. This is appropriate for quantities that have physical bounds you cannot exceed.

Arguments

• x - Angle in radians

Returns

The angle clamped to [-pi/2, +pi/2].

When to Use

• Declination: celestial latitude, poles are at +/-90 degrees
• Geographic latitude: -90 (south pole) to +90 (north pole)
• Altitude: horizon at 0, zenith at +90 (though altitude can be negative)

Why Clamp Instead of Wrap?

You cannot go “past” the north pole by walking north. If you try, you end up walking south on the other side. This is fundamentally different from longitude, where walking east forever eventually brings you back to where you started.

Clamping is a safety mechanism. If your calculation produces declination = 100 degrees, something is wrong upstream. Clamping to 90 degrees prevents downstream code from breaking, but you should investigate why the input was out of range.

Examples

use celestial_core::angle::clamp_dec;
use std::f64::consts::FRAC_PI_2;

// Within range: unchanged
let x = clamp_dec(0.5);
assert!((x - 0.5).abs() < 1e-10);

// Above +90 degrees: clamped to +90
let y = clamp_dec(2.0);
assert!((y - FRAC_PI_2).abs() < 1e-10);

// Below -90 degrees: clamped to -90
let z = clamp_dec(-2.0);
assert!((z - (-FRAC_PI_2)).abs() < 1e-10);

See Also

For declinations that might legitimately exceed +/-90 degrees (e.g., pier-flipped telescope positions), see the validation functions in the validate module which offer extended range options.