maidenhead 0.2.0

A simple package to convert to/from maidenhead squares to latitude/longitude
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# Maidenhead

A simple Rust library for converting between Maidenhead grid squares
and latitude/longitude coordinates.

## Overview

Maidenhead grid squares are a coordinate system used by amateur radio
operators to specify locations on Earth. This library provides functions
to convert between grid squares and decimal degree coordinates, as well
as calculate distances and bearings between grid squares.

## Features

- Convert grid squares to latitude/longitude coordinates
- Convert latitude/longitude coordinates to grid squares (4, 6, 8, or 10 character precision)
- Calculate distance between two grid squares using the Haversine formula
- Calculate bearing between two grid squares
- Comprehensive error handling with descriptive error messages

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
maidenhead = "0.1.1"
```

### Examples

```rust
use maidenhead::*;

// Convert grid square to coordinates
let (longitude, latitude) = grid_to_longlat("FM18lv")?;
println!("Coordinates: {}, {}", longitude, latitude);

// Convert coordinates to grid square
let grid = longlat_to_grid(-77.035278, 38.889484, 6)?;
println!("Grid square: {}", grid);

// Calculate distance between two grid squares
let distance = grid_distance("FM18lv", "EN91")?;
println!("Distance: {:.2} km", distance);

// Calculate bearing between two grid squares
let bearing = grid_bearing("FM18lv", "EN91")?;
println!("Bearing: {:.1}°", bearing);

// Calculate both distance and bearing
let (distance, bearing) = grid_dist_bearing("FM18lv", "EN91")?;
println!("Distance: {:.2} km, Bearing: {:.1}°", distance, bearing);
```

## Grid Square Format

Grid squares follow the format: `FFSSssEEee` where:
- **FF**: Field (2 letters, A-R) - covers 20°/10° longitude/latitude
- **SS**: Square (2 digits, 0-9) - covers 2°/1° longitude/latitude  
- **ss**: Subsquare (2 letters, a-x) - covers 5'/2.5' longitude/latitude
- **EE**: Extended square (2 digits, 0-9) - covers 30"/15" longitude/latitude
- **ee**: Superextended square (2 letters, A-X) - covers 1.25"/0.625" longitude/latitude

Supported precisions: 4, 6, 8, or 10 characters.

## Error Handling

The library uses the `thiserror` crate for comprehensive error handling:

- `InvalidGrid`: Invalid grid square format
- `InvalidGridLength`: Unsupported grid square length
- `InvalidLongLat`: Coordinates out of valid range
- `Unknown`: Internal error during grid generation

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.