Struct RoomXY

pub struct RoomXY {
    pub x: RoomCoordinate,
    pub y: RoomCoordinate,
}

An X/Y pair representing a given coordinate relative to any room.

Fields

x: RoomCoordinate

y: RoomCoordinate

Implementations

impl RoomXY

pub fn towards(self, target: RoomXY, distance_towards_target: i8) -> RoomXY

Calculates an approximate midpoint between this point and the target.

In case of a tie, rounds towards this point.

If distance_towards_target is bigger than the distance to the target, the target is returned.

Example

// Exact distances
let start = RoomXY::checked_new(10, 10).unwrap();
let target = RoomXY::checked_new(10, 15).unwrap();
assert_eq!(
    start.towards(target, 1),
    RoomXY::checked_new(10, 11).unwrap()
);
assert_eq!(
    start.towards(target, 4),
    RoomXY::checked_new(10, 14).unwrap()
);
assert_eq!(
    start.towards(target, 10),
    RoomXY::checked_new(10, 15).unwrap()
);

// Approximate/rounded distances
let start = RoomXY::checked_new(10, 10).unwrap();
let target_1 = RoomXY::checked_new(15, 20).unwrap();
let target_2 = RoomXY::checked_new(0, 5).unwrap();
assert_eq!(
    start.towards(target_1, 1),
    RoomXY::checked_new(10, 11).unwrap()
);
assert_eq!(
    start.towards(target_1, 9),
    RoomXY::checked_new(14, 19).unwrap()
);
assert_eq!(
    start.towards(target_2, 1),
    RoomXY::checked_new(9, 10).unwrap()
);

pub fn between(self, target: RoomXY, distance_from_target: i8) -> RoomXY

Calculates an approximate midpoint between this point and the target.

In case of a tie, rounds towards the target.

If distance_from_target is bigger than the distance to the target, this position is returned.

Note: This is essentially the same as RoomXY::towards, just rounding towards the target instead of the starting position.

Example

// Exact distances
let start = RoomXY::checked_new(10, 15).unwrap();
let target = RoomXY::checked_new(10, 10).unwrap();
assert_eq!(
    start.between(target, 1),
    RoomXY::checked_new(10, 11).unwrap()
);
assert_eq!(
    start.between(target, 4),
    RoomXY::checked_new(10, 14).unwrap()
);
assert_eq!(
    start.between(target, 10),
    RoomXY::checked_new(10, 15).unwrap()
);

// Approximate/rounded distances
let start_1 = RoomXY::checked_new(15, 20).unwrap();
let start_2 = RoomXY::checked_new(0, 5).unwrap();
let target = RoomXY::checked_new(10, 10).unwrap();
assert_eq!(
    start_1.between(target, 1),
    RoomXY::checked_new(10, 11).unwrap()
);
assert_eq!(
    start_1.between(target, 9),
    RoomXY::checked_new(14, 19).unwrap()
);
assert_eq!(
    start_2.between(target, 1),
    RoomXY::checked_new(9, 10).unwrap()
);

pub fn midpoint_between(self, target: RoomXY) -> RoomXY

Calculates an approximate midpoint between this point and the target.

In case of a tie, rounds towards the target.

Example

// Exact distances
let start = RoomXY::checked_new(10, 10).unwrap();

let target_1 = RoomXY::checked_new(10, 16).unwrap();
assert_eq!(
    start.midpoint_between(target_1),
    RoomXY::checked_new(10, 13).unwrap()
);

let target_2 = RoomXY::checked_new(20, 10).unwrap();
assert_eq!(
    start.midpoint_between(target_2),
    RoomXY::checked_new(15, 10).unwrap()
);

let target_3 = RoomXY::checked_new(12, 12).unwrap();
assert_eq!(
    start.midpoint_between(target_3),
    RoomXY::checked_new(11, 11).unwrap()
);

let target_4 = RoomXY::checked_new(4, 4).unwrap();
assert_eq!(
    start.midpoint_between(target_4),
    RoomXY::checked_new(7, 7).unwrap()
);

// Approximate/rounded distances
let start = RoomXY::checked_new(10, 10).unwrap();

let target_1 = RoomXY::checked_new(10, 15).unwrap();
assert_eq!(
    start.midpoint_between(target_1),
    RoomXY::checked_new(10, 13).unwrap()
);

let target_2 = RoomXY::checked_new(19, 10).unwrap();
assert_eq!(
    start.midpoint_between(target_2),
    RoomXY::checked_new(15, 10).unwrap()
);

let target_3 = RoomXY::checked_new(11, 11).unwrap();
assert_eq!(
    start.midpoint_between(target_3),
    RoomXY::checked_new(11, 11).unwrap()
);

let target_4 = RoomXY::checked_new(15, 15).unwrap();
assert_eq!(
    start.midpoint_between(target_4),
    RoomXY::checked_new(13, 13).unwrap()
);

impl RoomXY

pub fn offset(&mut self, x: i8, y: i8)

Returns a new position offset from this position by the specified x coords and y coords.

Unlike Position::offset, this function operates on room coordinates, and will panic if the new position overflows the room.

To return a new position rather than modifying in place, use pos + (x, y). See the implementation of Add<(i8, i8)> for RoomXY further down on this page.

Panics

Will panic if the new position overflows the room.

Example

let mut pos = RoomXY::checked_new(21, 21).unwrap();
pos.offset(5, 5);
assert_eq!(pos, RoomXY::checked_new(26, 26).unwrap());

let mut pos = RoomXY::checked_new(21, 21).unwrap();
pos.offset(-5, 5);
assert_eq!(pos, RoomXY::checked_new(16, 26).unwrap());

impl RoomXY

pub fn get_direction_to(self, target: RoomXY) -> Option<Direction>

Gets linear direction to the specified position.

Note that this chooses between Top/Bottom/Left/Right and TopLeft/TopRight/BottomLeft/BottomRight by the magnitude in both directions. For instance, Direction::Top can be returned even if the target has a slightly different x coordinate.

pub fn get_range_to(self, target: RoomXY) -> u8

Gets linear range to the specified position.

Linear range (also called Chebyshev Distance) is an alternate calculation of distance, calculated as the greater of the distance along the x axis or the y axis. Most calculations in Screeps use this distance metric. For more information see Chebeshev Distance.

Examples

let pos_1 = RoomXY::checked_new(5, 10).unwrap();
let pos_2 = RoomXY::checked_new(8, 15).unwrap();
// The differences are 3 along the X axis and 5 along the Y axis
// so the linear distance is 5.
assert_eq!(pos_1.get_range_to(pos_2), 5);

pub fn in_range_to(self, target: RoomXY, range: u8) -> bool

Checks whether this position is in the given range of another position.

Linear range (also called Chebyshev Distance) is an alternate calculation of distance, calculated as the greater of the distance along the x axis or the y axis. Most calculations in Screeps use this distance metric. For more information see Chebeshev Distance.

Examples

let pos_1 = RoomXY::checked_new(5, 10).unwrap();
let pos_2 = RoomXY::checked_new(8, 10).unwrap();

// The differences are 3 along the X axis and 0 along the Y axis
// so the linear distance is 3.
assert_eq!(pos_1.in_range_to(pos_2, 5), true);

let pos_3 = RoomXY::checked_new(8, 15).unwrap();

// The differences are 3 along the X axis and 5 along the Y axis
// so the linear distance is 5.
// `in_range_to` returns true if the linear distance is equal to the range
assert_eq!(pos_1.in_range_to(pos_3, 5), true);

let pos_4 = RoomXY::checked_new(20, 20).unwrap();
// The differences are 15 along the X axis and 10 along the Y axis
// so the linear distance is 15.
assert_eq!(pos_1.in_range_to(pos_4, 5), false);
assert_eq!(pos_1.in_range_to(pos_4, 10), false);
assert_eq!(pos_1.in_range_to(pos_4, 15), true);

pub fn is_equal_to(self, target: RoomXY) -> bool

Checks whether this position is the same as the specified position.

Examples

let pos_1 = RoomXY::checked_new(5, 10).unwrap();
let pos_2 = RoomXY::checked_new(5, 10).unwrap();
let pos_3 = RoomXY::checked_new(4, 9).unwrap();

assert_eq!(pos_1.is_equal_to(pos_2), true);
assert_eq!(pos_1.is_equal_to(pos_3), false);

pub fn is_near_to(self, target: RoomXY) -> bool

True if the range from this position to the target is at most 1.

Examples

let pos_1 = RoomXY::checked_new(5, 10).unwrap();
let pos_2 = RoomXY::checked_new(6, 10).unwrap();
let pos_3 = RoomXY::checked_new(4, 9).unwrap();
let pos_4 = RoomXY::checked_new(20, 20).unwrap();

assert_eq!(pos_1.is_near_to(pos_2), true);
assert_eq!(pos_1.is_near_to(pos_3), true);
assert_eq!(pos_1.is_near_to(pos_4), false);

impl RoomXY

pub fn new(x: RoomCoordinate, y: RoomCoordinate) -> Self

Create a new RoomXY from a pair of RoomCoordinate.

pub fn checked_new(x: u8, y: u8) -> Result<RoomXY, OutOfBoundsError>

Create a new RoomXY from a pair of u8, checking that they’re in the range of valid values.

pub unsafe fn unchecked_new(x: u8, y: u8) -> Self

Create a RoomXY from a pair of u8, without checking whether it’s in the range of valid values.

Safety

Calling this method with x >= ROOM_SIZE or y >= ROOM_SIZE can result in undefined behaviour when the resulting RoomXY is used.

pub const fn is_room_edge(self) -> bool

Get whether this coordinate pair represents an edge position (0 or 49 for either coordinate)

pub fn checked_add(self, rhs: (i8, i8)) -> Option<RoomXY>

Get the coordinate adjusted by a certain value, returning None if the result is outside the valid room area.

Example usage:

use screeps::local::RoomXY;

let zero = unsafe { RoomXY::unchecked_new(0, 0) };
let one = unsafe { RoomXY::unchecked_new(1, 1) };
let forty_nine = unsafe { RoomXY::unchecked_new(49, 49) };

assert_eq!(zero.checked_add((1, 1)), Some(one));
assert_eq!(zero.checked_add((-1, 0)), None);
assert_eq!(zero.checked_add((49, 49)), Some(forty_nine));
assert_eq!(forty_nine.checked_add((1, 1)), None);

pub fn saturating_add(self, rhs: (i8, i8)) -> RoomXY

Get the coordinate adjusted by a certain value, saturating at the edges of the room if the result would be outside the valid room area.

Example usage:

use screeps::local::RoomXY;

let zero = unsafe { RoomXY::unchecked_new(0, 0) };
let one = unsafe { RoomXY::unchecked_new(1, 1) };
let forty_nine = unsafe { RoomXY::unchecked_new(49, 49) };

assert_eq!(zero.saturating_add((1, 1)), one);
assert_eq!(zero.saturating_add((-1, 0)), zero);
assert_eq!(zero.saturating_add((49, 49)), forty_nine);
assert_eq!(zero.saturating_add((i8::MAX, i8::MAX)), forty_nine);
assert_eq!(forty_nine.saturating_add((1, 1)), forty_nine);
assert_eq!(forty_nine.saturating_add((i8::MIN, i8::MIN)), zero);

pub fn checked_add_direction(self, rhs: Direction) -> Option<RoomXY>

Get the neighbor of a given RoomXY in the given direction, returning None if the result is outside the valid room area.

Example usage:

use screeps::{constants::Direction::*, local::RoomXY};

let zero = unsafe { RoomXY::unchecked_new(0, 0) };
let one = unsafe { RoomXY::unchecked_new(1, 1) };
let forty_nine = unsafe { RoomXY::unchecked_new(49, 49) };

assert_eq!(zero.checked_add_direction(BottomRight), Some(one));
assert_eq!(zero.checked_add_direction(TopLeft), None);
assert_eq!(one.checked_add_direction(TopLeft), Some(zero));
assert_eq!(forty_nine.checked_add_direction(BottomRight), None);

pub fn saturating_add_direction(self, rhs: Direction) -> RoomXY

Get the neighbor of a given RoomXY in the given direction, saturating at the edges if the result is outside the valid room area.

Example usage:

use screeps::{constants::Direction::*, local::RoomXY};

let zero = unsafe { RoomXY::unchecked_new(0, 0) };
let one = unsafe { RoomXY::unchecked_new(1, 1) };
let forty_nine = unsafe { RoomXY::unchecked_new(49, 49) };

assert_eq!(zero.saturating_add_direction(BottomRight), one);
assert_eq!(zero.saturating_add_direction(TopLeft), zero);
assert_eq!(one.saturating_add_direction(TopLeft), zero);
assert_eq!(forty_nine.saturating_add_direction(BottomRight), forty_nine);

pub fn neighbors(self) -> Vec<RoomXY>

Get all the valid neighbors of a given RoomXY.

Example usage:

use screeps::local::RoomXY;

let zero_zero = unsafe { RoomXY::unchecked_new(0, 0) };
let zero_one = unsafe { RoomXY::unchecked_new(0, 1) };
let one_zero = unsafe { RoomXY::unchecked_new(1, 0) };
let one_one = unsafe { RoomXY::unchecked_new(1, 1) };

let zero_two = unsafe { RoomXY::unchecked_new(0, 2) };
let one_two = unsafe { RoomXY::unchecked_new(1, 2) };
let two_two = unsafe { RoomXY::unchecked_new(2, 2) };
let two_one = unsafe { RoomXY::unchecked_new(2, 1) };
let two_zero = unsafe { RoomXY::unchecked_new(2, 0) };

let zero_zero_neighbors = zero_zero.neighbors();

assert_eq!(zero_zero_neighbors.len(), 3);
assert!(zero_zero_neighbors.contains(&zero_one));
assert!(zero_zero_neighbors.contains(&one_one));
assert!(zero_zero_neighbors.contains(&one_zero));

let one_one_neighbors = one_one.neighbors();

assert_eq!(one_one_neighbors.len(), 8);
assert!(one_one_neighbors.contains(&zero_zero));
assert!(one_one_neighbors.contains(&zero_one));
assert!(one_one_neighbors.contains(&one_zero));
assert!(one_one_neighbors.contains(&zero_two));
assert!(one_one_neighbors.contains(&one_two));
assert!(one_one_neighbors.contains(&two_two));
assert!(one_one_neighbors.contains(&two_one));
assert!(one_one_neighbors.contains(&two_zero));

Trait Implementations

impl Add<(i8, i8)> for RoomXY

fn add(self, (x, y): (i8, i8)) -> Self

Adds an (x, y) pair to this position’s coordinates.

Panics

Will panic if the new position is outside standard room bounds.

Example

let pos1 = RoomXY::checked_new(42, 42).unwrap();
let pos2 = pos1 + (7, 7);
assert_eq!(pos2, RoomXY::checked_new(49, 49).unwrap());

type Output = RoomXY

The resulting type after applying the + operator.

impl Add<Direction> for RoomXY

fn add(self, direction: Direction) -> Self

Adds a Direction to this position’s coordinates.

Panics

Will panic if the new position is outside standard room bounds.

Example

let pos1 = RoomXY::checked_new(49, 40).unwrap();
let pos2 = pos1 + Direction::Top;
assert_eq!(pos2, RoomXY::checked_new(49, 39).unwrap());

type Output = RoomXY

The resulting type after applying the + operator.

impl Clone for RoomXY

fn clone(&self) -> RoomXY

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RoomXY

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

Formats the value using the given formatter.

impl Default for RoomXY

fn default() -> RoomXY

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for RoomXY

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for RoomXY

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

Formats the value using the given formatter.

impl From<(RoomCoordinate, RoomCoordinate)> for RoomXY

fn from(xy: (RoomCoordinate, RoomCoordinate)) -> RoomXY

Converts to this type from the input type.

impl From<Position> for RoomXY

fn from(pos: Position) -> RoomXY

Converts to this type from the input type.

impl From<RoomXY> for (RoomCoordinate, RoomCoordinate)

fn from(xy: RoomXY) -> (RoomCoordinate, RoomCoordinate)

Converts to this type from the input type.

impl From<RoomXY> for (u8, u8)

fn from(xy: RoomXY) -> (u8, u8)

Converts to this type from the input type.

impl Hash for RoomXY

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<RoomXY> for LocalCostMatrix

type Output = u8

The returned type after indexing.

fn index(&self, xy: RoomXY) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> Index<RoomXY> for XMajor<T>

type Output = T

The returned type after indexing.

fn index(&self, index: RoomXY) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> Index<RoomXY> for YMajor<T>

type Output = T

The returned type after indexing.

fn index(&self, index: RoomXY) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<RoomXY> for LocalCostMatrix

fn index_mut(&mut self, xy: RoomXY) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T> IndexMut<RoomXY> for XMajor<T>

fn index_mut(&mut self, index: RoomXY) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T> IndexMut<RoomXY> for YMajor<T>

fn index_mut(&mut self, index: RoomXY) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl Ord for RoomXY

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for RoomXY

fn eq(&self, other: &RoomXY) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for RoomXY

fn partial_cmp(&self, other: &RoomXY) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for RoomXY

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<(i8, i8)> for RoomXY

fn sub(self, (x, y): (i8, i8)) -> Self

Subtracts an (x, y) pair from this position’s coordinates.

Panics

Will panic if the new position is outside standard room bounds.

Example

let pos1 = RoomXY::checked_new(49, 40).unwrap();
let pos2 = pos1 - (49, 0);
assert_eq!(pos2, RoomXY::checked_new(0, 40).unwrap());

type Output = RoomXY

The resulting type after applying the - operator.

impl Sub<Direction> for RoomXY

fn sub(self, direction: Direction) -> Self

Subtracts a Direction from this position’s coordinates.

Panics

Will panic if the new position is outside standard room bounds.

Example

let pos1 = RoomXY::checked_new(49, 40).unwrap();
let pos2 = pos1 - Direction::Top;
assert_eq!(pos2, RoomXY::checked_new(49, 41).unwrap());

type Output = RoomXY

The resulting type after applying the - operator.

impl Sub for RoomXY

fn sub(self, other: RoomXY) -> (i8, i8)

Subtracts the other position from this one, extracting the difference as the output.

Example

let pos1 = RoomXY::checked_new(40, 40).unwrap();
let pos2 = RoomXY::checked_new(0, 20).unwrap();
assert_eq!(pos1 - pos2, (40, 20));

let pos3 = RoomXY::checked_new(45, 45).unwrap();
assert_eq!(pos1 - pos3, (-5, -5));

type Output = (i8, i8)

The resulting type after applying the - operator.

impl TryFrom<(u8, u8)> for RoomXY

type Error = OutOfBoundsError

The type returned in the event of a conversion error.

fn try_from(xy: (u8, u8)) -> Result<RoomXY, OutOfBoundsError>

Performs the conversion.

impl Copy for RoomXY

impl Eq for RoomXY

impl StructuralPartialEq for RoomXY