XQuery 4.0: An XML Query Language

5.20.2 Constructor Functions for Named Record Types

The construct:

declare record cx:complex(r as xs:double, i as xs:double := 0);

implicitly defines the function:

declare function cx:complex($r as xs:double, $i as xs:double := 0) as cx:complex {
  map:merge((
    { "r": $r },
    { "i": $i }
  ), { "retain-order" : true() })
};

declare function cx:complex($r as xs:double, $i as xs:double := 0) as cx:complex {
  map:merge(( { "r": $r }, { "i": $i } ))
};

So the call cx:complex(3, 2) produces the value { "r": 3e0, "i": 2e0 }, while the call cx:complex(3) produces the value { "r": 3e0, "i": 0e0 }

The resulting map has its [TERMDEF dt-map-ordered IN DM40] property set to true, so the order of entries corresponds to the order of field declarations in the record type. This means, for example, that when the map is serialized using the JSON output method, the order of entries in the output will correspond to the order of field declarations.The order of entries in the map corresponds to the order of field declarations in the record type. This means, for example, that when the map is serialized using the JSON output method, the order of entries in the output will correspond to the order of field declarations.The resulting map has itsorder of entries in [TERMDEF dt-map-ordered IN DM40] property set to true, so the order of entriesthe map corresponds to the order of field declarations in the record type. This means, for example, that when the map is serialized using the JSON output method, the order of entries in the output will correspond to the order of field declarations.

If a field is declared as optional, by including a question mark after the name, and if it has no initializer, then the initializer := () is added implicitly. If the declared type of an optional field does not permit an empty sequence, then the declared type of the function parameter is adjusted by changing the occurrence indicator (from absent to ? or from + to *) in order to make the empty sequence an acceptable value.

Furthermore, if a field is optional and has no explicit initializer, the relevant entry in the constructed map will be absent when the value supplied (implicitly or explicitly) to the function argument is an empty sequence. This is achieved by modifying the function body. Given the declaration:

declare record cx:complex(r as xs:double, i? as xs:double);

the equivalent function declaration is:

declare function cx:complex($r as xs:double, $i as xs:double? := ()) as cx:complex {
  map:merge((
    { "r": $r },
    if (exists($i)) { { "i": $i } }
  ), { "retain-order" : true() })
};

If any field is either declared optional, or has an explicit initializer, then all subsequent fields must also either be declared optional, or have an explicit initializer [err:XQST0148].

If the record type is declared as extensible (by the presence of a final ,*), then an additional paremeter is added to the function declaration. The name of the parameter is options (provided this name is available for use), its declared type is map(*), and its default value is {} (an empty map). The function body is then modified as shown in the following example. Given the declaration:

declare record p:person($first as xs:string, $last as xs:string, *);

the equivalent function declaration is:

declare function p:person(
  $first   as xs:string, 
  $last    as xs:string, 
  $options as map(*) := {}
) as p:person {
  map:merge((
    { "first": $first },
    { "last": $last },
    $options
  ),
  { "duplicates": "use-first", "retain-order" : true() }
 };

declare function p:person(
  $first   as xs:string, 
  $last    as xs:string, 
  $options as map(*) := {}
) as p:person {
  map:merge((
    { "first": $first },
    { "last": $last },
    $options
  ),
  { "duplicates": "use-first" }
 };

The effect of the duplicates option here is that when two values are supplied for the same field, one as a direct argument in the function call and the other in the options map, the value supplied as a direct argument is used in preference. The effect of the ordering option is that the resulting map has an entry order^DM in which the named fields appear first, in order of declaration, followed by the extension entries supplied in $options, retaining the entry order^DM of the $options map.The effect of the duplicates option here is that when two values are supplied for the same field, one as a direct argument in the function call and the other in the options map, the value supplied as a direct argument is used in preference. The resulting map has an entry order^DM in which the named fields appear first, in order of declaration, followed by the extension entries supplied in $options, retaining the entry order^DM of the $options map.The effect of the duplicates option here is that when two values are supplied for the same field, one as a direct argument in the function call and the other in the options map, the value supplied as a direct argument is used in preference. The effect of the ordering option is that the resulting map has an entry order^DM in which the named fields appear first, in order of declaration, followed by the extension entries supplied in $options, retaining the entry order^DM of the $options map.

If the name options is already in use for one of the fields, then the first available name from the sequence ("options1", "options2", ...) is used instead for the additional function parameter.

More formally, the equivalent function declaration is derived as follows:

• The function annotations are the annotations on the named record declaration.

• The function name is the QName of the named record declaration: an unprefixed name is expanded using the default namespace for elements and types. The resulting QName must be the same as the module namespace if the declaration appears in a library module, and in any event, it must be in some namespace.

• The parameters of the function declaration are derived from the fields of the named record declaration, in order.

  • The name of the parameter is the name of the field (always an NCName).

  • The declared type of the parameter is the declared type of the field, if present; but if the field is optional, indicated by a question mark (?) after its name, and has no initializer, then the occurrence indicator is adjusted to permit an empty sequence, as described earlier.

  • The default value for the parameter is given by the initializing expression in the ExtendedFieldDeclaration, if present. If the field is optional and has no initializer, then it is given a default value of (), the empty sequence.

• If the record type is extensible, then a further parameter is added at the end:

  • The name of the parameter is the first available name from the sequence ("options", "options1", "options2", ...).

  • The declared type of the parameter is map(*).

  • The default value of the parameter is {}, the empty map.

• The return type of the function is the name of the record declaration, with no occurrence indicator.

• The body of the function is a call of the function map:merge with two arguments:

  • The first argument is a parenthesized expression containing a comma-separated sequence of subexpressions, containing one subexpression for each field, in order, and optionally a further subexpression for the options parameter if present.

  • By default, the relevant subexpression is the map constructor { "N": $N } where N is the field name.

  • If the field is optional and is declared without an explicit initializer, then the relevant subexpression takes the form if (exists($N)) { { "N": $N } } where N is the field name.

  • The optional final subexpression, if present, takes the form $options, where $options is the name allocated to the final parameter.

  • The second argument in the call of the function map:merge is the map { "duplicates": "use-first", "retain-order": true() }.The second argument in the call of the function map:merge is the map { "duplicates": "use-first" }.The second argument in the call of the function map:merge is the map { "duplicates": "use-first", "retain-order": true() }.

Note that a question mark ? after the field name indicates that the field is optional from the point of view of conformance of an item to the record type. The presence of an initializer indicates that it is optional from the point of view of a call on the constructor function. The two things are independent of each other. For example:

• record(longitude, latitude, altitude?)

  Defines a record type in which altitude entry may be absent, and a constructor function with three arguments, of which the last is optional; if the function is called with two arguments (or with the third argument set to an empty sequence), then there will be no altitude entry in the resulting map.

  record(longitude, latitude, altitude := 0)

  Defines a record type in which all three fields will always be present, and a constructor function in which the third argument can be omitted, defaulting to zero.

  record(longitude, latitude, altitude? := ())

  Defines a record type in which the altitude entry may be absent both from the record and in the function call: but because a default value has been supplied explicitly, the constructed map will always have an entry for altitude.