Skip to main content

cgmath/
structure.rs

1// Copyright 2016 The CGMath Developers. For a full listing of the authors,
2// refer to the Cargo.toml file at the top-level directory of this distribution.
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8//     http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! Generic algebraic structures
17
18use num_traits::{cast, Float};
19use std::cmp;
20use std::iter;
21use std::ops::*;
22
23use approx;
24
25use angle::Rad;
26use num::{BaseFloat, BaseNum};
27
28pub use num_traits::{Bounded, One, Zero};
29
30/// An array containing elements of type `Element`
31pub trait Array
32where
33    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
34    Self: Index<usize, Output = <Self as Array>::Element>,
35    Self: IndexMut<usize, Output = <Self as Array>::Element>,
36{
37    type Element: Copy;
38
39    /// Get the number of elements in the array type
40    ///
41    /// ```rust
42    /// use cgmath::prelude::*;
43    /// use cgmath::Vector3;
44    ///
45    /// assert_eq!(Vector3::<f32>::len(), 3);
46    /// ```
47    fn len() -> usize;
48
49    /// Construct a vector from a single value, replicating it.
50    ///
51    /// ```rust
52    /// use cgmath::prelude::*;
53    /// use cgmath::Vector3;
54    ///
55    /// assert_eq!(Vector3::from_value(1),
56    ///            Vector3::new(1, 1, 1));
57    /// ```
58    fn from_value(value: Self::Element) -> Self;
59
60    /// Get the pointer to the first element of the array.
61    #[inline]
62    fn as_ptr(&self) -> *const Self::Element {
63        &self[0]
64    }
65
66    /// Get a mutable pointer to the first element of the array.
67    #[inline]
68    fn as_mut_ptr(&mut self) -> *mut Self::Element {
69        &mut self[0]
70    }
71
72    /// Swap the elements at indices `i` and `j` in-place.
73    #[inline]
74    fn swap_elements(&mut self, i: usize, j: usize) {
75        let tmp = self[i];
76        self[i] = self[j];
77        self[j] = tmp;
78    }
79
80    /// The sum of the elements of the array.
81    fn sum(self) -> Self::Element
82    where
83        Self::Element: Add<Output = <Self as Array>::Element>;
84
85    /// The product of the elements of the array.
86    fn product(self) -> Self::Element
87    where
88        Self::Element: Mul<Output = <Self as Array>::Element>;
89
90    /// Whether all elements of the array are finite
91    fn is_finite(&self) -> bool
92    where
93        Self::Element: Float;
94}
95
96/// Element-wise arithmetic operations. These are supplied for pragmatic
97/// reasons, but will usually fall outside of traditional algebraic properties.
98pub trait ElementWise<Rhs = Self> {
99    fn add_element_wise(self, rhs: Rhs) -> Self;
100    fn sub_element_wise(self, rhs: Rhs) -> Self;
101    fn mul_element_wise(self, rhs: Rhs) -> Self;
102    fn div_element_wise(self, rhs: Rhs) -> Self;
103    fn rem_element_wise(self, rhs: Rhs) -> Self;
104
105    fn add_assign_element_wise(&mut self, rhs: Rhs);
106    fn sub_assign_element_wise(&mut self, rhs: Rhs);
107    fn mul_assign_element_wise(&mut self, rhs: Rhs);
108    fn div_assign_element_wise(&mut self, rhs: Rhs);
109    fn rem_assign_element_wise(&mut self, rhs: Rhs);
110}
111
112/// Vectors that can be [added](http://mathworld.wolfram.com/VectorAddition.html)
113/// together and [multiplied](https://en.wikipedia.org/wiki/Scalar_multiplication)
114/// by scalars.
115///
116/// Examples include vectors, matrices, and quaternions.
117///
118/// # Required operators
119///
120/// ## Vector addition
121///
122/// Vectors can be added, subtracted, or negated via the following traits:
123///
124/// - `Add<Output = Self>`
125/// - `Sub<Output = Self>`
126/// - `Neg<Output = Self>`
127///
128/// ```rust
129/// use cgmath::Vector3;
130///
131/// let velocity0 = Vector3::new(1, 2, 0);
132/// let velocity1 = Vector3::new(1, 1, 0);
133///
134/// let total_velocity = velocity0 + velocity1;
135/// let velocity_diff = velocity1 - velocity0;
136/// let reversed_velocity0 = -velocity0;
137/// ```
138///
139/// Vector spaces are also required to implement the additive identity trait,
140/// `Zero`. Adding this to another vector should have no effect:
141///
142/// ```rust
143/// use cgmath::prelude::*;
144/// use cgmath::Vector2;
145///
146/// let v = Vector2::new(1, 2);
147/// assert_eq!(v + Vector2::zero(), v);
148/// ```
149///
150/// ## Scalar multiplication
151///
152/// Vectors can be multiplied or divided by their associated scalars via the
153/// following traits:
154///
155/// - `Mul<Self::Scalar, Output = Self>`
156/// - `Div<Self::Scalar, Output = Self>`
157/// - `Rem<Self::Scalar, Output = Self>`
158///
159/// ```rust
160/// use cgmath::Vector2;
161///
162/// let translation = Vector2::new(3.0, 4.0);
163/// let scale_factor = 2.0;
164///
165/// let upscaled_translation = translation * scale_factor;
166/// let downscaled_translation = translation / scale_factor;
167/// ```
168pub trait VectorSpace: Copy + Clone
169where
170    Self: Zero,
171
172    Self: Add<Self, Output = Self>,
173    Self: Sub<Self, Output = Self>,
174    Self: iter::Sum<Self>,
175
176    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
177    Self: Mul<<Self as VectorSpace>::Scalar, Output = Self>,
178    Self: Div<<Self as VectorSpace>::Scalar, Output = Self>,
179    Self: Rem<<Self as VectorSpace>::Scalar, Output = Self>,
180{
181    /// The associated scalar.
182    type Scalar: BaseNum;
183
184    /// Returns the result of linearly interpolating the vector
185    /// towards `other` by the specified amount.
186    #[inline]
187    fn lerp(self, other: Self, amount: Self::Scalar) -> Self {
188        self + ((other - self) * amount)
189    }
190}
191
192/// A type with a distance function between values.
193///
194/// Examples are vectors, points, and quaternions.
195pub trait MetricSpace: Sized {
196    /// The metric to be returned by the `distance` function.
197    type Metric;
198
199    /// Returns the squared distance.
200    ///
201    /// This does not perform an expensive square root operation like in
202    /// `MetricSpace::distance` method, and so can be used to compare distances
203    /// more efficiently.
204    fn distance2(self, other: Self) -> Self::Metric;
205
206    /// The distance between two values.
207    fn distance(self, other: Self) -> Self::Metric
208    where
209        Self::Metric: Float,
210    {
211        Float::sqrt(Self::distance2(self, other))
212    }
213}
214
215/// Vectors that also have a [dot](https://en.wikipedia.org/wiki/Dot_product)
216/// (or [inner](https://en.wikipedia.org/wiki/Inner_product_space)) product.
217///
218/// The dot product allows for the definition of other useful operations, like
219/// finding the magnitude of a vector or normalizing it.
220///
221/// Examples include vectors and quaternions.
222pub trait InnerSpace: VectorSpace
223where
224    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
225    Self: MetricSpace<Metric = <Self as VectorSpace>::Scalar>,
226{
227    /// Vector dot (or inner) product.
228    fn dot(self, other: Self) -> Self::Scalar;
229
230    /// Returns `true` if the vector is perpendicular (at right angles) to the
231    /// other vector.
232    fn is_perpendicular(self, other: Self) -> bool
233    where
234        Self::Scalar: approx::UlpsEq,
235    {
236        ulps_eq!(Self::dot(self, other), &Self::Scalar::zero())
237    }
238
239    /// Returns the squared magnitude.
240    ///
241    /// This does not perform an expensive square root operation like in
242    /// `InnerSpace::magnitude` method, and so can be used to compare magnitudes
243    /// more efficiently.
244    #[inline]
245    fn magnitude2(self) -> Self::Scalar {
246        Self::dot(self, self)
247    }
248
249    /// Returns the angle between two vectors in radians.
250    fn angle(self, other: Self) -> Rad<Self::Scalar>
251    where
252        Self::Scalar: BaseFloat,
253    {
254        Rad::acos(Self::dot(self, other) / (self.magnitude() * other.magnitude()))
255    }
256
257    /// Returns the
258    /// [vector projection](https://en.wikipedia.org/wiki/Vector_projection)
259    /// of the current inner space projected onto the supplied argument.
260    #[inline]
261    fn project_on(self, other: Self) -> Self {
262        other * (self.dot(other) / other.magnitude2())
263    }
264
265    /// The distance from the tail to the tip of the vector.
266    #[inline]
267    fn magnitude(self) -> Self::Scalar
268    where
269        Self::Scalar: Float,
270    {
271        Float::sqrt(self.magnitude2())
272    }
273
274    /// Returns a vector with the same direction, but with a magnitude of `1`.
275    #[inline]
276    fn normalize(self) -> Self
277    where
278        Self::Scalar: Float,
279    {
280        self.normalize_to(Self::Scalar::one())
281    }
282
283    /// Returns a vector with the same direction and a given magnitude.
284    #[inline]
285    fn normalize_to(self, magnitude: Self::Scalar) -> Self
286    where
287        Self::Scalar: Float,
288    {
289        self * (magnitude / self.magnitude())
290    }
291}
292
293/// Points in a [Euclidean space](https://en.wikipedia.org/wiki/Euclidean_space)
294/// with an associated space of displacement vectors.
295///
296/// # Point-Vector distinction
297///
298/// `cgmath` distinguishes between points and vectors in the following way:
299///
300/// - Points are _locations_ relative to an origin
301/// - Vectors are _displacements_ between those points
302///
303/// For example, to find the midpoint between two points, you can write the
304/// following:
305///
306/// ```rust
307/// use cgmath::Point3;
308///
309/// let p0 = Point3::new(1.0, 2.0, 3.0);
310/// let p1 = Point3::new(-3.0, 1.0, 2.0);
311/// let midpoint: Point3<f32> = p0 + (p1 - p0) * 0.5;
312/// ```
313///
314/// Breaking the expression up, and adding explicit types makes it clearer
315/// to see what is going on:
316///
317/// ```rust
318/// # use cgmath::{Point3, Vector3};
319/// #
320/// # let p0 = Point3::new(1.0, 2.0, 3.0);
321/// # let p1 = Point3::new(-3.0, 1.0, 2.0);
322/// #
323/// let dv: Vector3<f32> = p1 - p0;
324/// let half_dv: Vector3<f32> = dv * 0.5;
325/// let midpoint: Point3<f32> = p0 + half_dv;
326/// ```
327///
328/// ## Converting between points and vectors
329///
330/// Points can be converted to and from displacement vectors using the
331/// `EuclideanSpace::{from_vec, to_vec}` methods. Note that under the hood these
332/// are implemented as inlined a type conversion, so should not have any
333/// performance implications.
334///
335/// ## References
336///
337/// - [CGAL 4.7 - 2D and 3D Linear Geometry Kernel: 3.1 Points and Vectors](http://doc.cgal.org/latest/Kernel_23/index.html#Kernel_23PointsandVectors)
338/// - [What is the difference between a point and a vector](http://math.stackexchange.com/q/645827)
339///
340pub trait EuclideanSpace: Copy + Clone
341where
342    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
343    Self: Array<Element = <Self as EuclideanSpace>::Scalar>,
344
345    Self: Add<<Self as EuclideanSpace>::Diff, Output = Self>,
346    Self: Sub<<Self as EuclideanSpace>::Diff, Output = Self>,
347    Self: Sub<Self, Output = <Self as EuclideanSpace>::Diff>,
348
349    Self: Mul<<Self as EuclideanSpace>::Scalar, Output = Self>,
350    Self: Div<<Self as EuclideanSpace>::Scalar, Output = Self>,
351    Self: Rem<<Self as EuclideanSpace>::Scalar, Output = Self>,
352{
353    /// The associated scalar over which the space is defined.
354    ///
355    /// Due to the equality constraints demanded by `Self::Diff`, this is effectively just an
356    /// alias to `Self::Diff::Scalar`.
357    type Scalar: BaseNum;
358
359    /// The associated space of displacement vectors.
360    type Diff: VectorSpace<Scalar = Self::Scalar>;
361
362    /// The point at the origin of the Euclidean space.
363    fn origin() -> Self;
364
365    /// Convert a displacement vector to a point.
366    ///
367    /// This can be considered equivalent to the addition of the displacement
368    /// vector `v` to to `Self::origin()`.
369    fn from_vec(v: Self::Diff) -> Self;
370
371    /// Convert a point to a displacement vector.
372    ///
373    /// This can be seen as equivalent to the displacement vector from
374    /// `Self::origin()` to `self`.
375    fn to_vec(self) -> Self::Diff;
376
377    /// Returns the middle point between two other points.
378    ///
379    /// ```rust
380    /// use cgmath::prelude::*;
381    /// use cgmath::Point3;
382    ///
383    /// let p = Point3::midpoint(
384    ///     Point3::new(1.0, 2.0, 3.0),
385    ///     Point3::new(3.0, 1.0, 2.0),
386    /// );
387    /// ```
388    #[inline]
389    fn midpoint(self, other: Self) -> Self {
390        self + (other - self) / cast(2).unwrap()
391    }
392
393    /// Returns the average position of all points in the slice.
394    ///
395    /// ```rust
396    /// use cgmath::prelude::*;
397    /// use cgmath::Point2;
398    ///
399    /// let triangle = [
400    ///     Point2::new(1.0, 1.0),
401    ///     Point2::new(2.0, 3.0),
402    ///     Point2::new(3.0, 1.0),
403    /// ];
404    ///
405    /// let centroid = Point2::centroid(&triangle);
406    /// ```
407    #[inline]
408    fn centroid(points: &[Self]) -> Self {
409        let total_displacement = points
410            .iter()
411            .fold(Self::Diff::zero(), |acc, p| acc + p.to_vec());
412
413        Self::from_vec(total_displacement / cast(points.len()).unwrap())
414    }
415
416    /// This is a weird one, but its useful for plane calculations.
417    fn dot(self, v: Self::Diff) -> Self::Scalar;
418}
419
420/// A column-major matrix of arbitrary dimensions.
421///
422/// Because this is constrained to the `VectorSpace` trait, this means that
423/// following operators are required to be implemented:
424///
425/// Matrix addition:
426///
427/// - `Add<Output = Self>`
428/// - `Sub<Output = Self>`
429/// - `Neg<Output = Self>`
430///
431/// Scalar multiplication:
432///
433/// - `Mul<Self::Scalar, Output = Self>`
434/// - `Div<Self::Scalar, Output = Self>`
435/// - `Rem<Self::Scalar, Output = Self>`
436///
437/// Note that matrix multiplication is not required for implementors of this
438/// trait. This is due to the complexities of implementing these operators with
439/// Rust's current type system. For the multiplication of square matrices,
440/// see `SquareMatrix`.
441pub trait Matrix: VectorSpace
442where
443    Self::Scalar: Float,
444
445    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
446    Self: Index<usize, Output = <Self as Matrix>::Column>,
447    Self: IndexMut<usize, Output = <Self as Matrix>::Column>,
448{
449    /// The row vector of the matrix.
450    type Row: VectorSpace<Scalar = Self::Scalar> + Array<Element = Self::Scalar>;
451
452    /// The column vector of the matrix.
453    type Column: VectorSpace<Scalar = Self::Scalar> + Array<Element = Self::Scalar>;
454
455    /// The result of transposing the matrix
456    type Transpose: Matrix<Scalar = Self::Scalar, Row = Self::Column, Column = Self::Row>;
457
458    /// Get the pointer to the first element of the array.
459    #[inline]
460    fn as_ptr(&self) -> *const Self::Scalar {
461        &self[0][0]
462    }
463
464    /// Get a mutable pointer to the first element of the array.
465    #[inline]
466    fn as_mut_ptr(&mut self) -> *mut Self::Scalar {
467        &mut self[0][0]
468    }
469
470    /// Replace a column in the array.
471    #[inline]
472    fn replace_col(&mut self, c: usize, src: Self::Column) -> Self::Column {
473        use std::mem;
474
475        mem::replace(&mut self[c], src)
476    }
477
478    /// Get a row from this matrix by-value.
479    fn row(&self, r: usize) -> Self::Row;
480
481    /// Swap two rows of this array.
482    fn swap_rows(&mut self, a: usize, b: usize);
483    /// Swap two columns of this array.
484    fn swap_columns(&mut self, a: usize, b: usize);
485    /// Swap the values at index `a` and `b`
486    fn swap_elements(&mut self, a: (usize, usize), b: (usize, usize));
487
488    /// Transpose this matrix, returning a new matrix.
489    fn transpose(&self) -> Self::Transpose;
490}
491
492/// A column-major major matrix where the rows and column vectors are of the same dimensions.
493pub trait SquareMatrix
494where
495    Self::Scalar: Float,
496
497    Self: One,
498    Self: iter::Product<Self>,
499
500    Self: Matrix<
501        // FIXME: Can be cleaned up once equality constraints in where clauses are implemented
502        Column = <Self as SquareMatrix>::ColumnRow,
503        Row = <Self as SquareMatrix>::ColumnRow,
504        Transpose = Self,
505    >,
506    Self: Mul<<Self as SquareMatrix>::ColumnRow, Output = <Self as SquareMatrix>::ColumnRow>,
507    Self: Mul<Self, Output = Self>,
508{
509    // FIXME: Will not be needed once equality constraints in where clauses are implemented
510    /// The row/column vector of the matrix.
511    ///
512    /// This is used to constrain the column and rows to be of the same type in lieu of equality
513    /// constraints being implemented for `where` clauses. Once those are added, this type will
514    /// likely go away.
515    type ColumnRow: VectorSpace<Scalar = Self::Scalar> + Array<Element = Self::Scalar>;
516
517    /// Create a new diagonal matrix using the supplied value.
518    fn from_value(value: Self::Scalar) -> Self;
519    /// Create a matrix from a non-uniform scale
520    fn from_diagonal(diagonal: Self::ColumnRow) -> Self;
521
522    /// The [identity matrix]. Multiplying this matrix with another should have
523    /// no effect.
524    ///
525    /// Note that this is exactly the same as `One::one`. The term 'identity
526    /// matrix' is more common though, so we provide this method as an
527    /// alternative.
528    ///
529    /// [identity matrix]: https://en.wikipedia.org/wiki/Identity_matrix
530    #[inline]
531    fn identity() -> Self {
532        Self::one()
533    }
534
535    /// Transpose this matrix in-place.
536    fn transpose_self(&mut self);
537    /// Take the determinant of this matrix.
538    fn determinant(&self) -> Self::Scalar;
539
540    /// Return a vector containing the diagonal of this matrix.
541    fn diagonal(&self) -> Self::ColumnRow;
542
543    /// Return the trace of this matrix. That is, the sum of the diagonal.
544    #[inline]
545    fn trace(&self) -> Self::Scalar {
546        self.diagonal().sum()
547    }
548
549    /// Invert this matrix, returning a new matrix. `m.mul_m(m.invert())` is
550    /// the identity matrix. Returns `None` if this matrix is not invertible
551    /// (has a determinant of zero).
552    fn invert(&self) -> Option<Self>;
553
554    /// Test if this matrix is invertible.
555    #[inline]
556    fn is_invertible(&self) -> bool
557    where
558        Self::Scalar: approx::UlpsEq,
559    {
560        ulps_ne!(self.determinant(), &Self::Scalar::zero())
561    }
562
563    /// Test if this matrix is the identity matrix. That is, it is diagonal
564    /// and every element in the diagonal is one.
565    #[inline]
566    fn is_identity(&self) -> bool
567    where
568        Self: approx::UlpsEq,
569    {
570        ulps_eq!(self, &Self::identity())
571    }
572
573    /// Test if this is a diagonal matrix. That is, every element outside of
574    /// the diagonal is 0.
575    fn is_diagonal(&self) -> bool;
576
577    /// Test if this matrix is symmetric. That is, it is equal to its
578    /// transpose.
579    fn is_symmetric(&self) -> bool;
580}
581
582/// Angles and their associated trigonometric functions.
583///
584/// Typed angles allow for the writing of self-documenting code that makes it
585/// clear when semantic violations have occured - for example, adding degrees to
586/// radians, or adding a number to an angle.
587///
588pub trait Angle
589where
590    Self: Copy + Clone,
591    Self: PartialEq + cmp::PartialOrd,
592    // FIXME: Ugly type signatures - blocked by rust-lang/rust#24092
593    Self: approx::AbsDiffEq<Epsilon = <Self as Angle>::Unitless>,
594    Self: approx::RelativeEq<Epsilon = <Self as Angle>::Unitless>,
595    Self: approx::UlpsEq<Epsilon = <Self as Angle>::Unitless>,
596
597    Self: Zero,
598
599    Self: Neg<Output = Self>,
600    Self: Add<Self, Output = Self>,
601    Self: Sub<Self, Output = Self>,
602    Self: Rem<Self, Output = Self>,
603    Self: Mul<<Self as Angle>::Unitless, Output = Self>,
604    Self: Div<Self, Output = <Self as Angle>::Unitless>,
605    Self: Div<<Self as Angle>::Unitless, Output = Self>,
606
607    Self: iter::Sum,
608{
609    type Unitless: BaseFloat;
610
611    /// Return the angle, normalized to the range `[0, full_turn)`.
612    #[inline]
613    fn normalize(self) -> Self {
614        let rem = self % Self::full_turn();
615        if rem < Self::zero() {
616            rem + Self::full_turn()
617        } else {
618            rem
619        }
620    }
621
622    /// Return the angle, normalized to the range `[-turn_div_2, turn_div_2)`.
623    #[inline]
624    fn normalize_signed(self) -> Self {
625        let rem = self.normalize();
626        if Self::turn_div_2() < rem {
627            rem - Self::full_turn()
628        } else {
629            rem
630        }
631    }
632
633    /// Return the angle rotated by half a turn.
634    #[inline]
635    fn opposite(self) -> Self {
636        Self::normalize(self + Self::turn_div_2())
637    }
638
639    /// Returns the interior bisector of the two angles.
640    #[inline]
641    fn bisect(self, other: Self) -> Self {
642        let half = cast(0.5f64).unwrap();
643        Self::normalize((self - other) * half + self)
644    }
645
646    /// A full rotation.
647    fn full_turn() -> Self;
648
649    /// Half of a full rotation.
650    #[inline]
651    fn turn_div_2() -> Self {
652        let factor: Self::Unitless = cast(2).unwrap();
653        Self::full_turn() / factor
654    }
655
656    /// A third of a full rotation.
657    #[inline]
658    fn turn_div_3() -> Self {
659        let factor: Self::Unitless = cast(3).unwrap();
660        Self::full_turn() / factor
661    }
662
663    /// A quarter of a full rotation.
664    #[inline]
665    fn turn_div_4() -> Self {
666        let factor: Self::Unitless = cast(4).unwrap();
667        Self::full_turn() / factor
668    }
669
670    /// A sixth of a full rotation.
671    #[inline]
672    fn turn_div_6() -> Self {
673        let factor: Self::Unitless = cast(6).unwrap();
674        Self::full_turn() / factor
675    }
676
677    /// Compute the sine of the angle, returning a unitless ratio.
678    ///
679    /// ```rust
680    /// use cgmath::prelude::*;
681    /// use cgmath::Rad;
682    ///
683    /// let angle = Rad(35.0);
684    /// let ratio: f32 = Rad::sin(angle);
685    /// ```
686    fn sin(self) -> Self::Unitless;
687
688    /// Compute the cosine of the angle, returning a unitless ratio.
689    ///
690    /// ```rust
691    /// use cgmath::prelude::*;
692    /// use cgmath::Rad;
693    ///
694    /// let angle = Rad(35.0);
695    /// let ratio: f32 = Rad::cos(angle);
696    /// ```
697    fn cos(self) -> Self::Unitless;
698
699    /// Compute the tangent of the angle, returning a unitless ratio.
700    ///
701    /// ```rust
702    /// use cgmath::prelude::*;
703    /// use cgmath::Rad;
704    ///
705    /// let angle = Rad(35.0);
706    /// let ratio: f32 = Rad::tan(angle);
707    /// ```
708    fn tan(self) -> Self::Unitless;
709
710    /// Compute the sine and cosine of the angle, returning the result as a
711    /// pair.
712    ///
713    /// This does not have any performance benefits, but calculating both the
714    /// sine and cosine of a single angle is a common operation.
715    ///
716    /// ```rust
717    /// use cgmath::prelude::*;
718    /// use cgmath::Rad;
719    ///
720    /// let angle = Rad(35.0);
721    /// let (s, c) = Rad::sin_cos(angle);
722    /// ```
723    fn sin_cos(self) -> (Self::Unitless, Self::Unitless);
724
725    /// Compute the cosecant of the angle.
726    ///
727    /// This is the same as computing the reciprocal of `Self::sin`.
728    ///
729    /// ```rust
730    /// use cgmath::prelude::*;
731    /// use cgmath::Rad;
732    ///
733    /// let angle = Rad(35.0);
734    /// let ratio: f32 = Rad::csc(angle);
735    /// ```
736    #[inline]
737    fn csc(self) -> Self::Unitless {
738        Self::sin(self).recip()
739    }
740
741    /// Compute the cotangent of the angle.
742    ///
743    /// This is the same as computing the reciprocal of `Self::tan`.
744    ///
745    /// ```rust
746    /// use cgmath::prelude::*;
747    /// use cgmath::Rad;
748    ///
749    /// let angle = Rad(35.0);
750    /// let ratio: f32 = Rad::cot(angle);
751    /// ```
752    #[inline]
753    fn cot(self) -> Self::Unitless {
754        Self::tan(self).recip()
755    }
756
757    /// Compute the secant of the angle.
758    ///
759    /// This is the same as computing the reciprocal of `Self::cos`.
760    ///
761    /// ```rust
762    /// use cgmath::prelude::*;
763    /// use cgmath::Rad;
764    ///
765    /// let angle = Rad(35.0);
766    /// let ratio: f32 = Rad::sec(angle);
767    /// ```
768    #[inline]
769    fn sec(self) -> Self::Unitless {
770        Self::cos(self).recip()
771    }
772
773    /// Compute the arcsine of the ratio, returning the resulting angle.
774    ///
775    /// ```rust
776    /// use cgmath::prelude::*;
777    /// use cgmath::Rad;
778    ///
779    /// let angle: Rad<f32> = Rad::asin(0.5);
780    /// ```
781    fn asin(ratio: Self::Unitless) -> Self;
782
783    /// Compute the arccosine of the ratio, returning the resulting angle.
784    ///
785    /// ```rust
786    /// use cgmath::prelude::*;
787    /// use cgmath::Rad;
788    ///
789    /// let angle: Rad<f32> = Rad::acos(0.5);
790    /// ```
791    fn acos(ratio: Self::Unitless) -> Self;
792
793    /// Compute the arctangent of the ratio, returning the resulting angle.
794    ///
795    /// ```rust
796    /// use cgmath::prelude::*;
797    /// use cgmath::Rad;
798    ///
799    /// let angle: Rad<f32> = Rad::atan(0.5);
800    /// ```
801    fn atan(ratio: Self::Unitless) -> Self;
802
803    fn atan2(a: Self::Unitless, b: Self::Unitless) -> Self;
804}