ifc_schedule/event/definition.rs
1//! `IfcEvent` and `IfcEventTime`.
2//!
3//! # Read by name in the declared release (#234)
4//!
5//! The readers bind the model's declared release like the task readers
6//! (#212) and find every attribute by name in its table. IFC4 ADD2 TC1 and
7//! IFC4X3 ADD2 declare both entities alike; IFC2X3 TC1 declares neither,
8//! so an IFC2X3 model has no events. IFC4X1, IFC4X2 and a header with
9//! several schemas are refused.
10//!
11//! # Slots, verified against IFC4 EXPRESS
12//!
13//! The slot modules below are the IFC4/IFC4X3 positions the modelless
14//! writers lay records out with; the readers never go through them.
15//!
16//! `IfcEvent` is an `IfcProcess`, sharing the first seven slots with `IfcTask`:
17//!
18//! ```text
19//! 0 GlobalId 1 OwnerHistory 2 Name
20//! 3 Description 4 ObjectType 5 Identification (IfcProcess)
21//! 6 LongDescription 7 PredefinedType
22//! 8 EventTriggerType 9 UserDefinedEventTriggerType 10 EventOccurenceTime
23//!
24//! IfcEventTime (IfcSchedulingTime)
25//! 0 Name 1 DataOrigin 2 UserDefinedDataOrigin
26//! 3 ActualDate 4 EarlyDate 5 LateDate 6 ScheduleDate
27//! ```
28//!
29//! Note the schema's own spelling: `EventOccurenceTime`, with one `r`. It is
30//! reproduced here because that is the attribute's name in the standard.
31//!
32//! `IfcEventTypeEnum` has no `MILESTONE` member; its tokens are `STARTEVENT`,
33//! `ENDEVENT` and `INTERMEDIATEEVENT` (plus `USERDEFINED`/`NOTDEFINED`). A
34//! milestone is an `IfcTask` with `IsMilestone` set.
35//!
36//! # An event is an instant
37//!
38//! Unlike a task, an event has no duration -- `IfcEventTime` states dates
39//! only. This is why events are a separate projection rather than tasks with
40//! a flag.
41
42use ifc_model::{Entity, EntityId, Model};
43
44use crate::error::ScheduleReadError;
45use crate::release::ReadRelease;
46use crate::SchemaVersion;
47
48const EVENT: &str = "IFCEVENT";
49const EVENT_TIME: &str = "IFCEVENTTIME";
50
51/// `IfcEvent` slots.
52pub mod slot {
53 /// `GlobalId` (from `IfcRoot`).
54 pub const GLOBAL_ID: usize = 0;
55 /// `Name` (from `IfcRoot`).
56 pub const NAME: usize = 2;
57 /// `ObjectType` (from `IfcObject`). Required by the schema when
58 /// `PredefinedType` is `USERDEFINED`.
59 pub const OBJECT_TYPE: usize = 4;
60 /// `Identification` (from `IfcProcess`).
61 pub const IDENTIFICATION: usize = 5;
62 /// `LongDescription` (from `IfcProcess`).
63 pub const LONG_DESCRIPTION: usize = 6;
64 /// `PredefinedType`.
65 pub const PREDEFINED_TYPE: usize = 7;
66 /// `EventTriggerType`.
67 pub const EVENT_TRIGGER_TYPE: usize = 8;
68 /// `UserDefinedEventTriggerType`. Required by the schema when
69 /// `EventTriggerType` is `USERDEFINED`.
70 pub const USER_DEFINED_EVENT_TRIGGER_TYPE: usize = 9;
71 /// `EventOccurenceTime`, spelled as the schema spells it.
72 pub const EVENT_OCCURENCE_TIME: usize = 10;
73}
74
75/// `IfcEventTime` slots.
76pub mod time_slot {
77 /// `Name` (from `IfcSchedulingTime`).
78 pub const NAME: usize = 0;
79 /// `ActualDate`.
80 pub const ACTUAL_DATE: usize = 3;
81 /// `EarlyDate`.
82 pub const EARLY_DATE: usize = 4;
83 /// `LateDate`.
84 pub const LATE_DATE: usize = 5;
85 /// `ScheduleDate`.
86 pub const SCHEDULE_DATE: usize = 6;
87}
88
89/// When an event's dates are stated.
90#[derive(Debug, Clone, PartialEq, Eq)]
91#[non_exhaustive]
92pub struct EventTime {
93 /// The `IfcEventTime` entity.
94 pub id: EntityId,
95 /// `Name` (from `IfcSchedulingTime`), as authored (#234).
96 pub name: Option<String>,
97 /// `DataOrigin` (`IfcDataOriginEnum`), the token without its dots
98 /// (#234).
99 pub data_origin: Option<String>,
100 /// `UserDefinedDataOrigin`, as authored (#234).
101 pub user_defined_data_origin: Option<String>,
102 /// The actual date, as authored.
103 pub actual: Option<String>,
104 /// The earliest date, as authored.
105 pub early: Option<String>,
106 /// The latest date, as authored.
107 pub late: Option<String>,
108 /// The scheduled date, as authored.
109 pub scheduled: Option<String>,
110}
111
112/// A borrowed view of an `IfcEvent`, read against one release.
113#[derive(Debug, Clone, Copy)]
114pub struct Event<'m> {
115 id: EntityId,
116 entity: &'m Entity,
117 release: ReadRelease,
118}
119
120impl<'m> Event<'m> {
121 /// The entity id in the file.
122 #[must_use]
123 pub fn id(&self) -> EntityId {
124 self.id
125 }
126
127 /// The release this event is read against.
128 #[must_use]
129 pub fn release(&self) -> SchemaVersion {
130 self.release.version()
131 }
132
133 fn text(&self, attribute: &'static str) -> Option<&'m str> {
134 self.release.text(EVENT, self.entity, attribute)
135 }
136
137 /// The `GlobalId` string.
138 #[must_use]
139 pub fn global_id(&self) -> Option<&'m str> {
140 self.text("GlobalId")
141 }
142
143 /// The event name.
144 #[must_use]
145 pub fn name(&self) -> Option<&'m str> {
146 self.text("Name")
147 }
148
149 /// The object type, which the schema requires when `PredefinedType` is
150 /// `USERDEFINED`.
151 #[must_use]
152 pub fn object_type(&self) -> Option<&'m str> {
153 self.text("ObjectType")
154 }
155
156 /// The user-facing identification code.
157 #[must_use]
158 pub fn identification(&self) -> Option<&'m str> {
159 self.text("Identification")
160 }
161
162 /// The long description.
163 #[must_use]
164 pub fn long_description(&self) -> Option<&'m str> {
165 self.text("LongDescription")
166 }
167
168 /// The predefined type token, without its dots.
169 #[must_use]
170 pub fn predefined_type(&self) -> Option<&'m str> {
171 self.release.token(EVENT, self.entity, "PredefinedType")
172 }
173
174 /// What triggers the event, as an enum token.
175 #[must_use]
176 pub fn trigger_type(&self) -> Option<&'m str> {
177 self.release.token(EVENT, self.entity, "EventTriggerType")
178 }
179
180 /// `UserDefinedEventTriggerType`, which the schema requires when
181 /// `EventTriggerType` is `USERDEFINED` (#234).
182 #[must_use]
183 pub fn user_defined_trigger_type(&self) -> Option<&'m str> {
184 self.text("UserDefinedEventTriggerType")
185 }
186
187 /// The event's stated times, if any: `EventOccurenceTime`, when it
188 /// references an `IfcEventTime`.
189 #[must_use]
190 pub fn time(&self, model: &Model) -> Option<EventTime> {
191 let id = self
192 .release
193 .reference(EVENT, self.entity, "EventOccurenceTime")?;
194 let entity = model.get(id)?;
195 if !self.release.is_a(&entity.type_name, EVENT_TIME) {
196 return None;
197 }
198 let text = |attribute| {
199 self.release
200 .text(EVENT_TIME, entity, attribute)
201 .map(str::to_string)
202 };
203 Some(EventTime {
204 id,
205 name: text("Name"),
206 data_origin: self
207 .release
208 .token(EVENT_TIME, entity, "DataOrigin")
209 .map(str::to_string),
210 user_defined_data_origin: text("UserDefinedDataOrigin"),
211 actual: text("ActualDate"),
212 early: text("EarlyDate"),
213 late: text("LateDate"),
214 scheduled: text("ScheduleDate"),
215 })
216 }
217}
218
219/// Every event in the model, in file order, read against the model's
220/// declared release (#234).
221///
222/// IFC2X3 declares no `IfcEvent`, so an IFC2X3 model has none.
223///
224/// # Errors
225///
226/// [`ScheduleReadError::UnsupportedSchema`] or
227/// [`ScheduleReadError::MultipleSchemas`] for a header the readers cannot
228/// bind; a header with no schema reads as IFC4.
229pub fn read_events(model: &Model) -> Result<Vec<Event<'_>>, ScheduleReadError> {
230 Ok(events_in(model, ReadRelease::of(model)?))
231}
232
233/// Every event in the model, in file order.
234///
235/// Reads against the model's declared release when the readers can bind
236/// it. A header they cannot bind (IFC4X1, IFC4X2, several schemas) is read
237/// as IFC4, as this function always did; [`read_events`] refuses it
238/// instead.
239#[deprecated(
240 note = "reads an unverified or multi-schema header as IFC4; use `read_events`, which refuses it (#234)"
241)]
242#[must_use]
243pub fn events(model: &Model) -> Vec<Event<'_>> {
244 ReadRelease::of(model)
245 .or_else(|_| ReadRelease::of_version(SchemaVersion::Ifc4))
246 .map_or_else(|_| Vec::new(), |release| events_in(model, release))
247}
248
249fn events_in(model: &Model, release: ReadRelease) -> Vec<Event<'_>> {
250 if !release.declares(EVENT) {
251 return Vec::new();
252 }
253 release
254 .instances_of(model, EVENT)
255 .into_iter()
256 .filter_map(|id| {
257 Some(Event {
258 id,
259 entity: model.get(id)?,
260 release,
261 })
262 })
263 .collect()
264}