pub trait Pow<ExponentType>: Sized {
type Error: Error;
// Required methods
fn try_pow(self, exponent: ExponentType) -> Result<Self, Self::Error>;
fn pow(self, exponent: ExponentType) -> Self;
}
Expand description
A trait for computing the power of a number (base^exponent
).
This trait provides an interface for raising a Self
type (the base)
to a power specified by ExponentType
. It includes both a fallible version
(try_pow
) that performs validation and an infallible version (pow
) that
may panic in debug builds if validation fails.
§Type Parameters
ExponentType
: The type of the exponent. This can be a real number type (likef64
orRealRugStrictFinite<P>
) or an integer type (likei32
,u32
, etc.).
Required Associated Types§
Required Methods§
Sourcefn try_pow(self, exponent: ExponentType) -> Result<Self, Self::Error>
fn try_pow(self, exponent: ExponentType) -> Result<Self, Self::Error>
Attempts to compute self
(the base) raised to the power of exponent
.
This method performs validation on the base and exponent according to
defined policies (e.g., StrictFinitePolicy
).
It also checks for domain errors specific to the power operation, such as
a negative real base with a non-integer real exponent, or a zero base
with a negative exponent. Finally, it validates the computed result.
§Arguments
exponent
: The exponent to raiseself
to.
Sourcefn pow(self, exponent: ExponentType) -> Self
fn pow(self, exponent: ExponentType) -> Self
Computes self
(the base) raised to the power of exponent
.
This method provides a potentially more performant way to compute the power,
especially in release builds, by possibly omitting some checks performed by
try_pow
.
§Behavior
- In debug builds, this method typically calls
try_pow(exponent).unwrap()
, meaning it will panic iftry_pow
would return an error. - In release builds, it may call the underlying power function directly.
While input validation might be skipped, output validation (e.g., checking
if the result is finite) might still occur implicitly if the underlying
power function produces non-finite results (like NaN or Infinity) from
finite inputs, which are then caught by policies like
StrictFinitePolicy
if applied to the output.
§Arguments
exponent
: The exponent to raiseself
to.
§Returns
The result of self
raised to the power of exponent
.
§Panics
- Panics in debug builds if
try_pow
would return an error. - Behavior regarding panics in release builds depends on the specific
implementation and the underlying power function. For example,
f64::powf
itself does not panic but can returnNaN
orInfinity
.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.