nav 0.2.0

Features

• Cardinal Directions: Complete representation of the four primary directions (North, East, South, West)
• 2D Transformations: Full implementation of the dihedral group D4 (rotations and reflections)
• Type Conversions: Convert between string representations, enum values, and numeric types
• Mathematical Operations: Compose transformations and apply them to directions
• Array Transformations (optional): Apply transformations to ndarray 2D arrays
• No Standard Library Requirement: Core-only implementation for embedded systems compatibility
• Comprehensive Testing: 100% test coverage

Installation

Add this to your Cargo.toml:

[dependencies]
nav = "0.2.0"

To enable array transformation support (adds ndarray dependency):

[dependencies]
nav = { version = "0.2.0", features = ["array"] }

Usage

Direction

The Direction enum represents the four cardinal directions: North, East, South, and West.

use nav::Direction;
use std::str::FromStr;

// Create directions
let north = Direction::North;
let east = Direction::East;

// Check direction properties
assert!(north.is_vertical());
assert!(east.is_horizontal());

// Get opposite direction
assert_eq!(-north, Direction::South);

// Convert to/from strings
assert_eq!(north.to_string(), "N");
assert_eq!(Direction::from_str("South").unwrap(), Direction::South);
assert_eq!("west".parse::<Direction>().unwrap(), Direction::West);

// Convert to/from numeric representation
let dir_value: u8 = north.into(); // 0
assert_eq!(Direction::try_from(2).unwrap(), Direction::South);

Transform

The Transform enum represents the eight possible transformations in the dihedral group D4:

use nav::Transform;
use std::str::FromStr;

// Create transforms
let identity = Transform::Identity;
let rotate90 = Transform::Rotate90;
let flip_h = Transform::FlipHorizontal;

// Check transform properties
assert!(identity.is_identity());
assert!(rotate90.is_rotation());
assert!(flip_h.is_flip());

// Compose transforms
let rotate180 = rotate90 * rotate90;
assert_eq!(rotate180, Transform::Rotate180);

// Applying inverse transformations returns to identity
assert_eq!(flip_h * flip_h, Transform::Identity);

// Convert to/from strings
assert_eq!(rotate90.to_string(), "R");
assert_eq!(Transform::from_str("|").unwrap(), Transform::FlipHorizontal);

Applying Transformations to Directions

You can apply transformations to directions using the multiplication operator:

use nav::{Direction, Transform};

// Apply rotations
assert_eq!(Direction::North * Transform::Rotate90, Direction::East);
assert_eq!(Direction::East * Transform::Rotate90, Direction::South);
assert_eq!(Direction::South * Transform::Rotate90, Direction::West);
assert_eq!(Direction::West * Transform::Rotate90, Direction::North);

// Apply reflections
assert_eq!(Direction::North * Transform::FlipHorizontal, Direction::North);
assert_eq!(Direction::East * Transform::FlipHorizontal, Direction::West);

Array Transformation (requires array feature)

Apply geometric transformations to 2D arrays using the ndarray crate:

use nav::Transform;
use ndarray::{arr2, Array2};

// Enable the "array" feature in Cargo.toml:
// nav = { version = "0.1.5", features = ["array"] }

// Create a 2D array
let arr = arr2(&[
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]);

// Apply transformations
let rotated = Transform::Rotate90 * &arr;
let flipped = Transform::FlipHorizontal * &arr;

assert_eq!(
    rotated,
    arr2(&[
        [7, 4, 1],
        [8, 5, 2],
        [9, 6, 3],
    ])
);

assert_eq!(
    flipped,
    arr2(&[
        [3, 2, 1],
        [6, 5, 4],
        [9, 8, 7],
    ])
);

Working with All Values

The library provides constants for all directions and transforms:

use nav::{ALL_DIRECTIONS, ALL_TRANSFORMS, Direction, Transform};

// Iterate through all directions
for dir in ALL_DIRECTIONS {
    println!("Direction: {}", dir);
}

// Iterate through all transformations
for transform in ALL_TRANSFORMS {
    println!("Transform: {}", transform);
}

Transform Symbols

The Transform enum uses single character symbols for string representation:

Features

This crate provides the following features:

• array: Enables array transformation functionality using the ndarray crate

Applications

This library is useful for:

• Game development (movement, rotation, grid-based operations)
• Cellular automata and grid-based simulations
• Procedural generation
• Puzzle solving algorithms
• Geometry processing

License

This project is licensed under the MIT License - see the LICENSE file for details.