Assign a document URI to a forest index, using the same algorithm as xdmp:document-insert. The return value will be a positive integer from 1 to $forest-count.

This function does not insert or update the document; instead, it returns the index of the forest to which the document URI would be assigned if it were inserted as a new document. In order to match the document to the correct forest, use the list of forest-IDs as returned by xdmp:database-forests.

If the document already exists, this function may not return the correct forest for the document. In this case, xdmp:document-forest will return the correct forest.

If "assignment-policy" is specified, this function uses the specified policy to calculate the assignment. Otherwise, it uses the assignment policy of the context database to calculate the assignment.

This function works only with the bucket assignment policy and the legacy assignment policy. It reports an error if the statistical policy or the range policy is set.

Note that, if there are read-only or delete-only forests in a database that uses the bucket policy, the application may need to call this function twice to get the right assignment. The first call should pass in the total number of forests, including the read-only or delete-only ones. If the returned value happens to be a read-only or delete-only forest, the second call should pass in the number of forests that excludes the read-only or delete-only ones and pass in "legacy" as the third parameter.