Struct PositiveRealScalar 

pub struct PositiveRealScalar<RealType: RealScalar>(/* private fields */);

Type-safe wrapper for strictly positive real scalar values.

PositiveRealScalar<T> guarantees that wrapped values are strictly greater than zero. Zero is not valid for this type. For values that can be zero, use NonNegativeRealScalar.

Mathematical Definition

PositiveRealScalar<T> = { x ∈ T : x > 0 }

This is the set of positive real numbers ℝ⁺, which excludes zero.

Use Cases

• Lengths and distances that cannot be zero
• Positive tolerances
• Scaling factors that must be positive
• Any quantity that is mathematically required to be > 0

Examples

Basic Usage

use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
use try_create::TryNew;

// Valid positive values
let length = PositiveRealScalar::try_new(2.5_f64).unwrap();
let tiny = PositiveRealScalar::try_new(f64::MIN_POSITIVE).unwrap();

// Zero is NOT positive
assert!(matches!(
    PositiveRealScalar::try_new(0.0_f64),
    Err(ErrorsPositiveRealScalar::ZeroValue { .. })
));

// Negative values rejected
assert!(matches!(
    PositiveRealScalar::try_new(-1.0_f64),
    Err(ErrorsPositiveRealScalar::NegativeValue { .. })
));

Difference from NonNegativeRealScalar

use num_valid::scalars::{PositiveRealScalar, NonNegativeRealScalar};
use try_create::TryNew;

// Zero is INVALID for PositiveRealScalar (x > 0)
assert!(PositiveRealScalar::try_new(0.0_f64).is_err());

// Zero is VALID for NonNegativeRealScalar (x ≥ 0)
assert!(NonNegativeRealScalar::try_new(0.0_f64).is_ok());

Algebraic and Ordering Operations

PositiveRealScalar supports:

• Addition: Sum of positive values is positive
• Multiplication: Product of positive values is positive
• Integer powers: Raising positive to any integer exponent yields positive
• Square root: Preserves positivity (√x > 0 if x > 0)
• Multiplicative identity (One): For neutral multiplication operations
• Comparison (Max, Min): Ordering and selection helpers

use num::One;
use num_valid::{
    *,
    functions::{Max, Min, Pow},
    scalars::PositiveRealScalar,
};
use try_create::{IntoInner, TryNew};

let a = PositiveRealScalar::try_new(2.0_f64).unwrap();
let b = PositiveRealScalar::try_new(3.0_f64).unwrap();

// Add preserves positivity for valid operands.
let sum = a.clone() + b.clone();
assert_eq!(*sum.as_raw_scalar_ref(), 5.0);

// Multiply preserves positivity
let product = a.clone() * b.clone();
assert_eq!(*product.as_raw_scalar_ref(), 6.0);

// Integer powers preserve positivity
let squared = a.clone().pow(2u32);
assert_eq!(*squared.as_raw_scalar_ref(), 4.0);

// Square root preserves positivity
let sqrt = PositiveRealScalar::try_new(4.0_f64).unwrap().sqrt();
assert_eq!(*sqrt.as_raw_scalar_ref(), 2.0);

// One is the multiplicative identity.
let one = PositiveRealScalar::<f64>::one();
let result = a.clone() * one;
assert_eq!(*result.as_raw_scalar_ref(), 2.0);

let x = PositiveRealScalar::try_new(1.0_f64).unwrap();
let y = PositiveRealScalar::try_new(3.0_f64).unwrap();
assert_eq!(*Max::max_by_ref(&x, &y).as_raw_scalar_ref(), 3.0);
assert_eq!(*Min::min_by_value(x, y).as_raw_scalar_ref(), 1.0);

Implementations

impl<RealType: RealScalar> PositiveRealScalar<RealType>

pub fn into_inner(self) -> RealType

Consumes the struct and returns the inner value.

impl<RealType: RealScalar> PositiveRealScalar<RealType>

pub fn sqrt(self) -> Self

Computes the square root of this positive scalar.

Since the input is guaranteed to be positive, the result is always defined and remains positive.

Examples

use num_valid::{*, scalars::PositiveRealScalar};
use try_create::TryNew;

let value = PositiveRealScalar::try_new(4.0_f64).unwrap();
let sqrt = value.sqrt();
assert_eq!(sqrt.as_raw_scalar_ref(), &2.0);

pub fn new(value: RealType) -> Self

Trait Implementations

impl<RealType: RealScalar> Add for PositiveRealScalar<RealType>

Implements additive composition for PositiveRealScalar.

Since both operands are guaranteed to be positive, their sum is also positive.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self

Performs the + operation.

impl<'a, RealType: RealScalar> Add<&'a NonNegativeRealScalar<RealType>> for PositiveRealScalar<RealType>

Adds a NonNegativeRealScalar by reference to a PositiveRealScalar, yielding a PositiveRealScalar.

Since self is strictly positive (x > 0) and other is non-negative (y ≥ 0), their sum is strictly positive: x + y > 0.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add( self, other: &'a NonNegativeRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the + operation.

impl<'a, RealType: RealScalar> Add<&'a PositiveRealScalar<RealType>> for PositiveRealScalar<RealType>

Implements reference-based addition for PositiveRealScalar.

This allows adding a reference to a positive scalar without consuming it. Since both operands are guaranteed to be positive, their sum is also positive.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add( self, other: &'a PositiveRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the + operation.

impl<'a, RealType: RealScalar> Add<&'a PositiveRealScalar<RealType>> for NonNegativeRealScalar<RealType>

Adds a PositiveRealScalar by reference to a NonNegativeRealScalar, yielding a PositiveRealScalar.

Since other is strictly positive (x > 0) and self is non-negative (y ≥ 0), their sum is strictly positive: x + y > 0.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add( self, other: &'a PositiveRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the + operation.

impl<RealType: RealScalar> Add<NonNegativeRealScalar<RealType>> for PositiveRealScalar<RealType>

Adds a NonNegativeRealScalar to a PositiveRealScalar, yielding a PositiveRealScalar.

Since self is strictly positive (x > 0) and other is non-negative (y ≥ 0), their sum is strictly positive: x + y > 0.

Examples

use num_valid::{*, scalars::*};
use try_create::TryNew;

let pos = PositiveRealScalar::try_new(2.0_f64).unwrap();
let non_neg = NonNegativeRealScalar::try_new(3.0_f64).unwrap();

let result: PositiveRealScalar<f64> = pos + non_neg;
assert_eq!(result.as_raw_scalar_ref(), &5.0);

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add( self, other: NonNegativeRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the + operation.

impl<RealType: RealScalar> Add<PositiveRealScalar<RealType>> for NonNegativeRealScalar<RealType>

Adds a PositiveRealScalar to a NonNegativeRealScalar, yielding a PositiveRealScalar.

Since other is strictly positive (x > 0) and self is non-negative (y ≥ 0), their sum is strictly positive: x + y > 0.

Examples

use num_valid::{*, scalars::*};
use try_create::TryNew;

let non_neg = NonNegativeRealScalar::try_new(0.0_f64).unwrap(); // zero!
let pos = PositiveRealScalar::try_new(5.0_f64).unwrap();

let result: PositiveRealScalar<f64> = non_neg + pos;
assert_eq!(result.as_raw_scalar_ref(), &5.0);

type Output = PositiveRealScalar<RealType>

The resulting type after applying the + operator.

fn add( self, other: PositiveRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the + operation.

impl<RealType: RealScalar> AddAssign for PositiveRealScalar<RealType>

Implements in-place addition for PositiveRealScalar by value.

This allows adding a positive scalar value to self.

fn add_assign(&mut self, other: PositiveRealScalar<RealType>)

Performs the += operation.

impl<'a, RealType: RealScalar> AddAssign<&'a PositiveRealScalar<RealType>> for PositiveRealScalar<RealType>

Implements in-place reference-based addition for PositiveRealScalar.

This allows adding a reference to a positive scalar to self without consuming self.

fn add_assign(&mut self, other: &'a PositiveRealScalar<RealType>)

Performs the += operation.

impl<RealType: RealScalar> AsRef<RealType> for PositiveRealScalar<RealType>

fn as_ref(&self) -> &RealType

Converts this type into a shared reference of the (usually inferred) input type.

impl<RealType: Clone + RealScalar> Clone for PositiveRealScalar<RealType>

fn clone(&self) -> PositiveRealScalar<RealType>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<RealType: Debug + RealScalar> Debug for PositiveRealScalar<RealType>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, RealType> Deserialize<'de> for PositiveRealScalar<RealType>

where RealType: for<'a> Deserialize<'a> + RealScalar,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<RealType> Display for PositiveRealScalar<RealType>

where RealType: Display + RealScalar,

fn fmt(&self, __derive_more_f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<RealType: RealScalar> From<PositiveRealScalar<RealType>> for NonNegativeRealScalar<RealType>

Converts a PositiveRealScalar<T> to a NonNegativeRealScalar<T>.

This conversion is mathematically valid because every positive number (x > 0) is also non-negative (x ≥ 0). The conversion is infallible and zero-cost.

Examples

use num_valid::{*, scalars::*};
use try_create::TryNew;

let positive = PositiveRealScalar::try_new(5.0_f64).unwrap();
let non_negative: NonNegativeRealScalar<f64> = positive.into();

assert_eq!(non_negative.as_raw_scalar_ref(), &5.0);

fn from(positive: PositiveRealScalar<RealType>) -> Self

Converts to this type from the input type.

impl<RealType: RealScalar> IntoInner for PositiveRealScalar<RealType>

fn into_inner(self) -> Self::InnerType

Consumes the struct and returns the inner value.

type InnerType = RealType

The type of the inner value that will be extracted.

impl<RealType: RealScalar> Max for PositiveRealScalar<RealType>

Implements Max for PositiveRealScalar.

Maximum selection is delegated to the default trait behavior based on PartialOrd.

fn max_by_ref<'a>(&'a self, other: &'a Self) -> &'a Self

Returns a reference to the maximum of self and other.

fn max_by_value(self, other: Self) -> Self

Returns the maximum of self and other, consuming both values.

impl<RealType: RealScalar> Min for PositiveRealScalar<RealType>

Implements Min for PositiveRealScalar.

Minimum selection is delegated to the default trait behavior based on PartialOrd.

fn min_by_ref<'a>(&'a self, other: &'a Self) -> &'a Self

Returns a reference to the minimum of self and other.

fn min_by_value(self, other: Self) -> Self

Returns the minimum of self and other, consuming both values.

impl<RealType: RealScalar> Mul for PositiveRealScalar<RealType>

Implements multiplicative composition for PositiveRealScalar.

Since both operands are guaranteed to be positive, their product is also positive.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the * operator.

fn mul(self, other: Self) -> Self

Performs the * operation.

impl<'a, RealType: RealScalar> Mul<&'a PositiveRealScalar<RealType>> for PositiveRealScalar<RealType>

Implements reference-based multiplication for PositiveRealScalar.

This allows multiplying a positive scalar by a reference to another positive scalar without consuming it. Since both operands are guaranteed to be positive, their product is also positive.

type Output = PositiveRealScalar<RealType>

The resulting type after applying the * operator.

fn mul( self, other: &'a PositiveRealScalar<RealType>, ) -> PositiveRealScalar<RealType>

Performs the * operation.

impl<RealType: RealScalar> MulAssign for PositiveRealScalar<RealType>

Implements in-place multiplication for PositiveRealScalar by value.

This allows multiplying self by a positive scalar value.

fn mul_assign(&mut self, other: PositiveRealScalar<RealType>)

Performs the *= operation.

impl<'a, RealType: RealScalar> MulAssign<&'a PositiveRealScalar<RealType>> for PositiveRealScalar<RealType>

Implements in-place reference-based multiplication for PositiveRealScalar.

This allows multiplying self by a reference to another positive scalar without consuming self.

fn mul_assign(&mut self, other: &'a PositiveRealScalar<RealType>)

Performs the *= operation.

impl<RealType: RealScalar> NeumaierAddable for PositiveRealScalar<RealType>

Implements Neumaier compensated summation for PositiveRealScalar.

This implementation delegates to the underlying real scalar type’s Neumaier compensated sum operation, preserving numerical stability for sums of positive values.

fn neumaier_compensated_sum( value: Self, sum: &mut Self, compensation: &mut Self, )

Performs one step of the Neumaier compensated summation algorithm.

impl<RealType: RealScalar> One for PositiveRealScalar<RealType>

fn one() -> Self

Returns the multiplicative identity element of Self, 1.

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

where Self: PartialEq,

Returns true if self is equal to the multiplicative identity.

impl<RealType: PartialEq + RealScalar> PartialEq for PositiveRealScalar<RealType>

fn eq(&self, other: &PositiveRealScalar<RealType>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<RealType: PartialOrd + RealScalar> PartialOrd for PositiveRealScalar<RealType>

fn partial_cmp(&self, other: &PositiveRealScalar<RealType>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<RealType: RealScalar> Pow<i8> for PositiveRealScalar<RealType>

fn pow(self, exponent: i8) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, i8>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: i8) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<i16> for PositiveRealScalar<RealType>

fn pow(self, exponent: i16) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, i16>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: i16) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<i32> for PositiveRealScalar<RealType>

fn pow(self, exponent: i32) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, i32>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: i32) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<i64> for PositiveRealScalar<RealType>

fn pow(self, exponent: i64) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, i64>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: i64) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<i128> for PositiveRealScalar<RealType>

fn pow(self, exponent: i128) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, i128>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: i128) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<isize> for PositiveRealScalar<RealType>

fn pow(self, exponent: isize) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, isize>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: isize) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<u8> for PositiveRealScalar<RealType>

fn pow(self, exponent: u8) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, u8>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: u8) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<u16> for PositiveRealScalar<RealType>

fn pow(self, exponent: u16) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, u16>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: u16) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<u32> for PositiveRealScalar<RealType>

fn pow(self, exponent: u32) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, u32>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: u32) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<u64> for PositiveRealScalar<RealType>

fn pow(self, exponent: u64) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, u64>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: u64) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<u128> for PositiveRealScalar<RealType>

fn pow(self, exponent: u128) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, u128>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: u128) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> Pow<usize> for PositiveRealScalar<RealType>

fn pow(self, exponent: usize) -> Self

Raises the number self to the power exponent.

type Error = FunctionErrors<PowIntExponentInputErrors<<RealType as IntoInner>::InnerType, usize>, <<RealType as IntoInner>::InnerType as RawScalarValidate>::ValidationError>

The error type that can be returned by the try_pow method. This type must implement std::error::Error for proper error handling.

fn try_pow(self, exponent: usize) -> Result<Self, Self::Error>

Attempts to compute self (the base) raised to the power of exponent.

impl<RealType: RealScalar> ScalarCore for PositiveRealScalar<RealType>

type RawScalarType = <RealType as ScalarCore>::RawScalarType

The type of the inner value that will be extracted.

fn as_raw_scalar_ref(&self) -> &Self::RawScalarType

Returns a reference to the inner value.

fn into_raw_scalar(self) -> Self::RawScalarType

Consumes the scalar and returns its inner raw scalar value.

fn eq_raw(&self, other: &Self::RawScalarType) -> bool

Compares this scalar with a value in its underlying raw representation.

impl<RealType> Serialize for PositiveRealScalar<RealType>

where RealType: Serialize + RealScalar,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<RealType: PartialEq + RealScalar> StructuralPartialEq for PositiveRealScalar<RealType>

impl<RealType: RealScalar> TryNew for PositiveRealScalar<RealType>

fn try_new(value: RealType) -> Result<Self, Self::Error>

Attempts to create a PositiveRealScalar from a value.

Errors

• ErrorsPositiveRealScalar::NegativeValue: If the input is negative (< 0).
• ErrorsPositiveRealScalar::ZeroValue: If the input is zero.

Panics (Debug Mode Only)

In debug builds, panics if the input is not finite (NaN or infinity).

Examples

use num_valid::scalars::{PositiveRealScalar, ErrorsPositiveRealScalar};
use try_create::TryNew;

// Positive value succeeds
assert!(PositiveRealScalar::try_new(1.0_f64).is_ok());

// Zero fails
assert!(matches!(
    PositiveRealScalar::try_new(0.0_f64),
    Err(ErrorsPositiveRealScalar::ZeroValue { .. })
));

// Negative fails
assert!(matches!(
    PositiveRealScalar::try_new(-1.0_f64),
    Err(ErrorsPositiveRealScalar::NegativeValue { value: v, .. }) if v == -1.0
));

type Error = ErrorsPositiveRealScalar<RealType>

The error type that can be returned by the try_new method.