This is an automated email from the ASF dual-hosted git repository.
mbeckerle pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/daffodil-site.git
The following commit(s) were added to refs/heads/main by this push:
new 701ac35 Add doc for lookAhead and other functions
701ac35 is described below
commit 701ac352e36bf1ad7a304798bc7e9145d1e82443
Author: Michael Beckerle <[email protected]>
AuthorDate: Thu Jan 30 11:47:38 2025 -0500
Add doc for lookAhead and other functions
Does not close the ticket/issue as there are still other TBDs.
DAFFODIL-2179
---
site/dfdl-extensions.md | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 44 insertions(+), 5 deletions(-)
diff --git a/site/dfdl-extensions.md b/site/dfdl-extensions.md
index 443ef73..35a18bf 100644
--- a/site/dfdl-extensions.md
+++ b/site/dfdl-extensions.md
@@ -43,15 +43,49 @@ The following symbols defined in this namespace are
described below.
: A function that can be used in DFDL expressions. This functions does not
return a value or accept any arguments. When called, it causes a Parse Error or
Unparse Error.
- *This function is deprecated as of Daffodil 2.0.0. Use the
``fn:error(...)`` function instead.*
+ *This function is deprecated as of Daffodil 2.0.0.
+ Use the ``fn:error(...)`` function instead.*
``dfdlx:trace($value, $label)``
: A function that can be used in DFDL expressions, similar to the
``fn:trace()`` function. This logs the string ``$label`` followed by ``$value``
converted to a string and returns ``$value``. The second argument must be of
type ``xs:string``.
-``dfdlx:lookahead(offset, bitSize)``
-
- : TBD
+``dfdlx:lookAhead(offset, bitSize)``
+
+ : Read ``bitSize`` bits, where the first bit is located at an ``offset``
(in bits)
+ from the current location. The result is a ``xs:nonNegativeInteger``.
Restrictions:
+
+- offset >=0
+- bitSize >= 1
+- distance + bitSize <= Implementation defined limit no less than 512 bits
+- Cannot be called during unparse
+- Parse Error if the offset results in attempting to look ahead past EOF
+- Undefined behavior if the offset results in attempting to look past the
current data limit of
+a ``dfdl:lengthKind="explicit"`` surrounding element.
+- The ``dfdl:bitOrder`` and ``dfdl:byteOrder`` are determined by the current
schema component
+and data location.
+- DFDL property changes between the current location and the location
containing
+the data being read will not be used.
+
+#### Examples of `dfdlx:lookAhead`
+ The following two elements both populate element `a` with the value of the
next 3 bits as an
+ unsignedInt. They are not completely equivalent because the first will
consume 3 bits of the
+ input stream where the second will not advance the input stream.
+```xml
+<xs:element name="a" type="xs:unsignedInt" dfdl:length="3"
dfdl:lengthUnits="bits" />
+
+<xs:element name="a" type="xs:unsignedInt" dfdl:inputValueCalc="{
dfdlx:lookAhead(0,3) }" />
+```
+The following example demonstrates using lookAhead to branch based on a field
in the future.
+In this case the choice of elements `a` vs. `b` depends on the value of the
`tag` field which is
+found after fields `a` and `b`:
+```
+<xs:choice dfdl:choiceDispatchKey="{ dfdlx:lookAhead(16,8) }">
+ <xs:element name="a" type="xs:int" dfdl:length="16"
dfdl:choiceBranchKey="1"/>
+ <xs:element name="b" type="xs:int" dfdl:length="16"
dfdl:choiceBranchKey="2"/>
+</xs:choice>
+<xs:element name="tag" type="xs:int" dfdl:length="8" />
+```
Bitwise Functions
@@ -60,7 +94,12 @@ Bitwise Functions
``dfdlx:doubleFromRawLong`` and ``dfdlx:doubleToRawLong``
- : TBD
+ : Converting binary floating point numbers to/from base 10 text can result
in lost information.
+The base 10 representation, converted back to binary representation, may not
be bit-for-bit
+ identical. These functions can be used to carry 8-byte double precision
IEEE floating point
+ numbers as type `xs:long` so that no information is lost. The DFDL schema
can still obtain
+ and operate on the floating point value by converting these `xs:long`
values into type
+ `xs:double`, and back if necessary for unparsing a new value.
### Properties
