Add doc for lookAhead and other functions

DAFFODIL-2179

site/dfdl-extensions.md

@@ -43,15 +43,45 @@ 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 are equivalent:
+```xml
+<xs:element name="a" type="xs:unsignedInt" dfdl:length="3" dfdl:lengthUnits="bits" />
+
+<xs:element name="a" type="xs:unsignedInt" dfdl:length="3" dfdl:lengthUnits="bits" dfdl:inputValueCalc="{ dfdlx:lookAhead(0,3) }" />
+```
+The following example demonstrates using lookAhead to branch based on a field in the future:
+```
+<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 +90,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