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}