This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/daffodil-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new ca4f31e Publishing from 701ac352e36bf1ad7a304798bc7e9145d1e82443
ca4f31e is described below
commit ca4f31e55e38ed43f7eb41d9ad6324f876ebd3b9
Author: Apache Daffodil Site Autobuild <[email protected]>
AuthorDate: Mon Feb 3 14:18:44 2025 +0000
Publishing from 701ac352e36bf1ad7a304798bc7e9145d1e82443
---
content/dfdl-extensions/index.html | 50 +++++++++++++++++++++++++++++++++++---
1 file changed, 46 insertions(+), 4 deletions(-)
diff --git a/content/dfdl-extensions/index.html
b/content/dfdl-extensions/index.html
index c7194a8..3fd52dd 100644
--- a/content/dfdl-extensions/index.html
+++ b/content/dfdl-extensions/index.html
@@ -116,16 +116,53 @@ like so:</p>
<dd>
<p>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.</p>
- <p><em>This function is deprecated as of Daffodil 2.0.0. Use the <code
class="language-plaintext highlighter-rouge">fn:error(...)</code> function
instead.</em></p>
+ <p><em>This function is deprecated as of Daffodil 2.0.0.
+ Use the <code class="language-plaintext
highlighter-rouge">fn:error(...)</code> function instead.</em></p>
</dd>
<dt><code class="language-plaintext highlighter-rouge">dfdlx:trace($value,
$label)</code></dt>
<dd>
<p>A function that can be used in DFDL expressions, similar to the <code
class="language-plaintext highlighter-rouge">fn:trace()</code> function. This
logs the string <code class="language-plaintext
highlighter-rouge">$label</code> followed by <code class="language-plaintext
highlighter-rouge">$value</code> converted to a string and returns <code
class="language-plaintext highlighter-rouge">$value</code>. The second argument
must be of type <code class="language-plaintext highlighter [...]
</dd>
- <dt><code class="language-plaintext
highlighter-rouge">dfdlx:lookahead(offset, bitSize)</code></dt>
+ <dt><code class="language-plaintext
highlighter-rouge">dfdlx:lookAhead(offset, bitSize)</code></dt>
<dd>
- <p>TBD</p>
+ <p>Read <code class="language-plaintext highlighter-rouge">bitSize</code>
bits, where the first bit is located at an <code class="language-plaintext
highlighter-rouge">offset</code> (in bits)
+ from the current location. The result is a <code class="language-plaintext
highlighter-rouge">xs:nonNegativeInteger</code>. Restrictions:</p>
</dd>
+</dl>
+
+<ul>
+ <li>offset >=0</li>
+ <li>bitSize >= 1</li>
+ <li>distance + bitSize <= Implementation defined limit no less than 512
bits</li>
+ <li>Cannot be called during unparse</li>
+ <li>Parse Error if the offset results in attempting to look ahead past
EOF</li>
+ <li>Undefined behavior if the offset results in attempting to look past the
current data limit of
+a <code class="language-plaintext
highlighter-rouge">dfdl:lengthKind="explicit"</code> surrounding element.</li>
+ <li>The <code class="language-plaintext
highlighter-rouge">dfdl:bitOrder</code> and <code class="language-plaintext
highlighter-rouge">dfdl:byteOrder</code> are determined by the current schema
component
+and data location.</li>
+ <li>DFDL property changes between the current location and the location
containing
+the data being read will not be used.</li>
+</ul>
+
+<h4 id="examples-of-dfdlxlookahead">Examples of <code
class="language-plaintext highlighter-rouge">dfdlx:lookAhead</code></h4>
+<p>The following two elements both populate element <code
class="language-plaintext highlighter-rouge">a</code> 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.</p>
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><xs:element</span> <span
class="na">name=</span><span class="s">"a"</span> <span
class="na">type=</span><span class="s">"xs:unsignedInt"</span> <span
class="na">dfdl:length=</span><span class="s">"3"</span> <span
class="na">dfdl:lengthUnits=</span><span class="s">"bits"</span> <span
class="nt">/></span>
+
+<span class="nt"><xs:element</span> <span class="na">name=</span><span
class="s">"a"</span> <span class="na">type=</span><span
class="s">"xs:unsignedInt"</span> <span
class="na">dfdl:inputValueCalc=</span><span class="s">"{ dfdlx:lookAhead(0,3)
}"</span> <span class="nt">/></span>
+</code></pre></div></div>
+<p>The following example demonstrates using lookAhead to branch based on a
field in the future.
+In this case the choice of elements <code class="language-plaintext
highlighter-rouge">a</code> vs. <code class="language-plaintext
highlighter-rouge">b</code> depends on the value of the <code
class="language-plaintext highlighter-rouge">tag</code> field which is
+found after fields <code class="language-plaintext highlighter-rouge">a</code>
and <code class="language-plaintext highlighter-rouge">b</code>:</p>
+<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><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" />
+</code></pre></div></div>
+
+<dl>
<dt>Bitwise Functions</dt>
<dd>
<p>TBD, but the complete list (all <code class="language-plaintext
highlighter-rouge">dfdlx</code>) is <code class="language-plaintext
highlighter-rouge">BitAnd</code>, <code class="language-plaintext
highlighter-rouge">BitNot</code>, <code class="language-plaintext
highlighter-rouge">BitOr</code>, <code class="language-plaintext
highlighter-rouge">BitXor</code>, <code class="language-plaintext
highlighter-rouge">LeftShift</code>,
@@ -133,7 +170,12 @@ like so:</p>
</dd>
<dt><code class="language-plaintext
highlighter-rouge">dfdlx:doubleFromRawLong</code> and <code
class="language-plaintext highlighter-rouge">dfdlx:doubleToRawLong</code></dt>
<dd>
- <p>TBD</p>
+ <p>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 <code class="language-plaintext
highlighter-rouge">xs:long</code> so that no information is lost. The DFDL
schema can still obtain
+ and operate on the floating point value by converting these <code
class="language-plaintext highlighter-rouge">xs:long</code> values into type
+ <code class="language-plaintext highlighter-rouge">xs:double</code>, and
back if necessary for unparsing a new value.</p>
</dd>
</dl>
