reven2.types._instance.FieldInstance

class documentation

class FieldInstance(_Generic[_ValueType]):

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:`object`	Undocumented
Returns
`bool`	Undocumented

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:`str`	Undocumented
Returns
`str`	Undocumented

def __hash__(self):

Returns the hash for this value.

Returns
`int`	Undocumented

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:`StructInstance`	Undocumented
field:`RegularField`	Undocumented

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:`object`	Undocumented
Returns
`bool`	Undocumented

def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
`str`	Undocumented

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
`ValueError`	if, 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
`ValueError`	if, 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
`ValueError`	if, 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
`ValueError`	if, 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
`ValueError`	if, 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
`ValueError`	if, 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
`ValueError`	if, 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
`SubPointerValueType`	the value pointed to by this field, of the type that is produced by the type pointed to by the pointer.
Raises
`ValueError`	if, 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
`ArrayInstance`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is an `ArrayInstance`.
Raises
`ValueError`	if, 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
`bool`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is a `bool`.
Raises
`ValueError`	if, 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
`bytes`	the value pointed to by this field, as bytes.
Raises
`ValueError`	if, 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
`EnumerationInstance`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is an `EnumerationInstance`.
Raises
`ValueError`	if, 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
`float`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is a `float`.
Raises
`ValueError`	if, 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
`int`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is an `int`.
Raises
`ValueError`	if, 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
`PointerInstance`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is a `PointerInstance`.
Raises
`ValueError`	if, 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:`_CString`	allows to specify the encoding and maximum size of the string to read.
Returns
`str`	the value pointed to by this field, as a string.
Raises
`ValueError`	if, according to its runtime type, this field does not produce a pointer value.
`EncodingError`	if 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
`StructInstance`	the same value as returned by `FieldInstance.deref`, with the additional typing information that the value is a `StructInstance`.
Raises
`ValueError`	if, 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:`int`	Undocumented
current_depth:`int`	Undocumented
Returns
`str`	Undocumented

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
`_ValueType`	the 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
`ArrayInstance`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is an `ArrayInstance`.
Raises
`ValueError`	if, 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
`bool`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `bool`.
Raises
`ValueError`	if, 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
`bytes`	a 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
`EnumerationInstance`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `EnumerationInstance`.
Raises
`ValueError`	if, 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
`float`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `float`.
Raises
`ValueError`	if, 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
`int`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `int`.
Raises
`ValueError`	if, 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
`PointerInstance`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `PointerInstance`.
Raises
`ValueError`	if, 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
`StructInstance`	the same value as returned by `FieldInstance.read`, with the additional typing information that the value is a `StructInstance`.
Raises
`ValueError`	if, 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