nondeterministic context-dependent focus-independent

Tests if a file or directory exists.

Returns true if $path points to an existing file or directory, false otherwise.

On a UNIX-based system, the root and the volume roots are considered directories.

file:exists('.') true() file:exists('/') true() nondeterministic context-dependent focus-independent

Tests if $path points to a directory.

Returns true if $path points to an existing directory as defined in (no regular file, no symbolic link, no other operating-system specific file type). Otherwise, it returns false.

On a UNIX-based system, the root and the volume roots are considered directories.

file:is-dir('.') true() file:is-dir('/') true() nondeterministic context-dependent focus-independent

Tests if $path points to a regular file.

Returns true if $path points to an existing regular file as defined in (no directory, no symbolic link, no other operating-system specific file type). Otherwise, it returns false.

file:is-file('.') false() file:is-file('/') false() nondeterministic context-dependent focus-independent

Tests if $path is absolute.

Returns true if $path is absolute, false otherwise.

A path is absolute if it contains all the components necessary to identify a file location, without reference to a current drive or a current working directory.

All UNC file names are absolute.

The function may return a different result for the same path on a Windows and a UNIX-based system.

file:is-absolute('abc') false() file:is-absolute('/') Returns true on a UNIX-based system and false on a Windows system.

New in 4.0.

nondeterministic context-dependent focus-independent

Returns the last modification time of a file or directory.

Returns an xs:dateTime item representing the last modification of a file or directory.

is raised if the specified path does not exist.

is raised if any other error occurs.

file:last-modified('.') Returns the last modification time of the . file:last-modified(file:base-dir()) Returns the last modification time of the . nondeterministic context-dependent focus-independent

Returns the size of a file or directory.

If $path points to a file, returns the byte size of this file. Otherwise, if it points to a directory, returns either 0 or, if $recursive is true, the aggregated size of all files and subdirectories.

is raised if the specified path does not exist.

is raised if any other error occurs.

file:size('.') 0 file:size('/') 0

$recursive parameter added.

nondeterministic context-dependent focus-independent

Appends a serialized value to a file.

Serializes a value and appends the resulting string to a file. If the file pointed to by $file does not exist, a new file will be created.

The $options argument controls the way how $value is serialized. The semantics are the same as for . In contrast to fn:serialize, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified file does not exist.

is raised if the specified path points to a directory.

is raised if any other error occurs.

)]]> Appends a serialized element node to the file fragments.xml. The file is created if it does not already exist. file:append('snippets.json', { 'one': 1 }, { 'method': 'json' }) Serializes a map as JSON and appends the resulting string to the file snippets.json.

$options can now be a map, in alignment with fn:serialize.

nondeterministic context-dependent focus-independent

Appends binary data to a file.

Appends the binary data of an xs:base64Binary item to a file. If the file pointed to by $file does not exist, a new file will be created.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if any other error occurs.

file:append-binary('data.bin', xs:hexBinary('414243')) Appends the bytes 0x44, 0x43 and 0x41 to the file data.bin. The file is created if it does not already exist. nondeterministic context-dependent focus-independent

Appends a string to a file.

Appends a string to a file. If the file pointed to by $file does not exist, a new file will be created.

If no encoding is supplied, UTF-8 is used as output encoding.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:append-text('todos.txt', 'clean up') Appends a string to the file todos.txt. The file is created if it does not already exist. nondeterministic context-dependent focus-independent

Appends a sequence of strings to a file, each followed by the operating-system specific newline character.

Appends a sequence of strings to a file, each followed by the operating-system specific newline character. If the file pointed to by $file does not exist, a new file will be created.

If no encoding is supplied, UTF-8 is used as output encoding.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:append-text-lines('numbers.txt', (1 to 5) ! string()) Appends the string representation of the integers 1 to 5 to the file numbers.txt. The file is created if it does not already exist. nondeterministic context-dependent focus-independent

Copies a file or a directory.

Copies a file or a directory given a source and a target path/URI. The following rules apply if $source points to a file:

if $target does not exist, it will be created.

if $target is a file, it will be overwritten.

if $target is a directory, the file will be created in that directory with the name of the source file. If a file already exists, it will be overwritten.

Otherwise, if $source points to a directory:

if $target does not exist, it will be created as directory, and all files of the source directory are copied to this directory with their existing local names.

if $target is a directory, the source directory with all its files will be copied into the target directory. At each level, if a file already exists in the target with the same name as in the source, it is overwritten. If a directory already exists in the target with the same name as in the source, it is not removed, it is recursed in place. If it does not exist, it is created before recursing.

Other cases will result in one of the errors listed below.

The function returns the empty sequence if the operation is successful. No rollback to the original state will be possible if an error occurs during the operation.

is raised if the specified path does not exist.

is raised if the specified source path points to a directory and target path points to an existing file.

is raised if the parent directory of the specified source path does not exist.

is raised if the specified source path points to a file and the target path points to a directory in which a subdirectory exists with the name of the source file.

is raised if any other error occurs.

file:copy('a.txt', 'b.txt') Creates a copy of the file a.txt in the same directory, named b.txt. file:copy('a.txt', '../') Creates a copy of the file a.txt with the same name in the parent directory. file:copy('dir/', 'dir2/') Creates a recursive copy of the directory dir in the , named dir2. If dir2 already exists, the contents of dir will be copied into that directory. nondeterministic context-dependent focus-independent

Creates a directory.

Creates a directory unless it already exists. The operation will also create non-existing parent directories.

The function returns the empty sequence if the operation is successful.

is raised if the specified path, or any of its parent directories, points to an existing file.

is raised if any other error occurs.

file:create-dir('examples') Creates a directory named examples in the . file:create-dir('/') Does nothing, as the root directory already exists. nondeterministic context-dependent focus-independent

Creates a temporary directory.

Creates a temporary directory with an optional $prefix and $suffix in the filename, and returns the full path to the created directory. The path will point to a directory that did not exist before the function was called.

If $dir is omitted or an empty sequence, the directory will be created inside the operating-system specific default temporary-file directory.

The created directory will not be deleted automatically after query execution.

is raised if the specified directory does not exist or points to a file.

is raised if any other error occurs.

file:parent(file:create-temp-dir()) = file:temp-dir() true() file:create-temp-dir(dir := file:base-dir()) Creates a temporary directory in the or, if it is undefined, in the default temporary-file directory. let $dir := file:create-temp-dir() return try { file:write($dir || 'tmp.data', 1 to 10) } finally { file:delete($dir, true()) } Creates a temporary directory, writes a file into that directory, and deletes it again.

All parameters are optional now.

nondeterministic context-dependent focus-independent

Creates a temporary file.

Creates an empty temporary file with an optional $prefix and $suffix in the filename, and returns the full path to the created file. The path will point to a file that did not exist before the function was called.

If $dir is omitted or an empty sequence, the file will be created inside the operating-system specific default temporary-file directory.

The created file will not be deleted automatically after query execution.

is raised if the specified does not exist or points to a file.

is raised if any other error occurs.

file:create-temp-file(suffix := '.txt') Creates a file with the suffix .txt in the temporary-file directory.

All parameters are optional now.

nondeterministic context-dependent focus-independent

Deletes a file or a directory.

Deletes a file or a directory from the file system if it exists:

If $path points to a file, the file is deleted.

Otherwise, if $path points to a directory, then:

if it is non-empty and $recursive is false, an error is raised.

Otherwise, the directory and all its contents are deleted recursively.

Otherwise, nothing happens.

The function returns the empty sequence if the operation is successful.

No rollback to the original state will be possible if an error occurs during the operation.

is raised if the specified path points to a non-empty directory and if the deletion is not recursive.

is raised if any other error occurs.

file:delete('list.txt') Deletes the file list.txt from the . file:delete('examples', true()) Deletes the file or directory example and (if available) all subdirectories.

Non-existing paths are now ignored.

nondeterministic context-dependent focus-independent

Lists all files and directories in a given directory.

Lists all files and directories in a given directory. In contrast to is file:children, the returned paths are relative to the supplied directory $dir. The order of the items in the resulting sequence is not defined. The references to the specified directory and its parent directory (. and ..) are not returned.

If $recursive is true, all directories and files will be returned that are found while recursively traversing the given directory. Otherwise, only the contents of the specified directory will be returned.

The $pattern argument is used to define a name pattern in the glob syntax. If supplied, only the paths of the files and directories whose names are matching the pattern will be returned.

An implementation must support at least the following glob syntax characters:

* for matching any number of unknown characters and

? for matching one unknown character.

A related function is file:children.

is raised if the specified path does not exist.

is raised if the specified path does not point to an existing directory.

is raised if any other error occurs.

file:list('.') Returns the names of all files in the . file:list('.', pattern := '*.zip') Returns the names of archive files in the . let $root := '/path/to/files/' for $file in file:list($root, true(), '*.txt') let $path := file:resolve-path($file, $root) where file:size($path) > 1000000 return file:read-text($path) Returns the contents of large text files found in a specific directory and its subdirectories.

$pattern can now be supplied without supplying $recursive.

nondeterministic context-dependent focus-independent

Lists all root directories of the file system.

Lists all root directories of the file system:

On a Windows system, root directories are usually the letters of the currently available drives, followed by a colon and a backslash (for example, C:\ and D:\).

On a UNIX-based system, it is usually a single slash, denoting the root directory.

Dynamically available UNC file names are not returned by this function.

file:list-roots('/') A single slash as result indicates a UNIX-based system.

New in 4.0.

nondeterministic context-dependent focus-independent

Moves a file or a directory.

Moves a file or a directory given a source and a target path/URI. The following rules apply if $source points to a file:

if $target does not exist, it will be created.

if $target is a file, it will be overwritten.

if $target is a directory, the file will be created in that directory with the name of the source file. If a file already exists, it will be overwritten.

Otherwise, if $source points to a directory:

if $target does not exist, it will be created as directory, and all files of the source directory are moved to this directory with their existing local names.

if $target is a directory, the source directory with all its files will be moved into the target directory. If the target directory contains a directory with the same name as the source, the error is raised.

Other cases will result in one of the errors listed below.

The function returns the empty sequence if the operation is successful. No rollback to the original state will be possible if an error occurs during the operation.

is raised if the specified source path does not exist.

is raised if the specified source path points to a directory and target path points to an existing file.

is raised if the parent directory of the specified source path does not exist.

is raised if the specified target path points to a directory in which a subdirectory exists with the name of the source.

is raised if any other error occurs.

file:move('a.txt', 'b.txt') Renames a.txt to b.txt. file:move('a.txt', '../') Moves the file a.txt to the parent directory. file:move('dir/', 'dir2/') Renames dir to dir2. If dir2 already exists, moves the source directory into that directory. nondeterministic context-dependent focus-independent

Returns the binary content of a file.

Returns the content of a file as an xs:base64Binary item.

Chunks of a file can be read by supplying $offset and $length. If no value is supplied for $length, all remaining bytes will be read. If only $length is specified, the offset is 0.

is raised if the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified offset or length value is negative, or if the value would exceed the file bounds.

is raised if any other error occurs.

file:read-binary('data.bin') eq xs:hexBinary('41') Returns true if the file data.bin contains the single byte 0x41. file:read-binary('data.bin', file:size($path) - 1, 1) Returns the last byte of the file data.bin.

$length can now be supplied without supplying $offset.

nondeterministic context-dependent focus-independent

Returns the content of a file as a string.

Returns the content of a file in its string representation. Newlines are normalized: Any U+000D character, optionally followed by a U+000A character, is converted to a single U+000A character.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map { "encoding": $S }. After that substitution, the apply.

The entries that may appear in the $options map are as follows:

Defines the encoding of the resource, as described below. xs:string? "UTF-8" If $fallback is true, any character that cannot be decoded or that is not a is replaced by the Unicode replacement character (U+FFFD). xs:boolean false

is raised if the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

contains(file:read-text('todos.txt'), 'push forward') Returns true if the file todos.txt contains the specified string. 'test.bin' => file:write-binary(xs:hexBinary('00')) => file:read-text(fallback := true()) => string-to-codepoints() 65533 Returns the codepoint value of the Unicode replacement character.

$options parameter added.

The normalization of newlines has been made explicit.

A fallback option is now provided to address characters that cannot be decoded or are not permitted.

nondeterministic context-dependent focus-independent

Returns the contents of a file as a sequence of strings, separated at newline boundaries.

Any of the character sequences U+000A, U+000D, or U+000D followed by U+000A is interpreted as newline.

The entries that may appear in the $options map are as follows:

is raised if the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

let $file := 'numbers.txt' let $data := (1 to 5) ! string() return ( file:write-text-lines($file, $data), file:read-text-lines($file) => deep-equal($data) ) true() Can be used to prove that the written and read strings are equal.

$fallback parameter added.

The $fallback parameter has been integrated into the options map.

nondeterministic context-dependent focus-independent

Writes a serialized value to a file.

Serializes a value and appends the resulting string to a file. If the file pointed to by $file already exists, it will be overwritten; otherwise, it will be created.

The $options argument controls the way how $value is serialized. The semantics are the same as for . In contrast to fn:serialize, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if any other error occurs.

file:write('numbers.txt', 1 to 10) Writes 10 numbers to the file numbers.txt. , { 'encoding': 'us-ascii', 'indent': true() } ) ]]> Serializes an indented element node as US-ASCII and writes it to the file result.xml. file:write( 'numbers.json', map:build(1 to 10, string#1), { 'method': 'json' } ) Writes a map, serialized as JSON, to a specified file.

$options can now be a map, in alignment with fn:serialize.

nondeterministic context-dependent focus-independent

Writes binary data to a file.

Writes the binary data of an xs:base64Binary item to a file. If the file pointed to by $file already exists, it will be overwritten; otherwise, it will be created.

If $offset is specified and not an empty sequence, data will be written starting at this file position, and existing bytes will be overwritten. The operation may resize the existing file.

The function returns the empty sequence if the operation is successful.

Supplying an offset makes sense only if the file already exists.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified offset is negative, or if it exceeds the current file size.

is raised if any other error occurs.

file:write-binary('data.bin', xs:hexBinary('414243')) Writes the bytes 0x44, 0x43 and 0x41 to the file data.bin. file:write-binary('data.bin', xs:hexBinary('44', 2)) If this expression is called after the previous one, overwrites the last byte with 0x44. nondeterministic context-dependent focus-independent

Writes a string to a file.

Writes a string to a file. If the file pointed to by $file already exists, it will be overwritten.

If no encoding is supplied, UTF-8 is used as output encoding.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:write-text('todos.txt', 'get organized') Writes a string to the file todos.txt. The file is created if it does not already exist. nondeterministic context-dependent focus-independent

Writes strings to a file.

Writes strings to a file, each followed by the operating-system specific newline character. If the file pointed to by $file already exists, it will be overwritten; otherwise, it will be created.

If no encoding is supplied, UTF-8 is used as output encoding.

The function returns the empty sequence if the operation is successful.

is raised if the parent directory of the specified path does not exist.

is raised if the specified path points to a directory.

is raised if the specified encoding is invalid or not supported by the implementation.

is raised if any other error occurs.

file:write-text-lines('numbers.txt', (1 to 5) ! string()) Writes the string representation of the integers 1 to 5 to the file numbers.txt. deterministic context-independent focus-independent

Returns the name of a file or directory.

Returns the name of a file or directory. An empty string is returned if the path points to the root directory.

This function is deterministic: the path is neither checked for correctness nor looked up in the file system.

file:name('') '' file:name('/') '' file:name('hello.txt') 'hello.txt' file:name('dir/') 'dir' file:name('dir/file.txt') 'file.txt' file:name('dir/..') '..' file:name('file:///tmp/001.bin') '001.bin' nondeterministic context-dependent focus-independent

Returns the path to the parent directory of a given path.

Transforms the given path into an absolute path, as specified by file:resolve-path, and returns the parent directory.

An empty sequence is returned if the path points to a root directory.

The inverse function is file:children.

file:parent('/') () file:current-dir() = file:parent('abc') true() nondeterministic context-dependent focus-independent

Returns the paths of all files and directories that are located in the given directory.

Returns the paths of all files and directories that are located in the given directory. The order of the items in the resulting sequence is not defined. The references to the specified directory and its parent directory (. and ..) are not returned.

The inverse function is file:parent; a related function is file:list.

is raised if the specified path does not exist.

is raised if the specified path does not point to an existing directory.

is raised if any other error occurs.

count(file:children('.')) Counts the files and directories in the . file:children('path/to/media/') [matches(., '\.(avi|mpg|mp4)$', 'i')] Returns the paths to large videos found in a specific directory. nondeterministic context-dependent focus-independent

Returns the paths of all files and directories that are located in the given directory and its subdirectories.

Returns the paths of all files and directories that are located in the given directory and its subdirectories. The order of the items in the resulting sequence is not defined. The references to the specified directory and its parent directory (. and ..) are not returned.

is raised if the specified path does not exist.

is raised if the specified path does not point to an existing directory.

is raised if any other error occurs.

count(file:descendants('.')[file:is-directory(.)]) Counts the subdirectories in the . for $file in file:descendants('.') where file:last-modified($file) > current-dateTime() - xs:dayTimeDuration('PT1H') return $file Returns the paths to all files that have been modified in the last hour.

New in 4.0.

nondeterministic context-dependent focus-independent

Transforms a path to a canonical representation.

Transforms a URI, an absolute path, or relative path to a canonical, operating-system specific path representation. A canonical path is both absolute and unique and thus contains no redirections such as references to parent directories or symbolic links.

If the resulting path points to a directory, it will be suffixed with the operating-system specific directory separator.

is raised if the specified path does not exist.

is raised if an error occurs while trying to generate the native path.

file:path-to-native('/') Returns / on a UNIX-based system. deterministic context-independent focus-independent

Transforms a file system path into a URI.

Transforms a file system path into a URI with the file scheme. If the path is relative, it is first resolved against the .

This function is deterministic: the path is neither checked for correctness nor looked up in the file system.

file:path-to-uri('/temp') Returns file:///temp on a UNIX-based system contains(file:path-to-uri('a b'), '%20') true() Space characters will be encoded to %20. nondeterministic context-dependent focus-independent

Transforms a relative path into an absolute operating system path.

Transforms a relative path into an absolute operating system path. The following rules apply in order:

If $path is an absolute path, it is not changed.

Otherwise, if $base is the empty sequence, $path is resolved against the .

Otherwise, it is resolved against the supplied base path or, if the base path does not point to a directory, to its parent directory. An error is raised if the base is a relative path.

If the resulting path points to a directory, it will be suffixed with the operating-system specific directory separator.

is raised if the specified base directory is relative.

file:resolve-path('INF', 'C:/Windows/') 'C:/Windows/INF/' The result refers to a Windows system. file:resolve-path('data.bin', 'C:/Temp') 'C:/data.bin' The result refers to a Windows system. file:resolve-path('hilda/notes.txt', '/home/') '/home/hilda/notes.txt' The result refers to a UNIX-based system.

$base parameter added.

nondeterministic context-dependent focus-independent

Returns the directory separator.

Returns the value of the operating-system specific directory separator, which usually is / on UNIX-based systems and \ on Windows systems.

file:dir-separator() = ('/', '\') true() nondeterministic context-dependent focus-independent

Returns the line separator.

Returns the value of the operating-system specific line separator, which usually is 
 on UNIX-based systems, 
 on Windows systems and  on old Mac systems.

matches(file:line-separator(), '^(\n|\r\n|\r)$') true() nondeterministic context-dependent focus-independent

Returns the path separator.

Returns the value of the operating-system specific path separator, which usually is : on UNIX-based systems and ; on Windows systems.

file:dir-separator() = (':', ';') true() nondeterministic context-dependent focus-independent

Returns the path to the temporary-file directory.

Returns the path to the default temporary-file directory of an operating system.

file:write-text(file:temp-dir() || 'todos.txt', 'get on going') Write a text string to a file in the temporary-file directory. nondeterministic context-dependent focus-independent

Returns the base directory.

Returns the . If defined, the function returns the same result as the expression file:parent(static-base-uri()). Otherwise, it returns an empty sequence

let $dir := file:base-dir() otherwise file:create-temp-dir() return file:write-text($dir || 'todos.txt', 'get up') Writes todos.txt to the or, if it is not defined, to a temporary directory. nondeterministic context-dependent focus-independent

Returns the current working directory.

Returns the . All relative file paths are resolved against this directory.

file:resolve-path('.') file:path-to-native('todos.txt') = file:path-to-native(file:current-dir() || 'todos.txt') true() Both paths refer to the same file.