pub struct ObjectId<T> { /* private fields */ }
Expand description
Represents an Object ID and a type that the ID points to, stored in Rust memory.
Use JsObjectId
if a reference stored in JavaScript memory is preferred.
Each object ID in Screeps: World is represented by an ID of up to 24
hexidemical characters, which cannot change. This implementation takes
advantage of that by storing a packed representation in a u128
, using 96
bits for the ID and 32 bits for tracking the length of the ID string for
reconstruction in JS.
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
RawObjectId
s
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§
source§impl<T> ObjectId<T>
impl<T> ObjectId<T>
sourcepub fn into_type<U>(self) -> ObjectId<U>
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.
sourcepub fn from_packed(packed: u128) -> Self
pub fn from_packed(packed: u128) -> 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
.
sourcepub fn to_u128(self) -> u128
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.
sourcepub fn to_array_string(&self) -> ArrayString<24>
pub fn to_array_string(&self) -> ArrayString<24>
Formats this object ID as a string on the stack.
This is equivalent to ToString::to_string
, but involves no
allocation.
See also RawObjectId::to_array_string
.
sourcepub fn try_resolve(self) -> Result<Option<T>, RoomObject>where
T: MaybeHasId + JsCast,
pub fn try_resolve(self) -> Result<Option<T>, RoomObject>where
T: MaybeHasId + JsCast,
Resolves this object ID into an object, verifying that the returned object matches the expected type.
Errors
Will return an error if this ID’s type does not match the object it
points to with the resolved RoomObject
with an unknown type.
Will return Ok(None)
if the object no longer exists, or is in a room
we don’t have vision for.
sourcepub fn resolve(self) -> Option<T>where
T: MaybeHasId + JsCast,
pub fn resolve(self) -> Option<T>where
T: MaybeHasId + JsCast,
Resolves this ID into an object, assuming the type T
is the correct
type of object that this ID refers to. If the ID has been converted to
an invalid type, using the returned object in a way not valid for its
type will cause a panic.
Will return None
if this object no longer exists, or is in a room we
don’t have vision for.
Trait Implementations§
source§impl<'de, T> Deserialize<'de> for ObjectId<T>
impl<'de, T> Deserialize<'de> for ObjectId<T>
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
source§impl<T> From<ObjectId<T>> for ArrayString<24>
impl<T> From<ObjectId<T>> for ArrayString<24>
source§impl<T> From<ObjectId<T>> for RawObjectId
impl<T> From<ObjectId<T>> for RawObjectId
source§impl<T> From<RawObjectId> for ObjectId<T>
impl<T> From<RawObjectId> for ObjectId<T>
source§fn from(raw: RawObjectId) -> Self
fn from(raw: RawObjectId) -> Self
source§impl<T> Ord for ObjectId<T>
impl<T> Ord for ObjectId<T>
source§impl<T> PartialEq<ObjectId<T>> for RawObjectId
impl<T> PartialEq<ObjectId<T>> for RawObjectId
source§impl<T> PartialEq<RawObjectId> for ObjectId<T>
impl<T> PartialEq<RawObjectId> for ObjectId<T>
source§fn eq(&self, other: &RawObjectId) -> bool
fn eq(&self, other: &RawObjectId) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl<T> PartialEq for ObjectId<T>
impl<T> PartialEq for ObjectId<T>
source§impl<T> PartialOrd<ObjectId<T>> for RawObjectId
impl<T> PartialOrd<ObjectId<T>> for RawObjectId
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd<RawObjectId> for ObjectId<T>
impl<T> PartialOrd<RawObjectId> for ObjectId<T>
source§fn partial_cmp(&self, other: &RawObjectId) -> Option<Ordering>
fn partial_cmp(&self, other: &RawObjectId) -> Option<Ordering>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T> PartialOrd for ObjectId<T>
impl<T> PartialOrd for ObjectId<T>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more