class documentation

class FieldInstance(_Generic[_ValueType]):

View In Hierarchy

A field instance, the result of reading a field from a StructInstance.

You can obtain the value of the field by calling the FieldInstance.read method. The returned value will be of the natural type produced by the type of the field.

>>> value = struct_instance.field("Length").read()
>>> value
48

If you are using a type checker such as mypy or an IDE, you may want to annotate the produced type:

>>> value : int = struct_instance.field("Length").read()

However, the annotation will silently be wrong should you mistake the value produced by the field.

FieldInstance also provides the FieldInstance.assert_int, FieldInstance.assert_float, etc. methods to check the produced type at runtime, raising if there is a mistake, and allowing to drop the type annotation on the left side:

>>> value = struct_instance.field("Length").assert_int().read()

The FieldInstance.read_int, FieldInstance.read_float, etc. methods are a shortcut equivalent to calling assert followed by read.

>>> value = struct_instance.field("Length").read_int()

You can also always get the value of the field as bytes with the FieldInstance.read_bytes method.

When the field is of pointer type, the FieldInstance.deref family of functions allows to produce the pointed value without explicitly going through the intermediate PointerInstance.

Lastly, get the information about the field in its structure (name, type, offset) with the FieldInstance.info property, or link back to the StructInstance of origin with FieldInstance.parent_instance.

Method __eq__ Compares the instance for equality with an object.
Method __format__ Formats the value according to the specified options.
Method __hash__ Returns the hash for this value.
Method __init__ Initializes a new field instance from the struct instance of origin and the selected field.
Method __ne__ Compares the instance for equality with an object.
Method __str__ Returns the nicely printable string representation of this instance.
Method assert_array Asserts to the type system that this field produces an array value.
Method assert_bool Asserts to the type system that this field produces a boolean value.
Method assert_enum Asserts to the type system that this field produces a EnumerationInstance value.
Method assert_float Asserts to the type system that this field produces a float value.
Method assert_int Asserts to the type system that this field produces an integer value.
Method assert_ptr Asserts to the type system that this field produces a pointer value.
Method assert_struct Asserts to the type system that this field produces a StructInstance value.
Method deref If this field produces a pointer, dereferences the field and get the value pointed to by the pointer.
Method deref_array Dereferences the value of this field after asserting to the type system that this field produces a pointer to an array value.
Method deref_bool Dereferences the value of this field after asserting to the type system that this field produces a pointer to a boolean value.
Method deref_bytes If this field produces a pointer, dereferences the field to get the value pointed to by the pointer, interpreted as bytes.
Method deref_enum Dereferences the value of this field after asserting to the type system that this field produces a pointer to an enum value.
Method deref_float Dereferences the value of this field after asserting to the type system that this field produces a pointer to a float value.
Method deref_int Dereferences the value of this field after asserting to the type system that this field produces a pointer to an integer value.
Method deref_ptr Dereferences the value of this field after asserting to the type system that this field produces a pointer to a pointer value.
Method deref_str If this field produces a pointer, dereferences the field to get the value pointed to by the pointed, interpreted as a null-terminated string.
Method deref_struct Dereferences the value of this field after asserting to the type system that this field produces a pointer to a struct value.
Method format Undocumented
Method read Read the value of the field.
Method read_array Reads the value of this field after asserting to the type system that this field produces an array value.
Method read_bool Reads the value of this field after asserting to the type system that this field produces a boolean value.
Method read_bytes Read the value of this field as bytes.
Method read_enum Reads the value of this field after asserting to the type system that this field produces an enum value.
Method read_float Reads the value of this field after asserting to the type system that this field produces a float value.
Method read_int Reads the value of this field after asserting to the type system that this field produces an integer value.
Method read_ptr Reads the value of this field after asserting to the type system that this field produces a pointer value.
Method read_struct Reads the value of this field after asserting to the type system that this field produces a struct value.
Class Variable SubArrayValueType Undocumented
Class Variable SubPointerValueType Undocumented
Property info The information (offset, name) about the field associated with this instance.
Property parent_instance The struct instance that this instance originates from.
Instance Variable _field Undocumented
Instance Variable _struct Undocumented
def __eq__(self, o):

Compares the instance for equality with an object.

  • if the object is of type bytes, it will be considered equal to this instance if it is equal to the underlying bytes that this instance is made of.
  • two FieldInstances are considered equal if they have the same underlying Struct, Field and bytes.
  • if the object is neither bytes nor FieldInstance, then it will never be considered equal.

Note

  • The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two FieldInstances at different contexts with the same type and bytes will be considered equal.
  • Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two FieldInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bytes.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __format__(self, format_spec):

Formats the value according to the specified options.

The options are expected to be in the format described by reven2.util.parse_colon_separated_key_values.

The options will be passed as argument to format.

See StructInstance.__format__ for examples.

Parameters
format_spec:strUndocumented
Returns
strUndocumented
def __hash__(self):

Returns the hash for this value.

Returns
intUndocumented
def __init__(self, struct_instance, field):

Initializes a new field instance from the struct instance of origin and the selected field.

Warnings

At the moment, this object is not meant to be constructed directly. Use StructInstance.field instead.

Parameters
struct_instance:StructInstanceUndocumented
field:RegularFieldUndocumented
def __ne__(self, o):

Compares the instance for equality with an object.

  • if the object is of type bytes, it will be considered equal to this instance if it is equal to the underlying bytes that this instance is made of.
  • two FieldInstances are considered equal if they have the same underlying Struct, Field and bytes.
  • if the object is neither bytes nor FieldInstance, then it will never be considered equal.

Note

  • The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two FieldInstances at different contexts with the same type and bytes will be considered equal.
  • Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two FieldInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bytes.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def assert_array(self):

Asserts to the type system that this field produces an array value.

Information

Returns
FieldInstance[ArrayInstance]this field instance, with the additional typing information that its produced value is an array.
Raises
ValueErrorif, according to its runtime type, this field does not produce an array value.
def assert_bool(self):

Asserts to the type system that this field produces a boolean value.

Information

Returns
FieldInstance[bool]this field instance, with the additional typing information that its produced value is a bool.
Raises
ValueErrorif, according to its runtime type, this field does not produce a boolean value.
def assert_enum(self):

Asserts to the type system that this field produces a EnumerationInstance value.

Information

Returns
FieldInstance[EnumerationInstance]this field instance, with the additional typing information that its produced value is an enumeration.
Raises
ValueErrorif, according to its runtime type, this field does not produce an enumeration value.
def assert_float(self):

Asserts to the type system that this field produces a float value.

Information

Returns
FieldInstance[float]this field instance, with the additional typing information that its produced value is a float.
Raises
ValueErrorif, according to its runtime type, this field does not produce a float value.
def assert_int(self):

Asserts to the type system that this field produces an integer value.

Information

Returns
FieldInstance[int]this field instance, with the additional typing information that its produced value is an int.
Raises
ValueErrorif, according to its runtime type, this field does not produce an integer value.
def assert_ptr(self):

Asserts to the type system that this field produces a pointer value.

Information

Returns
FieldInstance[PointerInstance]this field instance, with the additional typing information that its produced value is a pointer.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer value.
def assert_struct(self):

Asserts to the type system that this field produces a StructInstance value.

Information

Returns
FieldInstance[StructInstance]this field instance, with the additional typing information that its produced value is a struct.
Raises
ValueErrorif, according to its runtime type, this field does not produce a struct value.
def deref(self):

If this field produces a pointer, dereferences the field and get the value pointed to by the pointer.

Information

Returns
SubPointerValueTypethe value pointed to by this field, of the type that is produced by the type pointed to by the pointer.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer value.
def deref_array(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to an array value.

Calling this method is equivalent to self.assert_ptr().read().assert_array().deref().

Information

Returns
ArrayInstancethe same value as returned by FieldInstance.deref, with the additional typing information that the value is an ArrayInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to an array value.
def deref_bool(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to a boolean value.

Calling this method is equivalent to self.assert_ptr().read().assert_bool().deref().

Information

Returns
boolthe same value as returned by FieldInstance.deref, with the additional typing information that the value is a bool.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to a boolean value.
def deref_bytes(self):

If this field produces a pointer, dereferences the field to get the value pointed to by the pointer, interpreted as bytes.

Information

Returns
bytesthe value pointed to by this field, as bytes.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer value.
def deref_enum(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to an enum value.

Calling this method is equivalent to self.assert_ptr().read().assert_enum().deref().

Information

Returns
EnumerationInstancethe same value as returned by FieldInstance.deref, with the additional typing information that the value is an EnumerationInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to an enum value.
def deref_float(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to a float value.

Calling this method is equivalent to self.assert_ptr().read().assert_float().deref().

Information

Returns
floatthe same value as returned by FieldInstance.deref, with the additional typing information that the value is a float.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to a float value.
def deref_int(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to an integer value.

Calling this method is equivalent to self.assert_ptr().read().assert_int().deref().

Information

Returns
intthe same value as returned by FieldInstance.deref, with the additional typing information that the value is an int.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to an integer value.
def deref_ptr(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to a pointer value.

Calling this method is equivalent to self.assert_ptr().read().assert_ptr().deref().

Information

Returns
PointerInstancethe same value as returned by FieldInstance.deref, with the additional typing information that the value is a PointerInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to a pointer value.
def deref_str(self, cstring):

If this field produces a pointer, dereferences the field to get the value pointed to by the pointed, interpreted as a null-terminated string.

Information

Parameters
cstring:_CStringallows to specify the encoding and maximum size of the string to read.
Returns
strthe value pointed to by this field, as a string.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer value.
EncodingErrorif the bytes pointed to by the field contain errors wrt to the specified encoding.
def deref_struct(self):

Dereferences the value of this field after asserting to the type system that this field produces a pointer to a struct value.

Calling this method is equivalent to self.assert_ptr().read().assert_struct().deref().

Information

Returns
StructInstancethe same value as returned by FieldInstance.deref, with the additional typing information that the value is a StructInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer, or does not produce a pointer to a struct value.
def format(self, max_depth=1, current_depth=1):

Undocumented

Parameters
max_depth:intUndocumented
current_depth:intUndocumented
Returns
strUndocumented
def read(self):

Read the value of the field.

Warning

Unlike what happens in Context.read, reading a pointer will return a PointerInstance rather than an address.

Information

Returns
_ValueTypethe value of this field, of the type that is produced by the type of this field.
def read_array(self):

Reads the value of this field after asserting to the type system that this field produces an array value.

Calling this method is equivalent to self.assert_array().read().

Information

Returns
ArrayInstancethe same value as returned by FieldInstance.read, with the additional typing information that the value is an ArrayInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce an array value.
def read_bool(self):

Reads the value of this field after asserting to the type system that this field produces a boolean value.

Calling this method is equivalent to self.assert_bool().read().

Information

Returns
boolthe same value as returned by FieldInstance.read, with the additional typing information that the value is a bool.
Raises
ValueErrorif, according to its runtime type, this field does not produce a boolean value.
def read_bytes(self):

Read the value of this field as bytes.

Information

Returns
bytesa buffer of bytes of size equal to the size of the type of this field.
def read_enum(self):

Reads the value of this field after asserting to the type system that this field produces an enum value.

Calling this method is equivalent to self.assert_enum().read().

Information

Returns
EnumerationInstancethe same value as returned by FieldInstance.read, with the additional typing information that the value is a EnumerationInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce an enum value.
def read_float(self):

Reads the value of this field after asserting to the type system that this field produces a float value.

Calling this method is equivalent to self.assert_float().read().

Information

Returns
floatthe same value as returned by FieldInstance.read, with the additional typing information that the value is a float.
Raises
ValueErrorif, according to its runtime type, this field does not produce a float value.
def read_int(self):

Reads the value of this field after asserting to the type system that this field produces an integer value.

Calling this method is equivalent to self.assert_int().read().

Information

Returns
intthe same value as returned by FieldInstance.read, with the additional typing information that the value is a int.
Raises
ValueErrorif, according to its runtime type, this field does not produce an integer value.
def read_ptr(self):

Reads the value of this field after asserting to the type system that this field produces a pointer value.

Calling this method is equivalent to self.assert_ptr().read().

Information

Returns
PointerInstancethe same value as returned by FieldInstance.read, with the additional typing information that the value is a PointerInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a pointer value.
def read_struct(self):

Reads the value of this field after asserting to the type system that this field produces a struct value.

Calling this method is equivalent to self.assert_struct().read().

Information

Returns
StructInstancethe same value as returned by FieldInstance.read, with the additional typing information that the value is a StructInstance.
Raises
ValueErrorif, according to its runtime type, this field does not produce a struct value.
SubArrayValueType =

Undocumented

SubPointerValueType =

Undocumented

@property
info: RegularField =

The information (offset, name) about the field associated with this instance.

@property
parent_instance: StructInstance =

The struct instance that this instance originates from.

_field =

Undocumented

_struct =

Undocumented