Skip to content

Commit 65de328

Browse files
committed
Added mention of the size check as well as existance check in the optional condition.
1 parent 6fd295c commit 65de328

1 file changed

Lines changed: 54 additions & 6 deletions

File tree

fields/optional.adoc

Lines changed: 54 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ using **cond** <<intro-properties, property>>.
9292
<optional name="Val1" defaultMode="missing" cond="$Flags.Val1Exists">
9393
<int name="ActVal1" type="uint32" />
9494
</optional>
95-
</fields>
95+
</message>
9696
</schema>
9797
----
9898
**NOTE**, that **cond** property can be used only for **&lt;optional&gt;** field
@@ -129,7 +129,7 @@ For example:
129129
<optional name="F3" defaultMode="exists" cond="$F1 &lt; $F2">
130130
<int name="WrappedF3" type="uint32" />
131131
</optional>
132-
</fields>
132+
</message>
133133
</schema>
134134
----
135135
The `F3` above exists, only if value of **F1** is less than value of **F2**
@@ -153,7 +153,7 @@ Deep (nested) conditions are also expected to be supported by the code generator
153153
<optional name="F3" defaultMode="exists" cond="!$F1.Mem2.B1">
154154
<int name="WrappedF3" type="uint32" />
155155
</optional>
156-
</fields>
156+
</message>
157157
</schema>
158158
----
159159

@@ -178,7 +178,7 @@ actual specified condition is automatically implied.
178178
<optional name="F3" defaultMode="exists" cond="!$F2.WrappedF2.B1">
179179
<int name="WrappedF3" type="uint32" />
180180
</optional>
181-
</fields>
181+
</message>
182182
</schema>
183183
----
184184

@@ -206,7 +206,7 @@ as the reference to a sibling field described above.
206206
<optional name="F2" defaultMode="exists" cond="!%Flags.Mem2.B1">
207207
<int name="WrappedF2" type="uint32" />
208208
</optional>
209-
</fields>
209+
</message>
210210
</schema>
211211
----
212212
**WARNING**: The **CommsDSL** specification supports multiple interfaces and doesn't impose any restriction
@@ -216,6 +216,54 @@ the referenced field. The code generator may also not impose many restrictions o
216216
Usage of the wrong **&lt;interface&gt;** class with the missing referenced
217217
field in the end application may result in compilation errors.
218218

219+
Since **v6.1** of this specification comparing the size of the collection type fields (
220+
**&lt;data&gt;**, **&lt;string&gt;**, and **&lt;list&gt;**) is also supported. The size check condition is determined
221+
by the usage of the `#` character after the one indicating sibling (`$`) or interface (`%`) reference.
222+
[source,xml]
223+
----
224+
<?xml version="1.0" encoding="UTF-8"?>
225+
<schema ...>
226+
<message name="Msg1" id="1">
227+
<data name="F1">
228+
<lengthPrefix>
229+
<int name="Length" type="uint8" />
230+
</lengthPrefix>
231+
</data>
232+
<optional name="F2" defaultMode="missing" cond="$#F1 != 0">
233+
<int name="ActF1" type="uint32" />
234+
</optional>
235+
</message>
236+
</schema>
237+
----
238+
In the example above the `F2` field exists if `F1` is not empty, i.e. its size is not `0`.
239+
240+
Also since **v6.1** of this specification check whether the previously encountered **&lt;optional&gt;** field
241+
exists is also supporting in another **&lt;optional&gt;** field condition. Such check is determined by the
242+
usage of the `?` character after the one indicating sibling (`$`) or interface (`%`) reference.
243+
244+
[source,xml]
245+
----
246+
<?xml version="1.0" encoding="UTF-8"?>
247+
<schema ...>
248+
<message name="Msg1" id="1">
249+
<set name="F1">
250+
<bit name="B0" idx="0" />
251+
<bit name="B1" idx="1" />
252+
</set>
253+
<optional name="F2" defaultMode="missing" cond="$F1.B0">
254+
<set name="ActF2">
255+
<bit name="B0" idx="0" />
256+
<bit name="B1" idx="1" />
257+
</set>
258+
</optional>
259+
<optional name="F3" defaultMode="exists" cond="!$?F2">
260+
<int name="ActF3" type="uint32" />
261+
</optional>
262+
</fields>
263+
</schema>
264+
----
265+
In the example above `F3` exists when `F2` is missing.
266+
219267
[[fields-optional-multiple-existence-conditions]]
220268
==== Multiple Existence Conditions ====
221269
The **CommsDSL** also allows usage of multiple existence condition statements. However,
@@ -279,7 +327,7 @@ place in the input buffer.
279327
Similar to <<fields-optional-missing-on-failed-read, missingOnReadFail>>, but with a bit of different
280328
flavour, the property **missingOnInvalid** insures that the **&lt;optional&gt;** field is marked as
281329
"missing" when the held field's value is invalid (applicable to the __refresh__ operation).
282-
In case of recognition the invalid value
330+
In case of recognition of the invalid value
283331
during the __read__ operation, the **&lt;optional&gt;** field must be marked as "missing" and
284332
reading of the following fields must continue from the place in the input buffer as if the __read__
285333
operation of the **&lt;optional&gt;** field didn't take place.

0 commit comments

Comments
 (0)