Description
Proposal
Problem statement
Integer primitives have functions such as overflowing_neg() for numeric negation with controlled overflow. These functions are currently missing from the core::num::NonZeroI{8,16,32,64} types.
Motivation, use-cases
Non-zero integers are frequently used to represent error codes from low-level OS APIs, because these APIs use 0 to indicate non-error. Some APIs use signed error codes as a form of namespacing, such as internal/public (FreeBSD) or kernel/userspace (Linux).
For example, the FUSE protocol uses userspace error codes (positive non-zero) but negates them when sending an error frame to the kernel.
// old
let (neg, _) = err.get().overflowing_neg();
let wire_neg = unsafe { NonZeroI32::new_unchecked(neg) };
// new
let (wire_neg, _) = err.overflowing_neg();Solution sketches
Since the primitive integer types already have *_neg() functions, and negation can't return zero for non-zero inputs, writing wrappers for the non-zero integers is straightforward.
pub const fn is_negative(self) -> bool {
self.get().is_negative()
}
pub const fn checked_neg(self) -> Option<$Ty> {
if let Some(result) = self.get().checked_neg() {
return Some(unsafe { $Ty::new_unchecked(result) });
}
None
}
pub const fn overflowing_neg(self) -> ($Ty, bool) {
let (result, overflow) = self.get().overflowing_neg();
((unsafe { $Ty::new_unchecked(result) }), overflow)
}
pub const fn saturating_neg(self) -> $Ty {
if let Some(result) = self.checked_neg() {
return result;
}
unsafe { $Ty::new_unchecked(<$Int>::MAX) }
}
pub const fn wrapping_neg(self) -> $Ty {
let result = self.get().wrapping_neg();
unsafe { $Ty::new_unchecked(result) }
}Links and related work
rust-lang/rust#89065
rust-lang/rust#84186
What happens now?
This issue is part of the libs-api team API change proposal process. Once this issue is filed the libs-api team will review open proposals in its weekly meeting. You should receive feedback within a week or two.