IInstance abstract#

The central element of the ISO 10303 application protocol model is the ENTITY.

ENTITY types represent fundamental objects in the EXPRESS modeling language (ISO 10303-11), defining structured data types with attributes that can be primitive types, selects, other entities, or collections.

Why IInstance is Powerful:#

The IInstance interface provides multiple paradigms for working with entity data:

1. Fine-grained API: Type-safe methods for precise attribute manipulation
2. Declarative JSON API: Batch operations via setAttributesByJson() for complex hierarchies
3. Path-based navigation: Universal attribute addressing with PIAttributePath
4. Hybrid model: Support for both composed instances and reference-based relationships

This combination enables:

• Performance: Batch operations for complex data structures
• Flexibility: Multiple ways to achieve the same outcome based on use case
• Interoperability: JSON interface familiar to web developers
• Precision: Type-safe methods for schema-compliant manipulation
• Navigation: Complex data traversal through path-based addressing

Path-Based API: Universal Data Access#

The path-based API provides a unified way to access and manipulate data anywhere in the instance hierarchy. Paths can:

• Traverse through multiple instance boundaries
• Navigate through selects and aggregates
• Address individual elements in multi-dimensional collections
• Work with both composed instances and instance references

This eliminates the need for complex navigation code and provides a consistent interface for accessing data regardless of its depth or complexity in the model.

A Fundamental Rule of ISO 10303:#

In all standard exchange formats (Part 21, Part 28, Part 26), attributes of an ENTITY type must be encoded as references. This prevents data duplication and enables complex data sharing across a model.

Example EXPRESS definition:#

ENTITY point2d;
  coordinates : LIST [2:2] OF REAL;
END_ENTITY;

ENTITY line2d;
  points : LIST [2:2] OF point2d; // ← point2d attribute is a reference
END_ENTITY;

PIComposer's Hybrid Model:#

While the standard mandates references for exchange, IInstance implements a hybrid model for in-memory processing that extends this paradigm:

1. Objectified References: IInstance can act as a lightweight reference handle (InstanceHandle), faithfully representing the standard's model.

2. Fully Populated Instances: IInstance can also be a complete, composition-contained object—a PIComposer enhancement for optimized performance and simpler manipulation of sub-graphs.

This dual nature is managed through completeness and composability:

• When an IInstance contains no external references, it is complete
• An attribute that is not a reference is a composition, forming an atomic, internally consistent data unit

Key Characteristics:#

• Maintains compliance with ISO 10303's reference-based exchange requirement
• Enables efficient in-memory processing through optional composition
• Every instance can container other instances (as references or compositions)
• Instances can store sharable instances in special buckets called composites
• Instances may have inverse links - reference objects that point to other instances, useful for managing object life cycles
• All composed attribute values are path-addressable, providing universal instance data management capabilities

This approach enables flexible data modeling while maintaining both the structural integrity required by ISO 10303 standards and the performance required for practical application development.

Buffer Management and Memory Model#

PIComposer uses a sophisticated buffer-based memory model to optimize performance and memory usage when working with ISO 10303 data.

Buffer Ownership Hierarchy#

Two EXPRESS data types—ENTITY and SELECT—maintain buffers that store their underlying data. These buffers form a hierarchical relationship:

• Master Buffer: The top-level instance in a composition owns the master buffer that contains all nested attribute data in a contiguous memory region
• Child Buffers: Inner Entity and Select instances typically share their parent's master buffer, acting as views into specific regions of that buffer

Detaching from Master Buffer#

Inner Entity and Select instances can gain independent buffer ownership by:

1. Calling the detach() method on the instance
2. Setting the detach: true flag when calling getXXX methods (e.g., getInstance(detach: true))

When detached, the instance creates its own private copy of the relevant data, transitioning from InstanceRunTimeType.attached to InstanceRunTimeType.free. This is essential when the parent buffer may be modified and you need the child instance to remain independent and unchanged.

In-Place Mutation Optimization#

For many fixed-size primitive types whose mutation does not change the buffer size, updates occur in situ (directly in the original buffer location):

• Primitive types: INTEGER, REAL, BOOLEAN, ENUM (fixed-size values)
• Fixed-size aggregates: Arrays with fixed dimensions
• String/Binary with fixed length: When defined with a fixed size in the schema

Key implication: When an inner attribute instance mutates a fixed-size primitive value, it actually modifies the master buffer directly, even though it appears to be operating on its own instance. This means changes are immediately visible to the parent instance and any other views into the same buffer region.

When to Use Detach#

Detach an instance when:

• You need to modify a child instance independently of its parent
• The parent buffer will undergo changes (e.g., via setAttributesByJson())
• You want to extract a subgraph for independent processing
• You need to ensure data isolation between operations

Example: Detach for Independent Modification#

// Get a profile from an extruded area solid (initially shares buffer)
final profile = extrude.getInstance("SweptArea");

// Detach BEFORE modifying the parent buffer
profile.detach();  // profile now has independent buffer

// Modify parent buffer - profile remains unchanged
extrude.setAttributesByJson({
  "ExtrudedDirection": {
    "@type": "IfcDirection",
    "DirectionRatios": [0.0, 0.0, 1.0]
  }
});

// profile.getRunTimeType() now returns InstanceRunTimeType.free
// profile can be safely modified without affecting extrude

Buffer State Transitions#

• attached: Instance shares parent's buffer (default for composed children)
• free: Instance has its own independent buffer (after detach)
• reference: Instance is a lightweight reference handle to another instance

This flexible buffer management system enables both the memory efficiency of shared buffers and the data independence required for complex manipulation scenarios.

PIComposer introduces the concept of path and path addressable attribute value to provide a universal interface to access and manage instance attributes: attributes can be managed by name or by path, enabling both precise control and broad navigation capabilities within complex data hierarchies.

Constructors#

IInstance()#

Properties#

attributeCount no setter#

Gets the total number of attributes for this instance.

Includes both defined and derived attributes in the count.

int get attributeCount;

attributeNames no setter#

Gets all attribute names defined for this instance.

Returns a list of all attribute names, including inherited attributes from supertypes, in the order they are defined in the schema.

List<String> get attributeNames;

descriptor no setter#

Gets the entity descriptor for this instance.

Returns the IEntityDescriptor that provides metadata about this instance's type definition, attributes, and schema information.

IEntityDescriptor get descriptor;

dirty no setter#

Indicates whether this instance has been modified since last persistence.

The dirty flag is automatically managed by the system but can be manually controlled for specific operations.

bool get dirty;

hash no setter#

Gets the unique 64-bit int hash value of this instance.

This hash is typically used for quick comparison and identification purposes within the PIComposer system.

int get hash;

hashCode no setter inherited#

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

external int get hashCode;

instanceHandle no setter#

Gets the instance handle serving as the persistent key.

The instance handle is used as the key for persistent storage in the key-value store and contains both instance ID and type ID.

InstanceHandle get instanceHandle;

instanceId read / write#

getter:

Gets the unique instance identifier.

This ID uniquely identifies this instance within its model context.

setter:

Sets the unique instance identifier.

instanceId: The new unique identifier for this instance. Use with caution, as changing IDs can affect referential integrity.

int get instanceId;

set instanceId(int instanceId);

instanceRunTimeType no setter#

Get the instance run time type.

InstanceRunTimeType get instanceRunTimeType;

instanceSchema no setter#

Gets the schema this instance was originally created from.

This may differ from modelSchema when multiple schemas are used within a single model (e.g., header instances from the header schema).

SupportedSchema get instanceSchema;

isDetach no setter#

is instance detached from other instance/select and has ownership of its own memory buffer.

bool get isDetach;

isInstanceReference no setter#

Indicates whether this instance is a reference to another instance.

Returns true if this instance acts as an object-based handle (reference) to another instance, false if it is a fully populated instance.

bool get isInstanceReference;

isNull no setter inherited#

Indicates whether the object represents a null value.

Returns true if the object is considered null according to its implementation, false otherwise.

Inherited from INullableObject.

bool get isNull;

modelSchema no setter#

Gets the primary schema of the model containing this instance.

Returns the SupportedSchema enumeration value representing the main schema used by the model that contains this instance.

SupportedSchema get modelSchema;

referencedTypeId no setter#

Gets the type identifier of the referenced instance.

Only valid when isInstanceReference is true. Returns the type ID of the instance that this reference points to.

int get referencedTypeId;

runtimeType no setter inherited#

A representation of the runtime type of the object.

Inherited from Object.

external Type get runtimeType;

schema no setter#

Gets the schema object that defines this instance's type.

Returns the ISchema that contains the type definition for this instance.

ISchema get schema;

typeId no setter#

Gets the unique type identifier of this instance.

Returns a hash-based integer ID representing the EXPRESS entity type of this instance.

int get typeId;

typeName no setter#

Gets the type name of this instance.

Returns the EXPRESS entity type name as defined in the schema.

String get typeName;

versionId read / write#

getter:

Gets the version identifier for this instance.

The version ID is automatically incremented each time the instance is saved to persistent storage, providing optimistic concurrency control.

setter:

Sets the version identifier for this instance.

versionId: The new version identifier. Typically managed automatically by the persistence layer.

int get versionId;

set versionId(int versionId);

Methods#

addAttribute()#

Adds a attribute value to an aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

value: The attribute value to add to the aggregate. attName: The name of the aggregate attribute. attIndex: The zero-based index of the aggregate attribute.

Returns true if the value was successfully added. Returns false if the attribute doesn't exist, or is not a aggregate type.

bool addAttribute<T>(T value, {String? attName, int? attIndex});

addComposite()#

Adds a composite instance to this instance.

inst: The composite instance to add to this instance's composite bucket.

Returns true if the composite was successfully added. Returns false if error.

bool addComposite(IInstance inst);

addCompositeDynamic()#

complement to addComposite and addComposites. Use in blockly scripting engine.

bool addCompositeDynamic(dynamic composite);

addComposites()#

Adds composite instances to this instance.

insts: The composite instance to add to this instance's composite bucket.

Returns true if the composites were successfully added. Returns false if error.

bool addComposites(List<IInstance> insts);

addInstanceRef()#

Adds an instance reference to an aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

inst: The entity instance to create a reference to and add. attName: The name of the ENTITYS attribute. attIndex: The zero-based index of the ENTITYS attribute. addInverse: If true, automatically adds an inverse reference from the target instance back to this instance.

Returns true if the reference was successfully created and added. Returns false if the attribute doesn't exist, or is not an ENTITYS type.

bool addInstanceRef(IInstance inst,
    {String? attName, int? attIndex, bool addInverse = true});

addInverse()#

Adds an inverse reference to this instance.

This method maintains the bidirectional relationship integrity by tracking which other instances reference this instance, enabling proper life cycle management and cascade operations.

inst: The instance handle representing the inverse reference to add. The handle should point to an instance that maintains a reference to this instance.

Note: This method typically manages the internal inverse reference collection and is often called automatically by reference setter methods when addInverse is set to true.

bool addInverse(InstanceHandle inst);

addInverseDynamic()#

complement to addInverse and addInverses. Use in Blockly scripting engine

bool addInverseDynamic(dynamic inverse);

addInverses()#

Adds multiple inverse references to this instance.

This batch operation is essential for efficiently establishing complex relationship networks and ensuring complete life cycle management coverage when working with large object graphs.

inverses: A list of instances that maintain inverse references to this instance.

Returns true if all inverse references were successfully added. Returns false if any inverse reference could not be added.

Note: This is a batch operation equivalent to calling addInverse for each instance in the list, but with better performance for large collections.

bool addInverses(List<IInstance> inverses);

clearAttributeAggregateByPath()#

Clears all elements from an aggregate attribute by path.

path: The PIAttributePath specifying the aggregate to clear. The path should address the aggregate attribute itself, not an element within it.

Returns the IInstance on which the operation was performed.

IInstance clearAttributeAggregateByPath(PIAttributePath path);

clearComposites()#

Clears all composites from this instance.

Returns the number of composites that were removed. Returns 0 if the instance had no composites.

Note: This operation removes all composites from this instance.

int clearComposites([bool removeReferences = true]);

clearInverses()#

Clears all inverse references pointing to this instance.

This operation is typically used during instance deletion or schema transformation to clean up bidirectional relationships before removing an instance from the model.

exclusion: Optional list of instance IDs to exclude from clearing. Inverse references to these instances will be preserved.

Returns the number of inverse references that were successfully cleared. Returns 0 if no inverse references were present.

Warning: Clearing inverse references may break bidirectional relationships. Use with caution.

int clearInverses([List<int> exclusion = const []]);

clearReferences()#

Clears all references emanating from this instance.

Sets all instance reference attributes to null or removes them from collections. Use with caution: This operation also clears non-optional attributes, which may leave the instance in an invalid state according to schema rules.

includeInternal: If true, includes references to composite instances. If false, only clears references to external instances. Defaults to false. exclusion: A list of instance IDs to exclude from clearing. References pointing to these instances will be preserved.

Returns a list of InstanceHandle objects that were cleared during the operation, which can be useful for cleanup or auditing purposes.

Example:

 Clear all external references except instance #123
List<InstanceHandle> cleared = instance.clearReferences(false, [123]);

List<InstanceHandle> clearReferences(
    [bool includeInternal = false, List<int> exclusion = const []]);

createComplexInstance()#

Creates a complex instance for the specified attribute.

Complex instances comprise multiple partial instances that together form a complete entity definition according to EXPRESS schema rules.

Either attName or attIndex must be provided to identify the target attribute. parts: A list of part type names to include in the complex instance.

Returns a new complex IInstance configured for the specified attribute.

IInstance createComplexInstance(
    {String? attName, int? attIndex, List<String> parts = const []});

createEnum()#

Creates an enum for the specified attribute.

Either attName or attIndex must be provided to identify the target attribute. The enum will be configured with the appropriate allowed values based on the attribute's schema definition.

attName: The name of the target attribute. attIndex: The zero-based index of the target attribute. value: Optional initial enum value.

Returns a new PIEnum instance configured for the specified attribute. Returns null enum if error.

PIEnum createEnum({String? attName, int? attIndex, String value = ''});

createInstance()#

Creates an instance of the appropriate type for the specified attribute.

Either attName or attIndex must be provided to identify the target attribute. The created instance will be of the type required by the attribute's schema definition.

attName: The name of the target attribute. attIndex: The zero-based index of the target attribute. type: Optional concrete subtype name override. If empty, uses the attribute's defined type. Required when the attribute type is abstract.

Returns a new IInstance of the appropriate type for the specified attribute. Returns null instance if an error occurs (e.g., attribute type is abstract and no concrete type is specified).

IInstance createInstance({String? attName, int? attIndex, String type = ''});

createNullInstance()#

Creates a null instance.

Returns a special null instance that represents a missing or unset value. Null instances typically have type ID 0 and can be checked with isNull.

Returns a nullInstance.

IInstance createNullInstance();

createSelect()#

Creates a select for the specified attribute.

Either attName or attIndex must be provided to identify the target attribute. The select will be configured with the appropriate allowed types based on the attribute's schema definition.

attName: The name of the target attribute. attIndex: The zero-based index of the target attribute. selectedType: Optional initial selected type name.

Returns a new ISelect instance configured for the specified attribute. Returns nullSelect if error.

ISelect createSelect(
    {String? attName, int? attIndex, String selectedType = ''});

detach()#

For composed or composite instances, detach instance from dependent buffer. Call this if the owning buffer has changed.

Example: profile from IfcExtrudedAreaSolid

final profile = extrude.getInstance("SweptArea");
  profile.detach();
  extrude.setAttributesByJson({
  "ExtrudedDirection": {
    "@type": "IfcDirection",
    "DirectionRatios": [0.0, 0.0, 1.0]
  });

profile.detach() must be called because the function extrude.setAttributeByJson change extrude's buffer which instance profile depends on. profile.detach() create an independent profile instance. profile.getRunTimeType will return InstanceRunTimeType.free.

Returns true if the instance was successfully detached.

bool detach();

duplicate()#

Creates a duplicate of this instance.

Creates a deep copy of this instance, including all composed attributes and internal state. Reference attributes are copied as references (not deep copied).

resolveIndex: If true, resolves instance IDs during duplication to ensure uniqueness in the new hierarchy. If false, preserves original IDs.

Returns a new IInstance that is a duplicate of this instance.

IInstance duplicate([bool resolveIndex = false]);

getAttribute()#

Gets the value of an attribute with type safety.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute. attIndex: The zero-based index of the attribute. resolveRef: If true, resolves instance references to return actual instances. If false, returns reference handles as-is. detach: If true, the returned value (if an instance or select) will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the child objects to remain independent. See detach() for more details.

Returns an Option<T> containing the stored value if successful, or Option.none if the attribute doesn't exist or contains a null value.

Option<T> getAttribute<T>(
    {String? attName,
    int? attIndex,
    bool resolveRef = false,
    bool detach = false});

getAttributeByPath()#

Gets an attribute value by path, along with its fundamental type.

The return value includes the FundamentalType to assist in handling the returned dynamic value properly.

path: The PIAttributePath specifying the attribute location. resolveRef: If true, converts all instance references into full instances during traversal. Must be true if the path crosses instance boundaries (i.e., accesses non-composite instances via references). detach: If true, any instances or selects encountered during traversal will have their own independent memory buffers instead of sharing the parent instance's buffer. This is useful when you need to manipulate the retrieved values independently of the original instance hierarchy. See detach() for more details.

Returns a tuple (FundamentalType, dynamic) where:

• First element: The fundamental type of the retrieved value
• Second element: The attribute value itself

Note: When accessing attributes across instance boundaries, resolveRef must be true to ensure proper navigation through reference instances.

(FundamentalType, dynamic) getAttributeByPath(PIAttributePath path,
    {bool resolveRef = true, bool detach = false});

getAttributeByPathAsDynamic()#

Gets an attribute value by path as a dynamic value.

path: The PIAttributePath specifying the attribute location. resolveRef: If true, converts instance references to full instances during traversal. detach: If true, any instances or selects encountered during traversal will have their own independent memory buffers instead of sharing the parent instance's buffer. This is useful when you need to manipulate the retrieved values independently of the original instance hierarchy. See detach() for more details.

Returns the attribute value directly as dynamic. For type-safe access, use getAttributeByPath which returns the type information.

dynamic getAttributeByPathAsDynamic(PIAttributePath path,
    {bool resolveRef = true, bool detach = false});

getAttributeDescriptor()#

Gets the attribute descriptor for the specified attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to look up. attIndex: The zero-based index of the attribute to look up.

Returns an IAttributeDescriptor containing metadata about the specified attribute, or return nullAttribute if error.

IAttributeDescriptor getAttributeDescriptor({String? attName, int? attIndex});

getAttributeFundamentalType()#

Gets the fundamental type categorization of the specified attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to look up. attIndex: The zero-based index of the attribute to look up.

Returns a FundamentalType enumeration value representing the core data type categorization of the attribute (e.g., INTEGER, STRING, ENTITY). Returns FundamentalType.UNKNOWN if error.

FundamentalType getAttributeFundamentalType({String? attName, int? attIndex});

getAttributeIndex()#

Gets the attribute index from its name.

attName: The name of the attribute to find.

Returns the zero-based index of the attribute with the given name. Returns -1 if no attribute with the specified name exists.

int getAttributeIndex(String attName);

getAttributeType()#

Gets the type name of the specified attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to look up. attIndex: The zero-based index of the attribute to look up.

Returns the EXPRESS type name of the attribute as a string (e.g., "REAL", "LIST OF INTEGER", "IfcLabel"). Returns empty String if error.

String getAttributeType({String? attName, int? attIndex});

getAttributeTypeId()#

Gets the type identifier of the specified attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to look up. attIndex: The zero-based index of the attribute to look up.

Returns a hash-based integer identifier representing the attribute's type. This is useful for quick type comparisons and lookups. Return 0 if error.

int getAttributeTypeId({String? attName, int? attIndex});

getAttributeValueFundamentalType()#

Gets the fundamental type of the value addressed by path.

path: The PIAttributePath specifying the value location.

Returns the FundamentalType of the value at the specified path. Note: This returns the type of the value, which means if the last token is an integer index into an aggregate, it returns the element type rather than the aggregate type.

FundamentalType getAttributeValueFundamentalType(PIAttributePath path);

getBinary()#

Gets the value of a BINARY attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the BINARY attribute. attIndex: The zero-based index of the BINARY attribute.

Returns a Uint8List containing the binary data. Returns an empty Uint8List if the attribute doesn't exist, is not a BINARY type, or contains a null value.

Uint8List getBinary({String? attName, int? attIndex});

getBinarys()#

Gets the value of a binary aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the BINARYS attribute. attIndex: The zero-based index of the BINARYS attribute.

Returns a List<Uint8List> containing the binary data values. Returns an empty list if the attribute doesn't exist, is not a BINARYS type, or contains a null value.

List<Uint8List> getBinarys({String? attName, int? attIndex});

getBool()#

Gets the boolean value of a BOOLEAN attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the BOOLEAN attribute. attIndex: The zero-based index of the BOOLEAN attribute.

Returns an Option<bool> where:

• optionOf if the attribute exists and contains a boolean value
• Option.none if the attribute doesn't exist, is not a BOOLEAN type, or contains a null value

Option<bool> getBool({String? attName, int? attIndex});

getBools()#

Gets the value of a bool aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the BOOLS attribute. attIndex: The zero-based index of the BOOLS attribute.

Returns a List<bool> containing the boolean values. Returns an empty list if the attribute doesn't exist, is not a BOOLS type, or contains a null value.

List<bool> getBools({String? attName, int? attIndex});

getClearTextRepresentation()#

Gets the clear text representation of this instance.

String getClearTextRepresentation(ExportFormat type);

getComposite()#

Gets a composite element by its instance identifier.

instanceId: The unique instance identifier of the composite to retrieve. detach: If true, the returned composite instance will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when you need to modify the composite independently of the owning instance. See detach() for more details.

Returns the IInstance with the specified ID if found within this instance's composites. Returns a null instance if no composite with the given ID exists.

IInstance getComposite(int instanceId, {bool detach = false});

getComposites()#

Gets all composite instance elements directly owned by this instance.

detach: If true, each returned composite instance will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when you need to modify composites independently of the owning instance. See detach() for more details.

Returns a list of IInstance objects representing the composite instances stored in this instance's special composite buckets. Does not include nested composites from child instances.

List<IInstance> getComposites({bool detach = false});

getCompositesByType()#

Gets composite elements by type.

type: The EXPRESS type name to filter composites by. includeSubType: If true, includes composites that are subtypes of the specified type. If false, only returns exact type matches. detach: If true, each returned composite instance will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when you need to modify composites independently of the owning instance. See detach() for more details.

Returns a list of IInstance objects that match the specified type criteria. Returns an empty list if no matching composites are found.

List<IInstance> getCompositesByType(String type,
    {bool includeSubType = false, bool detach = false});

getDecomposition()#

Gets all composites and composed attribute instances of this instance in a flat list.

Composites are sharable composed instances stored in special buckets within an entity instance, enabling efficient reuse of common sub-structures.

includeAllReferences: If true, the returned list includes both composed instances and instance references. If false, only returns fully composed instances. detach: If true, each returned instance in the decomposition will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when you need to manipulate the decomposition independently of the original instance. See detach() for more details.

Returns a flat list of IInstance objects representing the complete decomposition hierarchy of this instance. This is used by PIComposer to export to part 21 clear text representation.

List<IInstance> getDecomposition(
    {bool includeAllReferences, bool detach = false});

getEnum()#

Gets the value of an ENUMERATION attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the ENUM attribute. attIndex: The zero-based index of the ENUM attribute.

Returns a PIEnum representing the enumeration value. Returns a null enum value if the attribute doesn't exist, is not an ENUM type, or contains a null value.

PIEnum getEnum({String? attName, int? attIndex});

getEnums()#

Gets the value of an enum aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the ENUMS attribute. attIndex: The zero-based index of the ENUMS attribute.

Returns a List<PIEnum> containing the enumeration values. Returns an empty list if the attribute doesn't exist, is not an ENUMS type, or contains a null value.

List<PIEnum> getEnums({String? attName, int? attIndex});

getFloat()#

Gets the value of a float attribute (PIComposer extension).

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the FLOAT attribute. attIndex: The zero-based index of the FLOAT attribute.

Returns an Option<double> where:

• optionOf if the attribute exists and contains a float value
• Option.none if the attribute doesn't exist, is not a FLOAT type, or contains a null value

Option<double> getFloat({String? attName, int? attIndex});

getFloats()#

Gets the value of a float aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the FLOATS attribute. attIndex: The zero-based index of the FLOATS attribute.

Returns a List<double> containing the float values. Returns an empty list if the attribute doesn't exist, is not a FLOATS type, or contains a null value.

List<double> getFloats({String? attName, int? attIndex});

getFloats2()#

Gets the value of a 2D float aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the FLOATS2 attribute. attIndex: The zero-based index of the FLOATS2 attribute.

Returns a List<List<double>> containing the 2D float values. Returns an empty list if the attribute doesn't exist, is not a FLOATS2 type, or contains a null value.

List<List<double>> getFloats2({String? attName, int? attIndex});

getInstance()#

Gets the value of an ENTITY attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the ENTITY attribute. attIndex: The zero-based index of the ENTITY attribute. resolveRef: If true, resolves instance references to return the actual instance. If false, returns the reference handle as-is. detach: If true, the returned instance will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified (e.g., by setAttributesByJson) and you need the child instance to remain independent. See detach() for more details.

Returns an IInstance representing the entity value. Returns a null instance if the attribute doesn't exist, is not an ENTITY type, or contains a null value.

IInstance getInstance(
    {String? attName,
    int? attIndex,
    bool resolveRef = false,
    bool detach = false});

getInstanceId()#

Gets the instance identifier.

Alternative accessor for the instance ID. Returns the same value as the instanceId property.

int getInstanceId();

getInstances()#

Gets the value of an instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the ENTITYS attribute. attIndex: The zero-based index of the ENTITYS attribute. resolveRef: If true, resolves instance references to return actual instances. If false, returns reference handles as-is. detach: If true, each returned instance in the list will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the child instances to remain independent. See detach() for more details.

Returns a List<IInstance> containing the entity values. Returns an empty list if the attribute doesn't exist, is not an ENTITYS type, or contains a null value.

List<IInstance> getInstances(
    {String? attName,
    int? attIndex,
    bool resolveRef = false,
    bool detach = false});

getInstances2()#

attName: The name of the ENTITYS2 attribute. attIndex: The zero-based index of the ENTITYS2 attribute. resolveRef: If true, resolves instance references to return actual instances. If false, returns reference handles as-is. detach: If true, each returned instance in the 2D list will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the child instances to remain independent. See detach() for more details.

Returns a List<List<IInstance>> containing the 2D entity values. Returns an empty list if the attribute doesn't exist, is not an ENTITYS2 type, or contains a null value.

List<List<IInstance>> getInstances2(
    {String? attName,
    int? attIndex,
    bool resolveRef = false,
    bool detach = false});

getInstances3()#

Gets the value of a 3D instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the ENTITYS3 attribute. attIndex: The zero-based index of the ENTITYS3 attribute. resolveRef: If true, resolves instance references to return actual instances. If false, returns reference handles as-is. detach: If true, each returned instance in the 3D list will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the child instances to remain independent. See detach() for more details.

Returns a List<List<List<IInstance>>> containing the 3D entity values. Returns an empty list if the attribute doesn't exist, is not an ENTITYS3 type, or contains a null value.

List<List<List<IInstance>>> getInstances3(
    {String? attName,
    int? attIndex,
    bool resolveRef = false,
    bool detach = false});

getInt()#

Gets the integer value of an INTEGER attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the INTEGER attribute. attIndex: The zero-based index of the INTEGER attribute.

Returns an Option<int> where:

• optionOf if the attribute exists and contains an integer value
• Option.none if the attribute doesn't exist, is not an INTEGER type, or contains a null value

Option<int> getInt({String? attName, int? attIndex});

getInt64()#

Gets the value of a 64-bit integer attribute (PIComposer extension).

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the INT64 attribute. attIndex: The zero-based index of the INT64 attribute.

Returns an Option<int> where:

• optionOf if the attribute exists and contains a valid value
• Option.none if the attribute doesn't exist, is not an INT64 type, or contains a null value

Option<int> getInt64({String? attName, int? attIndex});

getInt64s()#

Gets the value of a 64-bit integer aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the INT64S attribute. attIndex: The zero-based index of the INT64S attribute.

Returns a List<int> containing the 64-bit integer values. Returns an empty list if the attribute doesn't exist, is not an INT64S type, or contains a null value.

List<int> getInt64s({String? attName, int? attIndex});

getInts()#

Gets the value of an integer aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the INTEGERS attribute. attIndex: The zero-based index of the INTEGERS attribute.

Returns a List<int> containing the integer values. Returns an empty list if the attribute doesn't exist, is not an INTEGERS type, or contains a null value.

List<int> getInts({String? attName, int? attIndex});

getInts2()#

Gets the value of a 2D integer aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the INTEGERS2 attribute. attIndex: The zero-based index of the INTEGERS2 attribute.

Returns a List<List<int>> containing the 2D integer values. Returns an empty list if the attribute doesn't exist, is not an INTEGERS2 type, or contains a null value.

List<List<int>> getInts2({String? attName, int? attIndex});

getInverse()#

Gets a specific inverse reference by instance identifier.

This method is essential for targeted life cycle management operations, allowing precise access to specific inverse relationships when managing complex object graphs or performing selective cleanup operations.

instanceId: The unique instance identifier of the inverse reference to retrieve.

Returns the InstanceHandle representing the inverse reference if found. Returns a null handle if no inverse reference with the given ID exists.

InstanceHandle getInverse(int instanceId);

getInverses()#

Gets all inverse references of this instance.

Inverse references represent relationships where other instances have instance references to this instance, providing bidirectional navigation and instance life cycle management—especially when cascade delete is required.

Returns a list of InstanceHandle objects representing all instances that maintain inverse references to this instance. Returns an empty list if no inverse references exist.

List<InstanceHandle> getInverses();

getInversesOfType()#

Gets inverse references of a specific type pointing to this instance.

Inverse references enable tracking of which instances reference this instance, crucial for life cycle management and maintaining data integrity during operations like cascade delete or schema validation.

Either type or typeId must be provided to filter the inverse references.

type: The EXPRESS type name to filter inverse references by. typeId: The type identifier to filter inverse references by. includeSubType: If true, includes inverse references from instances that are subtypes of the specified type. If false, only returns exact type matches.

Returns a list of InstanceHandle objects representing inverse references that match the specified type criteria. Returns an empty list if no matching inverse references are found.

List<InstanceHandle> getInversesOfType(
    {String? type, int? typeId, bool includeSubType = false});

getLogical()#

Gets the value of a LOGICAL attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the LOGICAL attribute. attIndex: The zero-based index of the LOGICAL attribute.

Returns a PIEnum representing the logical value (True, False, Unknown). Returns a null enum value if the attribute doesn't exist, is not a LOGICAL type, or contains a null value.

PIEnum getLogical({String? attName, int? attIndex});

getLogicals()#

Gets the value of a logical aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the LOGICALS attribute. attIndex: The zero-based index of the LOGICALS attribute.

Returns a List<PIEnum> containing the logical values. Returns an empty list if the attribute doesn't exist, is not a LOGICALS type, or contains a null value.

List<PIEnum> getLogicals({String? attName, int? attIndex});

getReal()#

Gets the value of a REAL attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the REAL attribute. attIndex: The zero-based index of the REAL attribute.

Returns an Option<double> where:

• optionOf if the attribute exists and contains a real number value
• Option.none if the attribute doesn't exist, is not a REAL type, or contains a null value

Option<double> getReal({String? attName, int? attIndex});

getReals()#

Gets the value of a real aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the REALS attribute. attIndex: The zero-based index of the REALS attribute.

Returns a List<double> containing the real number values. Returns an empty list if the attribute doesn't exist, is not a REALS type, or contains a null value.

List<double> getReals({String? attName, int? attIndex});

getReals2()#

Gets the value of a 2D real aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the REALS2 attribute. attIndex: The zero-based index of the REALS2 attribute.

Returns a List<List<double>> containing the 2D real number values. Returns an empty list if the attribute doesn't exist, is not a REALS2 type, or contains a null value.

List<List<double>> getReals2({String? attName, int? attIndex});

getReals3()#

Gets the value of a 3D real aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the REALS3 attribute. attIndex: The zero-based index of the REALS3 attribute.

Returns a List<List<List<double>>> containing the 3D real number values. Returns an empty list if the attribute doesn't exist, is not a REALS3 type, or contains a null value.

List<List<List<double>>> getReals3({String? attName, int? attIndex});

getReferences()#

Gets all references emanating from this instance.

References are non-composed attributes that contain instance references (object-based handles to other instances rather than fully composed objects).

includeInternal: If true, includes references to composite instances (shared instances stored in special composite buckets). If false, only returns references to external instances. Defaults to false.

Returns a list of InstanceHandle objects representing all instance references originating from this instance's attributes.

Example:

 Get all external references
List<InstanceHandle> externalRefs = instance.getReferences();

 Get all references including internal composites
List<InstanceHandle> allRefs = instance.getReferences(true);

List<InstanceHandle> getReferences([bool includeInternal = false]);

getSelect()#

Gets the value of a SELECT attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the SELECT attribute. attIndex: The zero-based index of the SELECT attribute. detach: If true, the returned select will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the select to remain independent. See detach() for more details.

Returns an ISelect representing the select value. Returns a null select if the attribute doesn't exist, is not a SELECT type, or contains a null value.

ISelect getSelect({String? attName, int? attIndex, bool detach = false});

getSelects()#

Gets the value of a select aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the SELECTS attribute. attIndex: The zero-based index of the SELECTS attribute. detach: If true, each returned select in the list will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the selects to remain independent. See detach() for more details.

Returns a List<ISelect> containing the select values. Returns an empty list if the attribute doesn't exist, is not a SELECTS type, or contains a null value.

List<ISelect> getSelects(
    {String? attName, int? attIndex, bool detach = false});

getSelects2()#

Gets the value of a 2D select aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the SELECTS2 attribute. attIndex: The zero-based index of the SELECTS2 attribute. detach: If true, each returned select in the 2D list will have its own independent memory buffer instead of sharing the parent instance's buffer. This is useful when the parent buffer may be modified and you need the selects to remain independent. See detach() for more details.

Returns a List<List<ISelect>> containing the 2D select values. Returns an empty list if the attribute doesn't exist, is not a SELECTS2 type, or contains a null value.

List<List<ISelect>> getSelects2(
    {String? attName, int? attIndex, bool detach = false});

getString()#

Gets the value of a STRING attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the STRING attribute. attIndex: The zero-based index of the STRING attribute.

Returns an Option<String> where:

• optionOf if the attribute exists and contains a string value
• Option.none if the attribute doesn't exist, is not a STRING type, or contains a null value

Option<String> getString({String? attName, int? attIndex});

getStrings()#

Gets the value of a string aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the STRINGS attribute. attIndex: The zero-based index of the STRINGS attribute.

Returns a List<String> containing the string values. Returns an empty list if the attribute doesn't exist, is not a STRINGS type, or contains a null value.

List<String> getStrings({String? attName, int? attIndex});

getStrings2()#

Gets the value of a 2D string aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the STRINGS2 attribute. attIndex: The zero-based index of the STRINGS2 attribute.

Returns a List<List<String>> containing the 2D string values. Returns an empty list if the attribute doesn't exist, is not a STRINGS2 type, or contains a null value.

List<List<String>> getStrings2({String? attName, int? attIndex});

getUInt()#

Gets the value of a 32-bit unsigned integer attribute (PIComposer extension).

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the UINTEGER attribute. attIndex: The zero-based index of the UINTEGER attribute.

Returns an Option<int> where:

• optionOf if the attribute exists and contains a valid value
• Option.none if the attribute doesn't exist, is not a UINTEGER type, or contains a null value

Option<int> getUInt({String? attName, int? attIndex});

getUInts()#

Gets the value of an unsigned integer aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the UINTEGERS attribute. attIndex: The zero-based index of the UINTEGERS attribute.

Returns a List<int> containing the unsigned integer values. Returns an empty list if the attribute doesn't exist, is not a UINTEGERS type, or contains a null value.

List<int> getUInts({String? attName, int? attIndex});

getUInts2()#

Gets the value of a 2D unsigned integer aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the UINTEGERS2 attribute. attIndex: The zero-based index of the UINTEGERS2 attribute.

Returns a List<List<int>> containing the 2D unsigned integer values. Returns an empty list if the attribute doesn't exist, is not a UINTEGERS2 type, or contains a null value.

List<List<int>> getUInts2({String? attName, int? attIndex});

incrementVersionId()#

Programmatically increments the version identifier.

Returns the new version ID after incrementing. This can be used to force a version change without persisting the instance.

int incrementVersionId();

isNullAttribute()#

Checks if the specified attribute contains a null value.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to check. attIndex: The zero-based index of the attribute to check.

Returns an Option<bool> where:

• optionOf(true) if the attribute exists and contains a null value
• optionOf(false) if the attribute exists and contains a non-null value
• Option.none if the attribute does not exist or the identifier is invalid

Example:

Check if 'optionalField' is null
final result = instance.isNullAttribute(attName: 'optionalField');
if (result.isSome() && result.getOrElse(() => false)) {
  print('Attribute is null');
}

Option<bool> isNullAttribute({String? attName, int? attIndex});

isSubTypeOf()#

Checks if this instance's type is a subtype of the specified type.

This method evaluates the EXPRESS schema inheritance hierarchy to determine if the current instance's type is a direct or indirect subtype (child) of the specified type.

otherTypeId: The hash-based type identifier to check against.

Returns true if this instance's type is a subtype of otherTypeId, false otherwise. This includes both direct and inherited subtype relationships.

Example:

 If this instance is IfcBeam (subtype of IfcElement)
bool isSub = instance.isSubTypeOf(ifcElementTypeId); // Returns true

bool isSubTypeOf(int otherTypeId);

isSuperTypeOf()#

Checks if this instance's type is a supertype of the specified type.

This method evaluates the EXPRESS schema inheritance hierarchy to determine if the current instance's type is a direct or indirect supertype (parent) of the specified type.

otherTypeId: The hash-based type identifier to check against.

Returns true if this instance's type is a supertype of otherTypeId, false otherwise. This includes both direct and inherited supertype relationships.

Example:

 If this instance is IfcElement (supertype of IfcBeam)
bool isSuper = instance.isSuperTypeOf(ifcBeamTypeId); // Returns true

bool isSuperTypeOf(int otherTypeId);

noSuchMethod() inherited#

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

nullifyAttribute()#

Sets the optional specified attribute to a null value.

Either attName or attIndex must be provided to identify the attribute.

attName: The name of the attribute to set to null. attIndex: The zero-based index of the attribute to set to null.

Returns an Option<bool> where:

• optionOf(true) if the attribute was successfully set to null
• optionOf(false) if the operation failed (e.g., attribute is non-optional)
• Option.none if the attribute does not exist or the identifier is invalid

Example:

Set 'optionalField' to null
final result = instance.nullifyAttribute(attName: 'optionalField');
if (result.isSome()) {
  print('Successfully nullified attribute');
}

Option<bool> nullifyAttribute({String? attName, int? attIndex});

nullifyAttributeByPath()#

Sets an optional attribute to null by path.

path: The PIAttributePath specifying the attribute to nullify.

Returns the IInstance on which the operation was performed.

Note: Only works for optional attributes. Required attributes cannot be nullified.

IInstance nullifyAttributeByPath(PIAttributePath path);

removeAttribute()#

Removes a attribute value from an aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

index: The zero-based index of the value to remove from the aggregate. attName: The name of the attribute. attIndex: The zero-based index of the attribute.

Returns true if the value was successfully removed. Returns false if the attribute doesn't exist, is not a aggregate type, or the index is out of bounds.

bool removeAttribute(int index, {String? attName, int? attIndex});

removeAttribute2()#

Removes a value from a 2D instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

row: The zero-based row index of the value to remove. col: The zero-based column index of the value to remove. attName: The name of the 2d aggregate attribute. attIndex: The zero-based index of the 2d aggregate attribute.

Returns true if the value was successfully removed. Returns false if the attribute doesn't exist, is not an 2d aggregate type, or either index is out of bounds.

bool removeAttribute2(int row, int col, {String? attName, int? attIndex});

removeAttribute3()#

Removes a value from a 3D instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

row: The zero-based row index of the value to remove. col: The zero-based column index of the value to remove. layer: The zero-based layer index of the value to remove. attName: The name of the 3d aggregate attribute. attIndex: The zero-based index of the 2d aggregate attribute.

Returns true if the value was successfully removed. Returns false if the attribute doesn't exist, is not an 3d aggregate type, or either index is out of bounds.

bool removeAttribute3(int row, int col, int layer,
    {String? attName, int? attIndex});

removeAttributeFromAggregateByPath()#

Removes a single element from an aggregate attribute by path.

path: The PIAttributePath specifying the element to remove. The last token must be an integer index into an aggregate.

Returns the IInstance on which the operation was performed.

IInstance removeAttributeFromAggregateByPath(PIAttributePath path);

removeComposite()#

Removes a composite by its instance identifier.

instanceId: The unique instance identifier of the composite to remove.

Note: Removing a composite may affect other instances that reference it.

void removeComposite(int instanceId, [bool removeReferences = true]);

removeCompositeOfType()#

Removes composites by type criteria.

type: Optional EXPRESS type name to filter composites for removal. typeId: Optional type identifier to filter composites for removal. includeSubType: If true, includes composites that are subtypes of the specified type in the removal operation.

Returns the number of composites that were successfully removed. Returns 0 if no matching composites were found.

Note: At least one of type or typeId must be provided.

int removeCompositeOfType(
    {String? type,
    int? typeId,
    bool includeSubType = false,
    bool removeReferences = true});

removeInverse()#

Removes a specific inverse reference by instance identifier.

This method is used to selectively clean up bidirectional relationships during partial model updates or when breaking specific references while maintaining other inverse relationships.

instanceId: The unique instance identifier of the inverse reference to remove.

void removeInverse(int instanceId);

removeInverseOfType()#

Removes inverse references by type criteria.

This operation is particularly useful for schema migration or selective cleanup where entire categories of relationships need to be removed while preserving other types of references for continued life cycle management.

Either type or typeId must be provided to filter the inverse references.

type: The EXPRESS type name to filter inverse references for removal. typeId: The type identifier to filter inverse references for removal. includeSubType: If true, includes inverse references from instances that are subtypes of the specified type in the removal operation.

Returns the number of inverse references that were successfully removed. Returns 0 if no matching inverse references were found.

int removeInverseOfType(
    {String? type, int? typeId, bool includeSubType = false});

removeReference()#

remove a reference to an instance identified by instanceId emanating from this instance.

bool removeReference(int instanceId);

setAttribute()#

Sets the value of an instance attribute.

Either attName or attIndex must be provided to identify the attribute.

value: The binary data to set. attName: The name of the BINARY attribute. attIndex: The zero-based index of the BINARY attribute.

Returns true if the value was successfully set. Returns false if the attribute doesn't exist, or value is not the right type for the attribute

bool setAttribute<T>(T value, {String? attName, int? attIndex});

setAttributeByPath()#

Sets an attribute value using a path specification.

This method allows precise modification of nested attributes within complex instance hierarchies by specifying a path to the target attribute. The path can traverse through multiple levels of object composition, aggregate elements, select type selections and across instance boundaries.

The path follows the same structure as IInstance.setAttributeByPath, allowing you to navigate through:

• Instance attributes (by name)
• Select type selections (using the selected type name)
• Aggregate elements (using integer indices for LIST, SET, ARRAY)

Together with getAttributeByPath and getAttributeContainer, this method provides a powerful way to manipulate complex instance structures without needing to manually traverse and extract intermediate objects.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute. The path consists of a starting instance handle and a list of path components (strings for attributes, integers for aggregates).
• value: The value to set. The type must be compatible with the target attribute's fundamental type. For instance attributes, this can be an IInstance, ISelect, or primitive value. For aggregate elements, it must match the aggregate's element type.

Returns the modified instance that owns the attribute. The return instance isNull if:

• The path is invalid or cannot be resolved
• The target attribute does not exist
• The value type is incompatible with the target attribute
• The path traverses through null or invalid intermediate instance

Example usage:

// Set a nested attribute in a complex hierarchy
final attPath = ['RelativePlacement', 'IfcAxis2Placement2D', 'RefDirection'];
final handle = getInstancesByType(toTypeId('IfcLocalPlacement')).first;
final path = InstancePath(handle, attPath);

final refDir = instanceFromJson({
  '@type': 'IfcDirection',
  'DirectionRatios': [1.0, 0.0]
});

final inst = setAttributeByPath(path, refDir);
if (inst.isNull) {
  print('Reference direction set successfully');
} else {
  print('Failed to set reference direction');
}
model.saveInstance(inst);

IInstance setAttributeByPath(PIAttributePath path, dynamic value);

setAttributeByPathWithJson()#

Sets an attribute value using both path specification and JSON data.

This method combines the functionality of setAttributeByPath and JSON-based instance creation to provide a powerful way to set complex nested attributes using a declarative JSON structure. It navigates to the target attribute using the specified path and sets its value using the provided json data.

The method handles the complete process:

1. Navigates through the instance hierarchy using the provided path
2. Creates appropriate values from the JSON data (including nested instances)
3. Sets the target attribute to the created value(s)

This is particularly useful for setting complex attributes that require creating nested object hierarchies or select type values.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute where the JSON value should be set.
• json: A JSON-like map representing the value to set. The structure follows the same conventions as instanceFromJson, including support for: - '@type' key for entity instances
  • Nested objects for complex attributes
  • Arrays for aggregate values
  • Select type specifications

Returns true if the attribute was successfully set using the JSON data, or false if:

• The path is invalid or cannot be resolved
• The JSON structure is malformed or incompatible with the target attribute
• The target attribute cannot accept the created value type
• Any intermediate object in the path is null or invalid

Example usage:

// Set a complex placement attribute using JSON
final placementPath = InstancePath(wallHandle, ['ObjectPlacement', 'RelativePlacement',
   'IfcAxis2Placement3D', 'Location']);
final success = setAttributeByPathWithJson(placementPath, {
      '@type': 'IfcCartesianPoint',
      'Coordinates': [10.0, 5.0, 3.0]
});

if (success) {
  print('Complex placement hierarchy created and set successfully');
} else {
  print('Failed to set placement from JSON');
}

See also:

• setAttributeByPath: Sets attribute using direct value assignment
• instanceFromJson: Creates complete instances from JSON data
• getAttributeByPath: Retrieves values using path specification

IInstance setAttributeByPathWithJson(PIAttributePath path, dynamic json);

setAttributesByJson()#

Sets attributes using JSON in a declarative batch operation.

This method provides a powerful way to set multiple attributes, including complex nested structures, through a single JSON object. It can be used for both initial population and updates of instance data.

The JSON object can recursively define composed instances and selects, allowing for complete hierarchical data construction.

Example: Setting an IfcLocalPlacement

setAttributesByJson({
  "PlacementRelTo": {
    "@reference": true,
    "instanceId": 123,
    "typeId": LocalPlacementId // or toTypeId("IfcLocalPlacement")
  },
  "RelativePlacement": {
    "IfcAxis2Placement3D": {
      "Location": {
        "type": "IfcCartesianPoint",
        "Coordinates": [1.0, 0.0, 0.0]
      },
      "Axis": {
        "DirectionRatios": [0.0, 0.0, 1.0]
      },
      "RefDirection": {
        "DirectionRatios": [1.0, 0.0, 0.0]
      }
    }
  }
});

Special JSON Keys:

PIComposer uses special keys to control instance construction:

1. "type" (kInstanceTypeKey): Specifies the EXPRESS type name for creating new instances
2. "@reference" (kReferenceKey): Indicates that an instance reference should be created
3. "instanceId" (kInstanceIdKey): Specifies the target instance ID for references

How It Works:

• PlacementRelTo: An ENTITY attribute set to an instance reference
• RelativePlacement: A SELECT attribute containing an IfcAxis2Placement3D instance
• Nested types: Type specification can be omitted for final types (no subtypes) like IfcDirection for Axis and RefDirection attributes

json: A JSON object defining the attribute structure and values Returns true if all attributes were successfully set, false if any part of the JSON structure was invalid or incompatible with the schema.

bool setAttributesByJson(Map<String, dynamic> json);

setCompositeItem()#

Sets or replaces a specific composite item.

inst: The composite instance to set or add. If a composite with the same instance ID already exists, it is replaced. Otherwise, the composite is appended to the collection.

Returns true if the composite was successfully set or added. Returns false if error.

bool setCompositeItem(IInstance inst);

setCompositeItemDynamic()#

complement to setCompositeItem

bool setCompositeItemDynamic(dynamic inst);

setComposites()#

Replaces all composites in this instance with the provided list.

composites: The complete list of composite instances to set. Replaces any existing composites entirely.

Note: This operation completely replaces the current composite collection. Use with caution as it may affect other instances referencing these composites.

bool setComposites(List<IInstance> composites);

setCompositesDynamic()#

complement to setComposites. Use in Blockly scripting engine

bool setCompositesDynamic(dynamic composites);

setDirty()#

Sets the dirty flag for this instance.

dirty: true to mark the instance as modified, false to mark as clean.

void setDirty(bool dirty);

setGuid() extension#

Sets a string attribute to a newly generated GUID value.

Either attName or attIndex must be provided to identify the target attribute.

attName: The name of the attribute to set. attIndex: The index of the attribute to set.

Returns true if the attribute was successfully set with a new GUID, false if the attribute could not be found or accessed.

Available on IInstance, provided by the IInstanceExtension extension

bool setGuid({String? attName, int? attIndex}) {
  final index = attIndex ?? getAttributeIndex(attName ?? '');
  if (index < 0) {
    return false;
  }
  setAttribute(attIndex: index, PIComposerAPIFFI.getGuid());
  return true;
}

setInstanceRef()#

Sets the value of an ENTITY attribute as an instance reference.

Either attName or attIndex must be provided to identify the attribute.

inst: The entity instance to create a reference to. attName: The name of the ENTITY attribute. attIndex: The zero-based index of the ENTITY attribute. addInverse: If true, automatically adds an inverse reference from the target instance back to this instance.

Returns true if the reference was successfully created and set. Returns false if the attribute doesn't exist, is not an ENTITY type.

bool setInstanceRef(IInstance inst,
    {String? attName, int? attIndex, bool addInverse = true});

toJson()#

Converts the instance to a JSON-compatible map representation.

This method serializes all attributes of the instance into a Map where keys are attribute names and values are JSON-compatible Dart objects. Nested instances and selects are recursively converted to their JSON form.

setDefaultForOption: If true (default), optional attributes that are null will return their default values (e.g., false for boolean, 0 for integer, 0.0 for real, '' for string). If false, null optional attributes will return null.

Returns a Map containing all instance attributes as key-value pairs.

Example

final wall = model.createInstance('IfcWall');
wall.setString(attName: 'Name', 'Main Wall');

final json = wall.toJson();
// Output: {
"@type": "ifcwall", "Name": "Main Wall"}

Map<String, dynamic> toJson({bool setDefaultForOption = true});

toString() inherited#

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

external String toString();

updateAttribute()#

Updates a attribute value in an aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

index: The zero-based index of the value to update in the aggregate. value: The new value to set at the specified index. attName: The name of the Aggregate attribute. attIndex: The zero-based index of the attribute.

Returns true if the value was successfully updated. Returns false if the attribute doesn't exist, or is not a aggregate type,

bool updateAttribute<T>(int index, T value, {String? attName, int? attIndex});

updateAttribute2()#

Updates a value in a 2D instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

row: The zero-based row index of the value to update. col: The zero-based column index of the value to update. value: The new value to set at the specified position. attName: The name of the aggregate attribute. attIndex: The zero-based index of the aggregate attribute.

Returns true if the value was successfully updated. Returns false if the attribute doesn't exist, is not an aggregate type, or index is out of bounds.

bool updateAttribute2<T>(int row, int col, T value,
    {String? attName, int? attIndex});

updateAttribute3()#

Updates a value in a 3D instance aggregate attribute.

Either attName or attIndex must be provided to identify the attribute.

row: The zero-based row index of the value to update. col: The zero-based column index of the value to update. layer: The zero-based layer index of the value to update. value: The new entity instance to set at the specified position. attName: The name of the aggregate attribute. attIndex: The zero-based index of the aggregate attribute.

Returns true if the value was successfully updated. Returns false if the attribute doesn't exist, is not an aggregate type, or any index (row, col, layer) is out of bounds.

bool updateAttribute3<T>(int row, int col, int layer, T value,
    {String? attName, int? attIndex});

validateInverses()#

Gets validate inverse references of this instance. Dangling inverses are removed from the instance and not returned.

Returns a list of InstanceHandle valid inverse.

List<InstanceHandle> validateInverses();

validateReferences()#

Gets validate references emanating from this instance. Dangling references are removed from the instance and are not returned.

To compare before and after call getReferences with includeInternal = true.

Returns a list of InstanceHandle valid objects representing all instance references originating from this instance's attributes.

List<InstanceHandle> validateReferences();

Operators#

operator ==() inherited#

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

external bool operator ==(Object other);