From 60ae4e80ceb8bfe470bc9155f49c016b215941e1 Mon Sep 17 00:00:00 2001
From: Dion Moult <dion@thinkmoult.com>
Date: Wed, 5 Jun 2024 13:04:50 +1000
Subject: [PATCH] New get_contained util.element function

---
 .../ifcopenshell/util/element.py              | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/ifcopenshell-python/ifcopenshell/util/element.py b/src/ifcopenshell-python/ifcopenshell/util/element.py
index 33f5643efe..e6c1cf750e 100644
--- a/src/ifcopenshell-python/ifcopenshell/util/element.py
+++ b/src/ifcopenshell-python/ifcopenshell/util/element.py
@@ -1172,6 +1172,27 @@ def get_parts(element: ifcopenshell.entity_instance) -> list[ifcopenshell.entity
     return []
 
 
+def get_contained(element: ifcopenshell.entity_instance) -> list[ifcopenshell.entity_instance]:
+    """
+    Retrieves the contained elements of spatial element.
+
+    :param element: The IFC element
+    :type element: ifcopenshell.entity_instance
+    :return: The parts of the element
+    :rtype: list[ifcopenshell.entity_instance]
+
+    Example:
+
+    .. code:: python
+
+        element = file.by_type("IfcBuildingStorey")[0]
+        elements = ifcopenshell.util.element.get_contained(element)
+    """
+    if (rel := getattr(element, "ContainsElements", None)) is not None and rel:
+        return rel[0].RelatedElements
+    return []
+
+
 def get_components(element: ifcopenshell.entity_instance, include_ports=False) -> list[ifcopenshell.entity_instance]:
     """
     Retrieves the components of an element that have an nest relationship.