Struct screeps::ObjectId

pub struct ObjectId<T> { /* fields omitted */ }

Represents an Object ID and a type that the ID points to.

Each object id in screeps is represented by a Mongo GUID, which, while not guaranteed, is unlikely to change. This takes advantage of that by storing a packed representation of 12 bytes.

This object ID is typed, but not strictly. It's completely safe to create an ObjectId with an incorrect type, and all operations which use the type will double-check at runtime.

With that said, using this can provide nice type inference, and should have few disadvantages to the lower-level alternative, RawObjectId.

Conversion

Use into to convert between ObjectId<T> and RawObjectId, and ObjectId::into_type to change the type this ObjectId points to freely.

Ordering

To facilitate use as a key in a BTreeMap or other similar data structures, ObjectId implements PartialOrd and Ord.

ObjectId's are ordered by the corresponding order of their underlying byte values. This agrees with:

• lexicographical ordering of the object id strings
• JavaScript's ordering of object id strings
• ordering of RawObjectIds

Note: when running on the official screeps server, or on a private server backed by a MongoDB database, this ordering roughly corresponds to creation order. The first four bytes of a MongoDB-created ObjectId are seconds since the epoch when the id was created, so up to a second accuracy, these ids will be sorted by object creation time.

Implementations

impl<T> ObjectId<T>

pub fn into_type<U>(self) -> ObjectId<U>

Changes the type this ObjectId points to, unchecked.

This will allow changing to any type - ObjectId makes no guarantees about its ID matching the type of any object in the game that it actually points to.

pub fn from_packed(packed: [u32; 3]) -> Self

Creates an object ID from its packed representation.

The input to this function is the bytes representing the up-to-24 hex digits in the object id.

See also RawObjectId::from_packed.

pub fn from_packed_js_val(
    packed_val: Reference
) -> Result<Self, ConversionError>

Creates an object ID from a packed representation stored in JavaScript.

The input must be a reference to a length-3 array of integers.

Recommended to be used with the object_id_to_packed JavaScript utility function, which takes in a string and returns the array of three integers that this function expects.

Example

use screeps::{prelude::*, traits::TryInto, Creep, ObjectId};
use stdweb::js;

let packed_obj_id = (js! {
    let creep = _.sample(Game.creeps);
    return object_id_to_packed(creep.id);
})
.try_into()
.unwrap();

let parsed: ObjectId<Creep> = ObjectId::from_packed_js_val(packed_obj_id).unwrap();
println!("found creep with id {}", parsed);

See also RawObjectId::from_packed_js_val.

pub fn to_u128(self) -> u128

Converts this object ID to a u128 number.

The returned number, when formatted as hex, will produce a string parseable into this object id.

The returned number will be less than or equal to 2^96 - 1, as that's the maximum value that RawObjectId can hold.

pub fn to_array_string(&self) -> ArrayString<[u8; 24]>

Formats this object ID as a string on the stack.

This is equivalent to ToString::to_string, but involves no allocation.

To use the produced string in stdweb, use &* to convert it to a string slice.

This is less efficient than ObjectId::unsafe_as_uploaded, but easier to get right.

Example

use screeps::{prelude::*, Creep, ObjectId};
use stdweb::js;

let object_id = screeps::game::creeps::values()[0].id();

let str_repr = object_id.to_array_string();

js! {
    let id = @{&*str_repr};
    console.log("we have a creep with the id " + id);
}

See also RawObjectId::to_array_string.

pub unsafe fn unsafe_as_uploaded(&self) -> UnsafeTypedArray<'_, u32>

Creates an array accessible from JavaScript which represents part of this object id's packed representation.

Specifically, the resulting array will contain the first non-zero number in this object id, and all following numbers. This allows for a more efficient object_id_from_packed implementation.

Safety

This is highly unsafe.

This creates an UnsafeTypedArray and does not use it in JS, so the restrictions from UnsafeTypedArray apply. When you call into JavaScript using it, you must "use" it immediately before calling into any Rust code whatsoever.

There are other safety concerns as well, but all deriving from UnsafeTypedArray. See UnsafeTypedArray.

Example

use screeps::{prelude::*, Creep, ObjectId};
use stdweb::js;

let object_id = screeps::game::creeps::values()[0].id();

let array_view = unsafe { object_id.unsafe_as_uploaded() };

js! {
    let id = object_id_from_packed(@{array_view});
    console.log("we have a creep with the id " + id);
}

See also RawObjectId::unsafe_as_uploaded.

pub fn try_resolve(self) -> Result<Option<T>, ConversionError> where
    T: HasId + SizedRoomObject, 

Resolves this object ID into an object.

This is a shortcut for game::get_object_typed(id)

Errors

Will return an error if this ID's type does not match the object it points to.

Will return Ok(None) if the object no longer exists, or is in a room we don't have vision for.

pub fn resolve(self) -> Option<T> where
    T: HasId + SizedRoomObject, 

Resolves this ID into an object, panicking on type mismatch.

This is a shortcut for id.try_resolve().expect(...)

Panics

Will panic if this ID points to an object which is not of type T.

Will return None if this object no longer exists, or is in a room we don't have vision for.

Trait Implementations

impl<T> Clone for ObjectId<T>

fn clone(&self) -> ObjectId<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Copy for ObjectId<T>

impl<T> Debug for ObjectId<T>

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

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for ObjectId<T>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<T> Display for ObjectId<T>

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

Formats the value using the given formatter.

impl<T> Eq for ObjectId<T>

impl<T> From<[u32; 3]> for ObjectId<T>

fn from(packed: [u32; 3]) -> Self

Performs the conversion.

impl<T> From<ObjectId<T>> for RawObjectId

fn from(id: ObjectId<T>) -> Self

Performs the conversion.

impl<T> From<ObjectId<T>> for ArrayString<[u8; 24]>

fn from(id: ObjectId<T>) -> Self

Performs the conversion.

impl<T> From<ObjectId<T>> for String

fn from(id: ObjectId<T>) -> Self

Performs the conversion.

impl<T> From<ObjectId<T>> for u128

fn from(id: ObjectId<T>) -> Self

Performs the conversion.

impl<T> From<ObjectId<T>> for [u32; 3]

fn from(id: ObjectId<T>) -> Self

Performs the conversion.

impl<T> From<RawObjectId> for ObjectId<T>

fn from(raw: RawObjectId) -> Self

Performs the conversion.

impl<T> FromStr for ObjectId<T>

type Err = RawObjectIdParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, RawObjectIdParseError>

Parses a string s to return a value of this type.

impl<T> Hash for ObjectId<T>

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, 

Feeds a slice of this type into the given [Hasher].

impl<T> Ord for ObjectId<T>

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

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<T> PartialEq<ObjectId<T>> for ObjectId<T>

fn eq(&self, o: &ObjectId<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialEq<ObjectId<T>> for RawObjectId

fn eq(&self, other: &ObjectId<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialEq<RawObjectId> for ObjectId<T>

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<ObjectId<T>> for ObjectId<T>

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

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

impl<T> PartialOrd<ObjectId<T>> for RawObjectId

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

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

impl<T> PartialOrd<RawObjectId> for ObjectId<T>

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

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

impl<T> Serialize for ObjectId<T>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.

impl<T> TryFrom<u128> for ObjectId<T>

type Error = RawObjectIdParseError

The type returned in the event of a conversion error.

fn try_from(val: u128) -> Result<Self, RawObjectIdParseError>

Performs the conversion.