D°M'S"
======
[](https://github.com/gwbres/dms-coordinates/actions/workflows/rust.yml)
[](https://docs.rs/dms-coordinates/badge.svg)
[](https://crates.io/crates/dms-coordinates)
[](https://crates.io/crates/dms-coordinates)
[](https://github.com/gwbres/dms-coordinates/blob/main/LICENSE-APACHE)
[](https://github.com/gwbres/dms-coordinates/blob/main/LICENSE-MIT)
`D°M'S"` represents an angle in sexagesimal format, where
* D° for degrees, positive integer, 0 <= D° < 360° in case
no cardinal associated to it
* M' for minutes, 0 <= M' < 60, 60'=1D°
* S" for fractionnal seconds, double precision, 0 <= S" < 60, 60"=1'
* Optionnal Cardinal point, among "N", "S", "E", "W"
```rust
let dms = dms_coordinates::DMS::new(40, 43, 50.196, None);
assert_eq!(dms.degrees, 40);
assert_eq!(dms.minutes, 43);
assert_float_relative_eq!(dms.seconds, 50.196, 1E-6);
assert_eq!(dms.cardinal, None);
```
A couple other methods are available
```rust
// Total amount of S" (unit basis) in D°M'S"
let dms = DMS::new(0, 10, 55.0);
total = dms.total_seconds();
assert_eq!(total, 10*60+55);
// Build D°M'S" from total amount of seconds
let d = DMS::from_seconds(total);
assert_eq!(dms, d);
```
D°M'S" supports overflow and wrapps internal so D°, M' and S"
remain within predefined ranges.
For instance, overflows are allowed when building a D°M'S":
```rust
let dms = DMS::new(10, 61, 0.0);
assert_eq!(dms.degrees, 11); // 61' = 1°+1'
assert_eq!(dms.minutes, 1);
```
It is possible to cast a D°M'S" angle into
* a `f64` number: you get the total amount of seconds, with fractionnal and double precision
* a `f32` number: you get the total amount of seconds, with fractionnal part and precision loss (6 digits)
* `u64`, `u32`, `u16`, `u8` : you get the total amount of seconds, but fractionnal part is lost
```rust
let dms = DMS::new(0, 1, 30.33);
let secs : f64 = dms.into();
assert_eq!(secs, 60.0+30.33);
let secs : u32 = dms.into();
assert_eq!(secs, 1*60+30); // fractionnal part is lost
```
## Arithmetics
D°M'S" supports all basic mathematical operations, for convenient
operations performed in navigation (like course and angle calculations).
It is possible to perform (*) (/) (+) and (-)
* between two D°M'S" angles
* between one D°M'S" angle and a number
### Operations with another angle
D°M'S" (+) D°M'S"
```rust
let d0 = DMS::new(0, 10, 55.0);
let d1 = DMS::new(0, 20, 5.0);
let d = d0 + d1;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 31);
assert_eq!(d.seconds, 0.0);
```
D°M'S" (-) D°M'S"
```rust
let d0 = DMS::new(0, 20, 55.0);
let d1 = DMS::new(0, 3, 5.0);
let d = d0 - d1;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 17);
assert_eq!(d.seconds, 50.0);
```
* D°M'S" (*) D°M'S" is not feasible
* D°M'S" (/) D°M'S" is not feasible
I doubt these have a practical use
### Operations with a number
D°M'S" (+) ɑ: we consider ɑ in seconds
```rust
// add 5"
let d = DMS::new(0, 20, 55.0) + 5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 21);
assert_eq!(d.seconds, 0.0);
// add 10" with fractionnal part
let d = DMS::new(0, 59, 50.0) + 10.3;
assert_eq!(d.degrees, 1);
assert_eq!(d.minutes, 0);
assert_eq!(d.seconds, 0.3);
```
D°M'S" (-) ɑ: we consider ɑ in seconds
```rust
// substract 5"
let d = DMS::new(0, 20, 55.0) + 5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 20);
assert_eq!(d.seconds, 50.0);
// substract 10" with fractionnal part
let d = DMS::new(0, 59, 9.0) - 10.3;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 58);
assert_eq!(d.seconds, 59.7);
```
D°M'S" (*) ɑ: we consider ɑ as an integral ratio
```rust
// multiply by factor of 5
let d = DMS::new(0, 1, 10.0) * 5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 5);
assert_eq!(d.seconds, 50.0);
// multiply by factor of 5.5
let d = DMS::new(0, 1, 10.0) * 5.5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 5);
assert_eq!(d.seconds, 55.0);
// divide by 2
let d = DMS::new(0, 1, 10.0) *0.5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 0);
assert_eq!(d.seconds, 5.0);
```
D°M'S" (/) ɑ: we consider ɑ as an integral ratio
```rust
// divide by factor of 5
let d = DMS::new(0, 1, 10.0) / 5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 0);
assert_eq!(d.seconds, 2.0);
// divide by fractionnal factor
let d = DMS::new(0, 1, 10.0) / 5.5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 1.8181);
// multiply by 2
let d = DMS::new(0, 1, 10.0) /0.5;
assert_eq!(d.degrees, 0);
assert_eq!(d.minutes, 2);
assert_eq!(d.seconds, 20.0);
```