DTED2

https://docs.rs/dted2/1.0.0
Admin
DTED2 is a Rust library for parsing and handling DTED (Digital Terrain Elevation Data) files for...
Tokens:38,194
Snippets:384
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Invalid Angle Creation Examples

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

These examples illustrate invalid inputs for Angle creation that would typically panic due to minutes or seconds being out of range or negative.

```rust
let angle = Angle::new(45, 67, 4.0, false);
```

```rust
let angle = Angle::new(45, 4, 60.0, false);
```

```rust
let angle = Angle::new(45, 4, -4.0, false);
```

--------------------------------

### Create Angle from Degrees, Minutes, Seconds

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Shows how to construct an Angle using its components: degrees, minutes, seconds, and a sign. Includes examples of positive and negative angles and their expected second values.

```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 1, 1.0, false);
assert_eq!(angle, Angle::from_secs(61.0));

let angle = Angle::new(123, 45, 43.0, true);
assert_eq!(angle, Angle::from_secs(-445543.0));
```

--------------------------------

### Using RecognitionSentinel Values and Comparisons

Source: https://docs.rs/dted2/1.0.0/dted2/dted/enum.RecognitionSentinel.html

Demonstrates how to get the byte value of RecognitionSentinel variants and how to use them in comparisons and parsing functions. It shows assertions for variant values and a helper function `is_user_header_label`.

```rust
use nom::bytes::complete::tag;
use dted2::dted::RecognitionSentinel;

assert_eq!(RecognitionSentinel::UHL.value(), b"UHL1");
assert_eq!(RecognitionSentinel::DSI.value(), b"DSIU");
assert_eq!(RecognitionSentinel::ACC.value(), b"ACC");
assert_eq!(RecognitionSentinel::DATA.value(), &[0xAA]);

fn is_user_header_label(input: &[u8]) -> nom::IResult<&[u8], ()> {
    let (input, _) = tag(RecognitionSentinel::UHL.value())(input)?;
    Ok((input, ()))
}

assert!(is_user_header_label(b"DSI").is_err());
assert!(is_user_header_label(b"UHL1").is_ok());
assert!(is_user_header_label(b"xxxUHL1xxx").is_err());
```

--------------------------------

### Create Angle from Total Seconds

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Explains how to convert a total number of seconds (which can be negative) into an Angle representation using `from_secs`. It also shows an example of a large second value.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::from_secs(61.0), Angle::new(0, 1, 1.0, false));
assert_eq!(Angle::new(123, 45, 43.8, true).total_secs(), -445543.8);
```

```rust
use dted2::primitives::Angle;

Angle::from_secs(1e10);
```

--------------------------------

### Get Minutes from Angle

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Shows how to extract the minute component of an Angle using the `min` method. The returned value is always a positive integer.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).min(), 55);
assert_eq!(Angle::new(47, 4, 32.0, true).min(), 4)
```

--------------------------------

### Panic when creating Angle with negative seconds

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

This example demonstrates a panic scenario when the `new` constructor is called with negative seconds, violating the Angle invariants.

```rust
let angle = Angle::new(45, 4, -4.0, false);
```

--------------------------------

### Get Degrees from Angle

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Illustrates how to retrieve the degree component of an Angle using the `deg` method. Works for both positive and negative angles.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).deg(), 123);
assert_eq!(Angle::new(47, 4, 32.0, true).deg(), 47)
```

--------------------------------

### Get Seconds from Angle

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Demonstrates retrieving the second component of an Angle using the `sec` method. This value can be a floating-point number and is always positive.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).sec(), 28.2);
assert_eq!(Angle::new(47, 4, 32.0, true).sec(), 32.0)
```

--------------------------------

### Panic when creating Angle with invalid minutes

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

This example demonstrates a panic scenario when the `new` constructor is called with minutes greater than or equal to 60, violating the Angle invariants.

```rust
let angle = Angle::new(45, 67, 4.0, false);
```

--------------------------------

### Get the minutes component of an Angle

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Illustrates retrieving the minutes component from an Angle instance using the `min` method. The returned value is always a positive `u8`.

```rust
assert_eq!(Angle::new(123, 55, 28.2, false).min(), 55);
assert_eq!(Angle::new(47, 4, 32.0, true).min(), 4)
```

--------------------------------

### Panic when creating Angle with invalid seconds

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

This example demonstrates a panic scenario when the `new` constructor is called with seconds greater than or equal to 60, violating the Angle invariants.

```rust
let angle = Angle::new(45, 4, 60.0, false);
```

--------------------------------

### Get Elevation by Lat/Lon

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDData.html

Retrieves the elevation at a specific latitude and longitude. Returns None if the coordinates are outside the DTED file's bounds.

```rust
use dted2::DTEDData;
let dted_data = DTEDData::read("tests/test_data.dt2").unwrap();
assert!(dted_data.get_elevation(42.52, 15.75).is_some());
assert!(dted_data.get_elevation(0.0, 0.0).is_none());
```

--------------------------------

### Parse RawDTEDHeader using dted_uhl_parser

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.dted_uhl_parser.html

Use this parser to extract `RawDTEDHeader` information from a byte slice. Ensure the input slice starts with valid UHL data.

```rust
use dted2::dted::RawDTEDHeader;
use dted2::primitives::{ Angle, AxisElement };
use dted2::parsers::dted_uhl_parser;
use dted2::dted::RecognitionSentinel;

assert_eq!(dted_uhl_parser(b"UHL11234556E8901234W123456789012UUUXXXXXXXXXXXX123445670XXXXXXXXXXXXXXXXXXXXXXXX"), Ok((&b""[..], RawDTEDHeader {
    origin: AxisElement { lat: Angle::new(890, 12, 34.0, true), lon: Angle::new(123, 45, 56.0, false) },
    interval_secs_x_10: AxisElement { lat: 5678, lon: 1234 },
    accuracy: Some(9012),
    count: AxisElement { lat: 4567, lon: 1234 },
})));
```

--------------------------------

### Get the degrees component of an Angle

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Shows how to retrieve the degrees component from an Angle instance using the `deg` method. The returned value is always a positive `u16`.

```rust
assert_eq!(Angle::new(123, 55, 28.2, false).deg(), 123);
assert_eq!(Angle::new(47, 4, 32.0, true).deg(), 47)
```

--------------------------------

### Create and Compare Angles

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Demonstrates creating an Angle using `new` and comparing it with an angle created from seconds. Ensures correct conversion and handling of negative angles.

```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 1, 0.0, false);
assert_eq!(angle, Angle::from_secs(60.0));

let angle = Angle::new(1, 0, 0.0, true);
assert_eq!(angle, Angle::from_secs(-3600.0));
```

--------------------------------

### value() - Get Sentinel Value

Source: https://docs.rs/dted2/1.0.0/dted2/dted/enum.RecognitionSentinel.html

Returns the byte slice representation of the enum variant.

```APIDOC
## pub fn value(&self) -> &'static [u8]

Returns the value of the enum variant defined by `Const`.

### Returns

*   `&'static [u8]` - The byte slice representing the sentinel.
```

--------------------------------

### Get seconds of an Angle

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Retrieves the seconds component of an Angle. This is a direct getter for the seconds field.

```rust
pub fn sec(&self) -> f64 {
        self.sec
    }
```

--------------------------------

### Create Angle from degrees, minutes, and seconds

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Demonstrates creating an Angle instance using the `new` constructor with valid inputs. This method ensures that minutes and seconds adhere to the required constraints.

```rust
let angle = Angle::new(0, 1, 0.0, false);
assert_eq!(angle, Angle::from_secs(60.0));

let angle = Angle::new(1, 0, 0.0, true);
assert_eq!(angle, Angle::from_secs(-3600.0));
```

--------------------------------

### Get Indices by Lat/Lon

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDData.html

Calculates the internal data indices corresponding to a given latitude and longitude. Returns None if the coordinates are out of bounds.

```rust
use dted2::DTEDData;
let dted_data = DTEDData::read("tests/test_data.dt2").unwrap();
assert!(dted_data.get_indices(42.52, 15.75).is_some());
assert!(dted_data.get_indices(0.0, 0.0).is_none());
```

--------------------------------

### Angle Comparison

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Explains how Angle instances are compared for equality, considering positive and negative zero.

```APIDOC
## Angle Comparison

### `impl PartialEq for Angle`
Compares two `Angle` instances for equality. This implementation accounts for the special case where positive zero is considered equal to negative zero.

#### `fn eq(&self, other: &Self) -> bool`
Tests for `self` and `other` values to be equal, and is used by the `==` operator.

#### `fn ne(&self, other: &Rhs) -> bool`
Tests for inequality, used by the `!=` operator.

#### Examples
```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 1.0, false));
assert_ne!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 1.0, true));
assert_ne!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 2.0, false));
assert_eq!(Angle::new(0, 0, 0.0, false), Angle::new(0, 0, 0.0, true));
```
```

--------------------------------

### PartialEq<&[u8]> Implementation

Source: https://docs.rs/dted2/1.0.0/dted2/dted/enum.RecognitionSentinel.html

Allows comparison of RecognitionSentinel variants with byte slices.

```APIDOC
## impl PartialEq<&[u8]> for RecognitionSentinel

Tests for `self` and `other` values to be equal.

### Returns

*   `true` if the type and the enum are equal
*   `false` if the type and the enum are not equal
```

--------------------------------

### Create Angle with specific degrees, minutes, and seconds

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Illustrates creating an Angle instance with specific degree, minute, and second values, including a negative angle. The `new` function converts these into a total seconds representation.

```rust
let angle = Angle::new(0, 1, 1.0, false);
assert_eq!(angle, Angle::from_secs(61.0));

let angle = Angle::new(123, 45, 43.0, true);
assert_eq!(angle, Angle::from_secs(-445543.0));
```

--------------------------------

### TryFrom<&[u8]> Implementation

Source: https://docs.rs/dted2/1.0.0/dted2/dted/enum.RecognitionSentinel.html

Allows conversion from a byte slice to a RecognitionSentinel variant.

```APIDOC
## impl TryFrom<&[u8]> for RecognitionSentinel

Performs the conversion from a byte slice to a `RecognitionSentinel`.

### Returns

*   `Ok(T)` where `T` is the enum variant if the conversion is successful.
*   `Err(())` if the conversion fails.
```

--------------------------------

### CloneToUninit for Angle

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Provides an unsafe method to clone the Angle type into uninitialized memory. This is a nightly-only experimental API.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`.

### Method
`clone_to_uninit`

### Parameters
- `dest` (*mut u8) - The destination pointer for the cloned data.

### Safety
This function is unsafe because it operates on raw pointers and assumes `dest` is valid and sufficiently large to hold the cloned data.
```

--------------------------------

### Get DTED Indices

Source: https://docs.rs/dted2/1.0.0/src/dted2/dted.rs.html

Calculates the latitude and longitude indices for a given geographic coordinate within the DTED data bounds. Returns None if the coordinates are out of bounds.

```rust
/// Get the indices of a lat/lon
///
/// # Arguments
///
/// * `lat` - latitude
/// * `lon` - longitude
///
/// # Returns
///
/// * `(lat_index, lon_index)` or None if out of bounds
///
/// # Examples
///
/// ```
/// use dted2::DTEDData;
/// let dted_data = DTEDData::read("tests/test_data.dt2").unwrap();
/// assert!(dted_data.get_indices(42.52, 15.75).is_some());
/// assert!(dted_data.get_indices(0.0, 0.0).is_none());
/// ```
pub fn get_indices<T: Into<f64>, U: Into<f64>>(&self, lat: T, lon: U) -> Option<(f64, f64)> {
    // --------------------------------------------------
    // check bounds
    // --------------------------------------------------
    let lat: f64 = lat.into();
    let lon: f64 = lon.into();
    if lat < self.min.lat || lat > self.max.lat || lon < self.min.lon || lon > self.max.lon {
        return None;
    }
    let lat_idx = (lat - self.min.lat) / self.metadata.interval.lat;
    let lon_idx = (lon - self.min.lon) / self.metadata.interval.lon;
    Some((lat_idx, lon_idx))
}
```

--------------------------------

### Calculate Total Seconds of an Angle

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Demonstrates how to compute the total signed arc seconds represented by an Angle using the `total_secs` method. This is useful for precise comparisons and calculations.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(0, 1, 1.0, false).total_secs(), 61.0);
assert_eq!(Angle::new(123, 45, 43.8, true).total_secs(), -445543.8);
```

--------------------------------

### Create DTEDMetadata from Raw Header

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDMetadata.html

Constructs a DTEDMetadata instance from raw header data and a filename. Requires the `RawDTEDHeader` and filename as input.

```rust
pub fn from_header(raw: &RawDTEDHeader, fname: &str) -> DTEDMetadata
```

--------------------------------

### AxisElement::new Constructor

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.AxisElement.html

Creates a new AxisElement instance.

```APIDOC
### impl<T> AxisElement<T>

#### pub fn new(lat: T, lon: T) -> Self

Creates a new AxisElement instance.
```

--------------------------------

### Read and Query DTED Data

Source: https://docs.rs/dted2/1.0.0/dted2

Demonstrates how to read a DTED file into DTEDData and DTEDMetadata structures. It also shows how to query for specific elevation points. Ensure the DTED file exists at the specified path.

```rust
use dted2::{ DTEDData, DTEDMetadata };

let data = DTEDData::read("dted_file.dt2").unwrap();
let metadata: DTEDMetadata = data.metadata;
// or can read just the header without the rest of the data
let metadata: DTEDMetadata = DTEDData::read_header("dted_file.dt2").unwrap();

// query elevation, returns None if out of bounds
let elevation: f64 = data.get_elevation(50.0, 10.0).unwrap();
```

--------------------------------

### Clone to Uninit

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDMetadata.html

Performs copy-assignment from `self` to an uninitialized memory location. This is a nightly-only experimental API.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### DTED Metadata Creation from Raw Header

Source: https://docs.rs/dted2/1.0.0/src/dted2/dted.rs.html

Demonstrates how to create a `DTEDMetadata` struct from a `RawDTEDHeader`. This conversion handles precision adjustments and unit conversions for interval data.

```rust
DTEDMetadata {
    filename: fname.to_string(),
    origin: raw.origin.into(),
    origin_angle: raw.origin,
    interval: raw.interval_secs_x_10 / (primitives::SEC2DEG * 10.0),
    interval_secs: raw.interval_secs_x_10 / 10.0,
    accuracy: raw.accuracy,
    count: raw.count,
}
```

--------------------------------

### DTEDMetadata::from_header

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDMetadata.html

Creates a DTEDMetadata instance from raw header data and a filename.

```APIDOC
## impl DTEDMetadata

### pub fn from_header(raw: &RawDTEDHeader, fname: &str) -> DTEDMetadata

#### Description

Create a DTEDMetadata from a RawDTEDHeader

#### Arguments

* `raw` - RawDTEDHeader
* `fname` - filename

#### Returns

* DTEDMetadata: DTED metadata
```

--------------------------------

### Parse DTED Record

Source: https://docs.rs/dted2/1.0.0/src/dted2/parsers.rs.html

Parses a single DTED data record, extracting block byte information, longitude and latitude counts, and elevation data. It expects the input to start with the 'DATA' sentinel.

```rust
pub fn parse_dted_record(input: &[u8], line_len: usize) -> IResult<&[u8], RawDTEDRecord> {
    let (input, (block_byte0, block_rest, lon_count, lat_count, elevations, _)) = tuple(( 
        preceded(
            tag(RecognitionSentinel::DATA.value()),
            take(1_usize), // starting block byte size, will always be 0
        ),
        be_u16,
        be_u16,
        be_u16,
        count(signed_mag_parser, line_len),
        take(4_usize), // checksum
    ))(input)?;
    // --------------------------------------------------
    // return
    // --------------------------------------------------
    Ok((
        input,
        RawDTEDRecord {
            blk_count: block_byte0[0] as u32 * 0x10000 + block_rest as u32,
            lon_count,
            lat_count,
            elevations,
        },
    ))
}
```

--------------------------------

### Parse DTED File

Source: https://docs.rs/dted2/1.0.0/src/dted2/parsers.rs.html

Parses an entire DTED file, including its header, DSI record, ACC record, and data records. It uses `dted_uhl_parser` to get the header information and then parses the data records based on the header's count.

```rust
pub fn dted_file_parser(input: &[u8]) -> IResult<&[u8], RawDTEDFile> {
    // --------------------------------------------------
    // get headers and header records
    // --------------------------------------------------
    let (input, (header, _dsi_record, _acc_record)) = tuple(( 
        dted_uhl_parser,
        // TODO: parse DSI record
        // TODO: parse ACC record
        take(DT2_DSI_RECORD_LENGTH),
        take(DT2_ACC_RECORD_LENGTH),
    ))(input)?;
    // --------------------------------------------------
    // parse the actual data
    // --------------------------------------------------
    let (input, records) = count(
        |input| parse_dted_record(input, header.count.lat as usize),
        header.count.lon as usize,
    )(input)?;
    // --------------------------------------------------
    // return
    // --------------------------------------------------
    Ok((
        input,
        RawDTEDFile {
            header,
            data: records,
            dsi_record: None,
            acc_record: None,
        },
    ))
}
```

--------------------------------

### PartialEq for Angle

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Implements equality comparison for Angle, considering positive and negative zero as equal.

```APIDOC
## PartialEq for Angle

### Description
Compares two `Angle` instances for equality. It correctly handles the case where positive zero and negative zero are considered equal.

### Method
`impl PartialEq for Angle`

### Returns
- `bool`: `true` if the angles are equal, `false` otherwise.
```

--------------------------------

### Angle::new

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Constructs a new Angle from degrees, minutes, seconds, and a sign indicator. It enforces invariants that minutes and seconds must be less than 60, and seconds must be non-negative.

```APIDOC
## Angle::new

### Description
Converts degrees, minutes, and seconds to an angle.

### Method Signature
`pub fn new(deg: u16, min: u8, sec: f64, negative: bool) -> Self`

### Arguments
* `deg` - The number of degrees
* `min` - The number of minutes
* `sec` - The number of seconds (floating point precision), must always be non-negative
* `negative` - Whether or not the angle is negative

### Returns
The Angle with the number of degrees, minutes, and seconds.

### Panics
A panic will occur if either `min` or `sec` are at least 60, or if `sec` is negative.

### Examples
```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 1, 1.0, false);
assert_eq!(angle, Angle::from_secs(61.0));

let angle = Angle::new(123, 45, 43.0, true);
assert_eq!(angle, Angle::from_secs(-445543.0));
```
```

--------------------------------

### Angle Conversions to Numeric Types

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Demonstrates how to convert an Angle to various numeric types like f32, f64, i128, i16, i32, i64, and isize. These conversions typically represent the angle in radians.

```APIDOC
## Angle Conversions

### `impl From<Angle> for f32`
Converts an Angle (degrees, minutes, seconds) to radians as an `f32`.

### `impl From<Angle> for f64`
Converts an Angle (degrees, minutes, seconds) to radians as an `f64`.

### `impl From<Angle> for i128`
Converts an Angle (degrees, minutes, seconds) to radians as an `i128`.

### `impl From<Angle> for i16`
Converts an Angle (degrees, minutes, seconds) to radians as an `i16`.

### `impl From<Angle> for i32`
Converts an Angle (degrees, minutes, seconds) to radians as an `i32`.

### `impl From<Angle> for i64`
Converts an Angle (degrees, minutes, seconds) to radians as an `i64`.

### `impl From<Angle> for isize`
Converts an Angle (degrees, minutes, seconds) to radians as an `isize`.

#### Example Usage (for all `From<Angle>` implementations):
```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 0, 0.0, false);
let radians_f32: f32 = angle.into();
let radians_f64: f64 = angle.into();
let radians_i128: i128 = angle.into();
let radians_i16: i16 = angle.into();
let radians_i32: i32 = angle.into();
let radians_i64: i64 = angle.into();
let radians_isize: isize = angle.into();

assert_eq!(radians_f32, 0.0 as f32);
assert_eq!(radians_f64, 0.0 as f64);
assert_eq!(radians_i128, 0.0 as i128);
assert_eq!(radians_i16, 0.0 as i16);
assert_eq!(radians_i32, 0.0 as i32);
assert_eq!(radians_i64, 0.0 as i64);
assert_eq!(radians_isize, 0.0 as isize);
```
```

--------------------------------

### Read DTED File and Metadata

Source: https://docs.rs/dted2/1.0.0/dted2/index.html

Use `DTEDData::read` to load a DTED file into memory or `DTEDData::read_header` to load only the metadata. Ensure the file path is correct.

```rust
use dted2::{ DTEDData, DTEDMetadata };

let data = DTEDData::read("dted_file.dt2").unwrap();
let metadata: DTEDMetadata = data.metadata;
// or can read just the header without the rest of the data
let metadata: DTEDMetadata = DTEDData::read_header("dted_file.dt2").unwrap();
```

--------------------------------

### PartialEq Implementation for RawDTEDHeader

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.RawDTEDHeader.html

Enables comparison of two RawDTEDHeader instances for equality. This implementation is automatically derived.

```rust
impl PartialEq for RawDTEDHeader
```

--------------------------------

### Compare Angles for Equality

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Compares two Angle instances for equality, correctly handling positive and negative zero. This is crucial for accurate angular comparisons.

```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 1.0, false));
assert_ne!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 1.0, true));
assert_ne!(Angle::new(1, 1, 1.0, false), Angle::new(1, 1, 2.0, false));
assert_eq!(Angle::new(0, 0, 0.0, false), Angle::new(0, 0, 0.0, true));
```

--------------------------------

### AxisElement Division

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Demonstrates division operations for AxisElement with different types.

```APIDOC
## AxisElement<Angle> / AxisElement<Angle>

### Description
Divides a [AxisElement]<[Angle]> by another [AxisElement]<[Angle]>.

### Returns
* [AxisElement]<[Angle]>

### Method Signature
`fn div(self, rhs: Self) -> Self::Output`
```

```APIDOC
## AxisElement<Angle> / Angle

### Description
Divides a [AxisElement]<[Angle]> by a [Angle].

### Returns
* [AxisElement]<[Angle]>

### Method Signature
`fn div(self, rhs: Angle) -> Self::Output`
```

```APIDOC
## AxisElement<Angle> / D

### Description
Divides a [AxisElement]<[Angle]> by a scalar `D` (max precision of f64).

### Returns
* [AxisElement]<[Angle]>

### Method Signature
`fn div(self, rhs: D) -> Self::Output`
```

```APIDOC
## AxisElement<Angle> / AxisElement<D>

### Description
Divides a [AxisElement]<[Angle]> by a [AxisElement]`<D>`.

### Returns
* [AxisElement]<[Angle]>

### Method Signature
`fn div(self, rhs: AxisElement<D>) -> Self::Output`
```

```APIDOC
## AxisElement<T> / AxisElement<D>

### Description
Divides a [AxisElement]`<T>` by a [AxisElement]`<D>`.

### Returns
* [AxisElement]`<D>`

### Method Signature
`fn div(self, rhs: AxisElement<D>) -> Self::Output`
```

--------------------------------

### Div for Angle (Angle / Angle)

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Implements division for two Angle types.

```APIDOC
## Div for Angle (Angle / Angle)

### Description
Divides one `Angle` by another. The result is a new `Angle`.

### Method
`impl Div for Angle`

### Returns
- `Angle`: The result of the division.
```

--------------------------------

### Create Angle Parser

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.angle_parser.html

Use this parser to extract Angle data from byte slices, specifying the exact number of bytes for degrees, minutes, and seconds. It handles both signed and unsigned angle representations.

```rust
use dted2::primitives::Angle;
use dted2::parsers::angle_parser;
assert_eq!(angle_parser(3, 1, 1)(b"12345"), Ok((&b""[..], Angle::new(123, 4, 5.0, false))));
```

```rust
use dted2::primitives::Angle;
use dted2::parsers::angle_parser;
assert_eq!(angle_parser(3, 1, 1)(b"12345W"), Ok((&b""[..], Angle::new(123, 4, 5.0, true))));
```

--------------------------------

### Div<AxisElement<D>> for AxisElement<T>

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.AxisElement.html

Divides an AxisElement<T> by another AxisElement.

```APIDOC
### impl<D, T> Div<AxisElement<D>> for AxisElement<T>

Divides a AxisElement`<T>` by a AxisElement`<D>`
```

--------------------------------

### Angle Struct and Methods

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Documentation for the Angle struct, which represents an angle in degrees, minutes, and seconds, along with its constructor and accessor methods.

```APIDOC
## Angle::new

### Description
Converts degrees, minutes, and seconds to an angle.

### Arguments
* `deg` - The number of degrees
* `min` - The number of minutes
* `sec` - The number of seconds (floating point precision), must always be non-negative
* `negative` - Whether or nor the angle is negative

### Returns
The [Angle] with the number of degrees, minutes, and seconds

### Panics
A panic will occur if either `min` or `sec` are at least 60, or if `sec` is negative.

### Examples
```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 1, 1.0, false);
assert_eq!(angle, Angle::from_secs(61.0));

let angle = Angle::new(123, 45, 43.0, true);
assert_eq!(angle, Angle::from_secs(-445543.0));
```

```should_panic
# use dted2::primitives::Angle;
let angle = Angle::new(45, 67, 4.0, false);
```

```should_panic
# use dted2::primitives::Angle;
let angle = Angle::new(45, 4, 60.0, false);
```

```should_panic
# use dted2::primitives::Angle;
let angle = Angle::new(45, 4, -4.0, false);
```
```

```APIDOC
## Angle::is_negative

### Description
Returns whether or not the angle is negative.

### Examples
```rust
use dted2::primitives::Angle;

assert!(!Angle::from_secs(4567.0).is_negative());
assert!(Angle::from_secs(-4567.0).is_negative());
```
```

```APIDOC
## Angle::deg

### Description
Returns the positive integer number of degrees.

### Examples
```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).deg(), 123);
assert_eq!(Angle::new(47, 4, 32.0, true).deg(), 47)
```
```

```APIDOC
## Angle::min

### Description
Returns the positive integer number of minutes.

### Examples
```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).min(), 55);
assert_eq!(Angle::new(47, 4, 32.0, true).min(), 4)
```
```

```APIDOC
## Angle::sec

### Description
Returns the positive number of seconds.

### Examples
```rust
use dted2::primitives::Angle;

assert_eq!(Angle::new(123, 55, 28.2, false).sec(), 28.2);
```
```

--------------------------------

### Blanket Implementations for Generic Types

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.RawDTEDHeader.html

Shows common blanket implementations that apply to generic types, such as Any, Borrow, BorrowMut, From, Into, TryFrom, and TryInto. These are standard Rust trait implementations.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
```

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
```

```rust
impl<T> From<T> for T
```

```rust
impl<T, U>
where U: From<T>,
```

```rust
impl<T, U>
where U: TryFrom<T>,
```

```rust
impl<T, U>
where U: TryFrom<T>,
```

--------------------------------

### Conversion Constants

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Constants used for converting between degrees, minutes, and seconds.

```APIDOC
## Conversion Constants

### Description
Constants used for converting between different units of angular measurement.

### Constants
* `SEC2DEG`: Seconds to Degrees conversion factor (3600.0).
* `SEC2MIN`: Seconds to Minutes conversion factor (60.0).
* `MIN2DEG`: Minutes to Degrees conversion factor (60.0).
```

--------------------------------

### to_uint

Source: https://docs.rs/dted2/1.0.0/src/dted2/parsers.rs.html

Parses a byte slice into an unsigned integer. Supports up to 32 bits.

```APIDOC
## to_uint

### Description
Parses a byte slice into an unsigned integer. The maximum precision is 32 bits (4294967296).

### Arguments
* `input` - A byte slice

### Returns
An option containing an unsigned integer.

### Examples
```rust
use dted2::parsers::to_uint;
assert_eq!(to_uint::<u32>(b"123"), Some(123 as u32));
```
```

--------------------------------

### Div<AxisElement<D>> for AxisElement<Angle>

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.AxisElement.html

Divides an AxisElement<Angle> by another AxisElement.

```APIDOC
### impl<D> Div<AxisElement<D>> for AxisElement<Angle>

Divides a AxisElement<Angle> by a AxisElement`<D>`
```

--------------------------------

### Implement From<Error> for Error

Source: https://docs.rs/dted2/1.0.0/dted2/enum.Error.html

Allows converting an existing Error type into itself. This is a common pattern for error handling and propagation.

```rust
fn from(err: Error) -> Error
```

--------------------------------

### Read DTED File

Source: https://docs.rs/dted2/1.0.0/dted2/dted/struct.DTEDData.html

Reads an entire DTED file from the specified path. Ensure the file exists and is a valid DTED format.

```rust
use dted2::DTEDData;
assert!(DTEDData::read("tests/test_data.dt2").is_ok());
```

--------------------------------

### SEC2MIN Constant Definition

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/constant.SEC2MIN.html

Defines the constant SEC2MIN for converting seconds to minutes. Use this for calculations involving time unit conversions.

```rust
pub const SEC2MIN: f64 = 60.0;
```

--------------------------------

### Check if Angle is Negative

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Demonstrates the usage of the `is_negative` method to determine if an Angle represents a negative value.

```rust
use dted2::primitives::Angle;

assert!(!Angle::from_secs(4567.0).is_negative());
assert!(Angle::from_secs(-4567.0).is_negative());
```

--------------------------------

### Implement TryInto<U> for T

Source: https://docs.rs/dted2/1.0.0/dted2/enum.Error.html

Implements `try_into` for converting type `T` into type `U`. This operation may fail, returning a `Result` with an error type defined by `U`'s `TryFrom<T>` implementation.

```rust
type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Add for Angle

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Implements addition for Angle types.

```APIDOC
## Add for Angle

### Description
Adds two `Angle` instances together. The result is a new `Angle` representing the sum.

### Method
`impl Add for Angle`

### Returns
- `Angle`: The sum of the two angles.
```

--------------------------------

### Compare Angle equality

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Implements the PartialEq trait for the Angle struct. It considers positive and negative zero to be equal, but otherwise performs a standard comparison of degrees, minutes, seconds, and the sign.

```rust
impl PartialEq for Angle {
    fn eq(&self, other: &Self) -> bool {
        let is_zero = self.deg == 0 || self.min == 0 || self.sec == 0.0;
        (is_zero || self.negative == other.negative)
            && self.deg == other.deg
            && self.min == other.min
            && self.sec == other.sec
    }
}
```

--------------------------------

### Debug for AxisElement<T>

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.AxisElement.html

Enables debugging output for AxisElement.

```APIDOC
### impl<T: Debug> Debug for AxisElement<T>

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

Formats the value using the given formatter.
```

--------------------------------

### uint_parser

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.uint_parser.html

Parses a specified number of bytes into an unsigned integer. It takes the number of bytes to parse as an argument and returns a closure that accepts a byte slice and returns a Nom IResult.

```APIDOC
## Function uint_parser

### Signature
```rust
pub fn uint_parser<U>(count: usize) -> impl Fn(&[u8]) -> IResult<&[u8], U>
where
    U: PrimInt + Unsigned,
```

### Description
Nom parser that parses `count` number of bytes and returns an unsigned integer.

### Arguments
* `count` - The number of bytes to parse.

### Returns
A result containing an unsigned integer of length `count`, or an error if the input is invalid.

### Examples
```rust
use dted2::parsers::uint_parser;
assert_eq!(uint_parser::<u32>(3)(b"123"), Ok((&b""[..], 123 as u32)));
```
```

--------------------------------

### Convert Angle to i64 Radians

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Converts an Angle (degrees, minutes, seconds) to radians as an i64. Provides a larger range for integer radian values compared to i32.

```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 0, 0.0, false);
let radians: i64 = angle.into();
assert_eq!(radians, 0.0 as i64);
```

--------------------------------

### Function to_angle

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.to_angle.html

Parses a byte slice into a crate::primitives::Angle. It takes the input byte slice and the number of bytes to parse for degrees, minutes, and seconds.

```APIDOC
## to_angle

### Description
Parses a byte slice into a crate::primitives::Angle.

### Signature
```rust
pub fn to_angle(
    input: &[u8],
    num_deg: usize,
    num_min: usize,
    num_sec: usize,
) -> IResult<&[u8], Angle>
```

### Arguments
* `input` - A byte slice
* `num_deg` - The number of bytes to parse for degrees
* `num_min` - The number of bytes to parse for minutes
* `num_sec` - The number of bytes to parse for seconds

### Returns
An Option containing a crate::primitives::Angle

### Examples
```rust
use dted2::parsers::to_angle;
use dted2::primitives::Angle;
assert_eq!(to_angle(b"12345", 3, 1, 1), Ok((&b""[..], Angle::new(123, 4, 5.0, false))));
assert_eq!(to_angle(b"12345W", 3, 1, 1), Ok((&b""[..], Angle::new(123, 4, 5.0, true))));
```
```

--------------------------------

### Parse unsigned integer from bytes

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.uint_parser.html

Use this parser to convert a specified number of bytes from input into an unsigned integer. Ensure the input byte slice contains valid numeric characters.

```rust
use dted2::parsers::uint_parser;
assert_eq!(uint_parser::<u32>(3)(b"123"), Ok((&b""[..], 123 as u32)));
```

--------------------------------

### Mul for Angle (Angle * Angle)

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Implements multiplication for two Angle types.

```APIDOC
## Mul for Angle (Angle * Angle)

### Description
Multiplies two `Angle` instances together. The result is a new `Angle`.

### Method
`impl Mul for Angle`

### Returns
- `Angle`: The product of the two angles.
```

--------------------------------

### Test Angle Conversions

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Tests the conversion of an `Angle` struct to various primitive integer and floating-point types. Asserts that the conversion to `f64` results in the correct decimal representation and to integer types results in the truncated degree value.

```rust
#[test]
    /// Test [Angle] conversions to various primitive types
    fn angle_conversions() {
        let angle = Angle::new(123, 45, 43.8, true);

        assert_eq!(f64::from(angle), -123.76216666666667f64);
        assert_eq!(i16::from(angle), -123);
        assert_eq!(i32::from(angle), -123);
        assert_eq!(i64::from(angle), -123);
        assert_eq!(i128::from(angle), -123);
        assert_eq!(isize::from(angle), -123);
    }
```

--------------------------------

### Nom parser for unsigned integers

Source: https://docs.rs/dted2/1.0.0/src/dted2/parsers.rs.html

A `nom` parser that takes a specified number of bytes and converts them into an unsigned integer using `to_uint`. Returns an error if parsing fails.

```rust
pub fn uint_parser<U>(count: usize) -> impl Fn(&[u8]) -> IResult<&[u8], U>
where
    U: PrimInt + Unsigned,
{
    move |input| {
        map_res(take(count), |bytes: &[u8]| {
            to_uint::<U>(bytes).ok_or(nom::error::Error::new(input, nom::error::ErrorKind::Digit))
        })(input)
    }
}
```

--------------------------------

### Divide AxisElement<T> by AxisElement<D>

Source: https://docs.rs/dted2/1.0.0/src/dted2/primitives.rs.html

Divides an AxisElement<T> by an AxisElement<D>, converting to f64 for calculation and then back to D.

```rust
impl<D, T>
    Div<AxisElement<D>> for AxisElement<T>
where
    D: Copy + ToPrimitive + FromPrimitive,
    T: Copy + ToPrimitive,
{
    type Output = AxisElement<D>;
    fn div(self, rhs: AxisElement<D>) -> Self::Output {
        let rhs_lat: f64 = D::to_f64(&rhs.lat).expect("Failed to convert RHS lat to f64");
        let rhs_lon: f64 = D::to_f64(&rhs.lon).expect("Failed to convert RHS lon to f64");
        let lat: f64 = T::to_f64(&self.lat).expect("Failed to convert latitude to f64");
        let lon: f64 = T::to_f64(&self.lon).expect("Failed to convert longitude to f64");
        AxisElement {
            lat: D::from_f64(lat / rhs_lat).expect("Failed to convert latitude from f64"),
```

--------------------------------

### Parse Signed Magnitude i16

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.signed_mag_parser.html

Use this parser to convert byte slices into signed 16-bit integers following the signed magnitude format. Ensure the input slice contains valid signed magnitude data.

```rust
use dted2::parsers::signed_mag_parser;
assert_eq!(signed_mag_parser(&[0x00, 0x00]), Ok((&b""[..], 0)));
assert_eq!(signed_mag_parser(&[0x00, 0x03]), Ok((&b""[..], 3)));
assert_eq!(signed_mag_parser(&[0x80, 0x03]), Ok((&b""[..], -3)));
assert_eq!(signed_mag_mag_parser(&[0x7f, 0xff]), Ok((&b""[..], 32767)));
assert_eq!(signed_mag_parser(&[0xff, 0xff]), Ok((&b""[..], -32767)));
```

--------------------------------

### Parse Angle from Bytes

Source: https://docs.rs/dted2/1.0.0/src/dted2/parsers.rs.html

Creates a parser for DTED angle values. Specify the number of bytes for degrees, minutes, and seconds. Handles optional trailing 'W' for west longitude.

```rust
use dted2::primitives::Angle;
use dted2::parsers::angle_parser;
assert_eq!(angle_parser(3, 1, 1)(b"12345"), Ok((&b""[..], Angle::new(123, 4, 5.0, false))));
assert_eq!(angle_parser(3, 1, 1)(b"12345W"), Ok((&b""[..], Angle::new(123, 4, 5.0, true))));
```

--------------------------------

### Add<AxisElement<A>> for AxisElement<T>

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.AxisElement.html

Adds another AxisElement to an existing AxisElement.

```APIDOC
### impl<A, T> Add<AxisElement<A>> for AxisElement<T>

Adds a AxisElement`<A>` to a scalar AxisElement`<T>`, using max precision of f64

#### Example
```rust
use dted2::primitives::{AxisElement, Angle};

let a = AxisElement::new(10, 20);
let b = AxisElement::new(12, 32);
let c = a + b;
assert_eq!(c, AxisElement::new(22, 52));
```
```

--------------------------------

### to_i16 Function

Source: https://docs.rs/dted2/1.0.0/dted2/parsers/fn.to_i16.html

Converts a signed magnitude integer (formatted as u16) into an i16.

```APIDOC
## to_i16

### Description
Convert signed magnitude int to i16.

### Signature
```rust
pub fn to_i16(x: u16) -> i16
```

### Arguments
* `x` - The signed magnitude int (2 bytes, formatted as u16).

### Returns
An i16, converted from the signed magnitude int.

### Examples
```rust
use dted2::parsers::to_i16;

assert_eq!(to_i16(0x0000), 0);
assert_eq!(to_i16(0x0003), 3);
assert_eq!(to_i16(0x8003), -3);
assert_eq!(to_i16(0x7fff), 32767);
assert_eq!(to_i16(0xFFFF), -32767);
```
```

--------------------------------

### Convert Angle to isize Radians

Source: https://docs.rs/dted2/1.0.0/dted2/primitives/struct.Angle.html

Converts an Angle (degrees, minutes, seconds) to radians as an isize. This is platform-dependent and useful for system-level programming.

```rust
use dted2::primitives::Angle;

let angle = Angle::new(0, 0, 0.0, false);
let radians: isize = angle.into();
assert_eq!(radians, 0.0 as isize);
```
Tokens:
Raw