Struct S1ChordAngle 

#[repr(C)]
pub struct S1ChordAngle {
    pub length2: f64,
}

S1ChordAngle represents the angle subtended by a chord (i.e., the straight line segment connecting two points on the sphere). Its representation makes it very efficient for computing and comparing distances, but unlike S1Angle it is only capable of representing angles between 0 and Pi radians. S1ChordAngle is intended for applications where many angles need to be computed and compared, otherwise it is simpler to use S1Angle.

S1ChordAngle also loses some accuracy as the angle approaches Pi radians. There are several different ways to measure this error, including the representational error (i.e., how accurately S1ChordAngle can represent angles near Pi radians), the conversion error (i.e., how much precision is lost when an S1Angle is converted to an S1ChordAngle), and the measurement error (i.e., how accurate the S1ChordAngle(a, b) constructor is when the points A and B are separated by angles close to Pi radians). All of these errors differ by a small constant factor.

For the measurement error (which is the largest of these errors and also the most important in practice), let the angle between A and B be (Pi - x) radians, i.e. A and B are within “x” radians of being antipodal. The corresponding chord length is

$$ r = 2 * sin((Pi - x) / 2) = 2 * cos(x / 2) . $$

For values of x not close to Pi the relative error in the squared chord length is at most 4.5 * DBL_EPSILON (see GetS2PointConstructorMaxError). The relative error in “r” is thus at most 2.25 * DBL_EPSILON ~= 5e-16. To convert this error into an equivalent angle, we have

$$ |dr / dx| = sin(x / 2) $$

and therefore

$$ |dx| = dr / sin(x / 2) $$ $$ = 5e-16 * (2 * cos(x / 2)) / sin(x / 2) $$ $$ = 1e-15 / tan(x / 2) $$

The maximum error is attained when

$$ x = |dx| $$ $$ = 1e-15 / tan(x / 2) $$ $$ ~= 1e-15 / (x / 2) $$ $$ ~= sqrt(2e-15) $$

In summary, the measurement error for an angle (Pi - x) is at most

$$ dx = min(1e-15 / tan(x / 2), sqrt(2e-15)) $$ $$ (~= min(2e-15 / x, sqrt(2e-15)) when x is small). $$

On the Earth’s surface (assuming a radius of 6371km), this corresponds to the following worst-case measurement errors:

    Accuracy:             Unless antipodal to within:
    ---------             ---------------------------
    6.4 nanometers        10,000 km (90 degrees)
    1 micrometer          81.2 kilometers
    1 millimeter          81.2 meters
    1 centimeter          8.12 meters
    28.5 centimeters      28.5 centimeters

The representational and conversion errors referred to earlier are somewhat smaller than this. For example, maximum distance between adjacent representable S1ChordAngle values is only 13.5 cm rather than 28.5 cm. To see this, observe that the closest representable value to r^2 = 4 is r^2 = 4 * (1 - DBL_EPSILON / 2). Thus r = 2 * (1 - DBL_EPSILON / 4) and the angle between these two representable values is

$$ x = 2 * acos(r / 2) $$ $$ = 2 * acos(1 - DBL_EPSILON / 4) $$ $$ ~= 2 * asin(sqrt(DBL_EPSILON / 2) $$ $$ ~= sqrt(2 * DBL_EPSILON) $$ $$ ~= 2.1e-8 $$

which is 13.5 cm on the Earth’s surface.

The worst case rounding error occurs when the value halfway between these two representable values is rounded up to 4. This halfway value is r^2 = (4 * (1 - DBL_EPSILON / 4)), thus r = 2 * (1 - DBL_EPSILON / 8) and the worst case rounding error is

$$ x = 2 * acos(r / 2) $$ $$ = 2 * acos(1 - DBL_EPSILON / 8) $$ $$ ~= 2 * asin(sqrt(DBL_EPSILON / 4) $$ $$ ~= sqrt(DBL_EPSILON) $$ $$ ~= 1.5e-8 $$

which is 9.5 cm on the Earth’s surface.

This class is intended to be copied by value as desired. It uses the default copy constructor and assignment operator.

Usage

Methods that are available:

• S1ChordAngle::new: Create a new S1ChordAngle
• S1ChordAngle::zero: Returns the zero S1ChordAngle
• S1ChordAngle::infinity: Returns the infinite S1ChordAngle
• S1ChordAngle::from_angle: Conversion from an S1Angle
• S1ChordAngle::from_degrees: Construct an S1ChordAngle from an angle in degrees
• S1ChordAngle::from_length2: Construct the S1ChordAngle corresponding to the given length
• S1ChordAngle::from_s2_points: Construct the S1ChordAngle corresponding to the distance between the two given points
• S1ChordAngle::right_angle: Return a right angle
• S1ChordAngle::straight_angle: Return a chord angle of 180 degrees (a “straight angle”)
• S1ChordAngle::negative_angle: Construct an S1ChordAngle that is a lower bound on the given S1Angle
• S1ChordAngle::fast_upper_bound_from: Construct an S1ChordAngle that is an upper bound on the given S1Angle
• S1ChordAngle::is_special: Returns true if the angle is special
• S1ChordAngle::to_angle: Convert to an S1Angle
• S1ChordAngle::to_meters: Convert to meters. If no radius is specified, the Earth’s radius is used.
• S1ChordAngle::from_meters: Convert from meters. If no radius is specified, the Earth’s radius is used.
• S1ChordAngle::to_km: Convert to kilometers. If no radius is specified, the Earth’s radius is used.
• S1ChordAngle::from_km: Convert from kilometers. If no radius is specified, the Earth’s radius is used.
• S1ChordAngle::chord_angle_sin: apply a sine function on a ChordAngle
• S1ChordAngle::chord_angle_cos: apply a cosine function on a ChordAngle
• S1ChordAngle::chord_angle_tan: apply a tangent function on a ChordAngle
• S1ChordAngle::chord_angle_sin2: Returns sin(a)^2
• S1ChordAngle::modulo: Returns the remainder when dividing by modulus

Fields

length2: f64

The squared length of the corresponding S1Chord.

Implementations

impl S1ChordAngle

pub fn new(length2: f64) -> Self

Creates a new S1ChordAngle.

pub fn zero() -> Self

Returns the zero S1ChordAngle.

pub fn infinity() -> Self

Returns the infinite S1ChordAngle.

pub fn from_angle(angle: S1Angle) -> Self

Conversion from an S1Angle. Angles outside the range [0, Pi] are handled as follows: Infinity() is mapped to Infinity(), negative angles are mapped to Negative(), and finite angles larger than Pi are mapped to Straight().

Note that this operation is relatively expensive and should be avoided. To use S1ChordAngle effectively, you should structure your code so that input arguments are converted to S1ChordAngles at the beginning of your algorithm, and results are converted back to S1Angles only at the end.

S1ChordAngles are represented by the squared chord length, which can range from 0 to 4. Infinity() uses an infinite squared length.

Parameters

• angle An angle in radians.

Returns

The corresponding ChordAngle.

pub fn from_degrees(degrees: f64) -> Self

Construct an S1ChordAngle from an angle in degrees.

pub fn from_length2(length2_: f64) -> Self

Construct an S1ChordAngle from the squared chord length. Note that the argument is automatically clamped to a maximum of 4.0 to handle possible roundoff errors. The argument must be non-negative.

pub fn from_s2_points(a: &S2Point, b: &S2Point) -> Self

Construct the S1ChordAngle corresponding to the distance between the two given points. The points must be unit length.

pub fn right_angle() -> Self

Return a chord angle of 90 degrees (a “right angle”).

pub fn straight_angle() -> Self

Return a chord angle of 180 degrees (a “straight angle”). This is the maximum finite chord angle.

pub fn negative_angle() -> Self

Return a chord angle smaller than Zero(). The only valid operations on Negative() are comparisons, S1Angle conversions, and successor() / predecessor().

pub fn fast_upper_bound_from(angle: S1Angle) -> Self

Construct an S1ChordAngle that is an upper bound on the given S1Angle. i.i. such that FastUpperBoundFrom(x).toAngle() >= x. Unlike the S1Angle constructor above, this method is very fast, and the bound is accurate to within 1% for distances up to about 3100km on the Earth’s surface.

pub fn is_special(&self) -> bool

Convenience function to test if a ChordAngle is special.

pub fn to_angle(&self) -> S1Angle

Convert to an S1Angle. Infinity() is converted to S1Angle.Infinity(), and Negative() is converted to an unspecified negative S1Angle.

Note that the conversion uses trigonometric functions and therefore should be avoided in inner loops.

pub fn to_meters(&self, radius: Option<f64>) -> f64

Convert to meters. If no radius is specified, the Earth’s radius is used.

pub fn from_meters(meters: f64, radius: Option<f64>) -> Self

Convert from meters. If no radius is specified, the Earth’s radius is used.

pub fn to_km(&self, radius: Option<f64>) -> f64

Convert to kilometers. If no radius is specified, the Earth’s radius is used.

pub fn from_km(km: f64, radius: Option<f64>) -> Self

Convert from kilometers. If no radius is specified, the Earth’s radius is used.

pub fn chord_angle_sin(&self) -> f64

apply a sine function on a ChordAngle

pub fn chord_angle_cos(&self) -> f64

apply a cosine function on a ChordAngle

pub fn chord_angle_tan(&self) -> f64

apply a tangent function on a ChordAngle

pub fn chord_angle_sin2(&self) -> f64

Returns sin(a)^2, but computed more efficiently.

pub fn modulo(&self, modulus: f64) -> Self

Returns the remainder when dividing by modulus

Methods from Deref<Target = f64>

pub const RADIX: u32 = 2u32

pub const MANTISSA_DIGITS: u32 = 53u32

pub const DIGITS: u32 = 15u32

pub const EPSILON: f64 = 2.2204460492503131E-16f64

pub const MIN: f64 = -1.7976931348623157E+308f64

pub const MIN_POSITIVE: f64 = 2.2250738585072014E-308f64

pub const MAX: f64 = 1.7976931348623157E+308f64

pub const MIN_EXP: i32 = -1_021i32

pub const MAX_EXP: i32 = 1_024i32

pub const MIN_10_EXP: i32 = -307i32

pub const MAX_10_EXP: i32 = 308i32

pub const NAN: f64 = NaN_f64

pub const INFINITY: f64 = +Inf_f64

pub const NEG_INFINITY: f64 = -Inf_f64

pub fn total_cmp(&self, other: &f64) -> Ordering

Returns the ordering between self and other.

Unlike the standard partial comparison between floating point numbers, this comparison always produces an ordering in accordance to the totalOrder predicate as defined in the IEEE 754 (2008 revision) floating point standard. The values are ordered in the following sequence:

• negative quiet NaN
• negative signaling NaN
• negative infinity
• negative numbers
• negative subnormal numbers
• negative zero
• positive zero
• positive subnormal numbers
• positive numbers
• positive infinity
• positive signaling NaN
• positive quiet NaN.

The ordering established by this function does not always agree with the PartialOrd and PartialEq implementations of f64. For example, they consider negative and positive zero equal, while total_cmp doesn’t.

The interpretation of the signaling NaN bit follows the definition in the IEEE 754 standard, which may not match the interpretation by some of the older, non-conformant (e.g. MIPS) hardware implementations.

Example

struct GoodBoy {
    name: String,
    weight: f64,
}

let mut bois = vec![
    GoodBoy { name: "Pucci".to_owned(), weight: 0.1 },
    GoodBoy { name: "Woofer".to_owned(), weight: 99.0 },
    GoodBoy { name: "Yapper".to_owned(), weight: 10.0 },
    GoodBoy { name: "Chonk".to_owned(), weight: f64::INFINITY },
    GoodBoy { name: "Abs. Unit".to_owned(), weight: f64::NAN },
    GoodBoy { name: "Floaty".to_owned(), weight: -5.0 },
];

bois.sort_by(|a, b| a.weight.total_cmp(&b.weight));

// `f64::NAN` could be positive or negative, which will affect the sort order.
if f64::NAN.is_sign_negative() {
    assert!(bois.into_iter().map(|b| b.weight)
        .zip([f64::NAN, -5.0, 0.1, 10.0, 99.0, f64::INFINITY].iter())
        .all(|(a, b)| a.to_bits() == b.to_bits()))
} else {
    assert!(bois.into_iter().map(|b| b.weight)
        .zip([-5.0, 0.1, 10.0, 99.0, f64::INFINITY, f64::NAN].iter())
        .all(|(a, b)| a.to_bits() == b.to_bits()))
}

Trait Implementations

impl Add<f64> for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the + operator.

fn add(self, rhs: f64) -> Self

Performs the + operation.

impl Add for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the + operator.

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

Performs the + operation.

impl Clone for S1ChordAngle

fn clone(&self) -> S1ChordAngle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for S1ChordAngle

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

Formats the value using the given formatter.

impl Default for S1ChordAngle

fn default() -> S1ChordAngle

Returns the “default value” for a type.

impl Deref for S1ChordAngle

type Target = f64

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Div<f64> for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the / operator.

fn div(self, rhs: f64) -> Self

Performs the / operation.

impl Div for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self

Performs the / operation.

impl From<S1Angle> for S1ChordAngle

fn from(angle: S1Angle) -> S1ChordAngle

Converts to this type from the input type.

impl From<S1ChordAngle> for S1Angle

fn from(c_angle: S1ChordAngle) -> S1Angle

Converts to this type from the input type.

impl From<f64> for S1ChordAngle

fn from(length2: f64) -> S1ChordAngle

Converts to this type from the input type.

impl Mul<f64> for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self

Performs the * operation.

impl Mul for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the * operator.

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

Performs the * operation.

impl Neg for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl Ord for S1ChordAngle

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<f64> for S1ChordAngle

fn eq(&self, other: &f64) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for S1ChordAngle

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<f64> for S1ChordAngle

fn partial_cmp(&self, other: &f64) -> 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 PartialOrd for S1ChordAngle

fn partial_cmp(&self, other: &Self) -> 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 Rem<f64> for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the % operator.

fn rem(self, modulus: f64) -> Self::Output

Performs the % operation.

impl RemAssign<f64> for S1ChordAngle

fn rem_assign(&mut self, modulus: f64)

Performs the %= operation.

impl Sub<f64> for S1ChordAngle

fn sub(self, rhs: f64) -> Self

Subtracts a value from the length2 of the chord angle.

type Output = S1ChordAngle

The resulting type after applying the - operator.

impl Sub for S1ChordAngle

type Output = S1ChordAngle

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self

Performs the - operation.

impl Copy for S1ChordAngle

impl Eq for S1ChordAngle