# Aniker GPS Library Usage Guide

This document provides detailed information on how to use the Aniker GPS library for parsing NMEA sentences.

## Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
aniker-gps = "0.1.0"
```

## Basic Usage

### Parsing a GGA Sentence

The most common use case is parsing a GGA sentence to extract position data:

```rust
use aniker_gps::{Position, parse_gga, GpsError};

fn main() {
    // Example NMEA GGA sentence
    let mut gga_example = "$GPGGA,210230,3855.4487,N,09446.0071,W,1,07,1.1,370.5,M,-29.5,M,,*7A".to_string();

    // Parse the GGA sentence and handle the result
    match parse_gga(&mut gga_example) {
        Ok(position) => {
            println!("Latitude: {}", position.lat);
            println!("Longitude: {}", position.long);
            println!("Altitude: {}", position.alt);
        }
        Err(e) => {
            println!("Error parsing GGA sentence:");
            match e {
                GpsError::InvalidMessageType => println!("  Invalid message type, expected GGA"),
                GpsError::InvalidLength => println!("  Invalid GGA sentence length"),
                GpsError::ParseError(msg) => println!("  Parse error: {}", msg),
                GpsError::Other(msg) => println!("  Other error: {}", msg),
            }
        }
    }
}
```

### Working with Position Data

The `Position` struct contains the following fields:

- `lat`: Latitude in decimal degrees (positive for North, negative for South)
- `long`: Longitude in decimal degrees (positive for East, negative for West)
- `alt`: Altitude in meters

You can access these fields directly:

```rust
let position = parse_gga(&mut gga_example).unwrap();
let latitude = position.lat;
let longitude = position.long;
let altitude = position.alt;
```

## Error Handling

The `parse_gga` function returns a `Result<Position, GpsError>`, which means it can either return a valid `Position` or a `GpsError`. The `GpsError` enum provides detailed error information:

- `GpsError::InvalidMessageType`: Returned when the message type is not GGA
- `GpsError::InvalidLength`: Returned when the GGA sentence has an incorrect number of fields
- `GpsError::ParseError(msg)`: Returned when parsing a specific field fails, with a description of the error
- `GpsError::Other(msg)`: Returned for other errors that don't fit into the above categories

Example of error handling:

```rust
match parse_gga(&mut gga_example) {
    Ok(position) => {
        // Use the position data
    }
    Err(e) => {
        // Handle the error
        match e {
            GpsError::InvalidMessageType => println!("Invalid message type, expected GGA"),
            GpsError::InvalidLength => println!("Invalid GGA sentence length"),
            GpsError::ParseError(msg) => println!("Parse error: {}", msg),
            GpsError::Other(msg) => println!("Other error: {}", msg),
        }
    }
}
```

## Advanced Usage

### Parsing Multiple Sentences

When working with multiple NMEA sentences, you can process them in a loop:

```rust
let sentences = vec![
    "$GPGGA,210230,3855.4487,N,09446.0071,W,1,07,1.1,370.5,M,-29.5,M,,*7A",
    "$GPGGA,210231,3855.4488,N,09446.0072,W,1,07,1.1,371.5,M,-29.5,M,,*7B",
];

for sentence in sentences {
    let mut sentence = sentence.to_string();
    match parse_gga(&mut sentence) {
        Ok(position) => {
            // Process the position
            println!("Latitude: {}, Longitude: {}", position.lat, position.long);
        }
        Err(e) => {
            // Handle the error
            match e {
                GpsError::InvalidMessageType => println!("Invalid message type, expected GGA"),
                GpsError::InvalidLength => println!("Invalid GGA sentence length"),
                GpsError::ParseError(msg) => println!("Parse error: {}", msg),
                GpsError::Other(msg) => println!("Other error: {}", msg),
            }
        }
    }
}
```

## Examples

Check out the examples directory for more detailed examples of how to use the library:

- `basic_usage.rs`: Simple example of parsing a GGA sentence
- `multiple_sentences.rs`: Example of parsing multiple sentences

## Running the Examples

To run the examples, use the following command:

```bash
cargo run --example basic_usage
```

## Running the Tests

To run the tests, use the following command:

```bash
cargo test
```