factory constructor Uri.file

Creates a new file URI from an absolute or relative file path.

The file path is passed in path.

This path is interpreted using either Windows or non-Windows semantics.

With non-Windows semantics the slash ("/") is used to separate path segments.

With Windows semantics, backslash ("\\") and forward-slash ("/") are used to separate path segments, except if the path starts with "\\\\?\\" in which case, only backslash ("\\") separates path segments.

If the path starts with a path separator an absolute URI is created. Otherwise a relative URI is created. One exception from this rule is that when Windows semantics is used and the path starts with a drive letter followed by a colon (":") and a path separator then an absolute URI is created.

The default for whether to use Windows or non-Windows semantics determined from the platform Dart is running on. When running in the standalone VM this is detected by the VM based on the operating system. When running in a browser non-Windows semantics is always used.

To override the automatic detection of which semantics to use pass a value for windows. Passing true will use Windows semantics and passing false will use non-Windows semantics.

Examples using non-Windows semantics:

// xxx/yyy
new Uri.file("xxx/yyy", windows: false);

// xxx/yyy/
new Uri.file("xxx/yyy/", windows: false);

// file:///xxx/yyy
new Uri.file("/xxx/yyy", windows: false);

// file:///xxx/yyy/
new Uri.file("/xxx/yyy/", windows: false);

// C:
new Uri.file("C:", windows: false);

Examples using Windows semantics:

// xxx/yyy
new Uri.file(r"xxx\yyy", windows: true);

// xxx/yyy/
new Uri.file(r"xxx\yyy\", windows: true);

file:///xxx/yyy
new Uri.file(r"\xxx\yyy", windows: true);

file:///xxx/yyy/
new Uri.file(r"\xxx\yyy/", windows: true);

// file:///C:/xxx/yyy
new Uri.file(r"C:\xxx\yyy", windows: true);

// This throws an error. A path with a drive letter is not absolute.
new Uri.file(r"C:", windows: true);

// This throws an error. A path with a drive letter is not absolute.
new Uri.file(r"C:xxx\yyy", windows: true);

// file://server/share/file
new Uri.file(r"\\server\share\file", windows: true);

If the path passed is not a legal file path ArgumentError is thrown.