Add a File::create_ambient function.

`File::create_ambient` is to `File::open_ambient` as `std::fs::File::create` is
to `std::fs::File::open`.

Author: sunfishcode

cap-async-std/src/fs/file.rs

@@ -131,6 +131,31 @@ impl File {
         .map(|f| Self::from_std(f.into()))
     }
 
+    /// Constructs a new instance of `Self` in write-only mode by opening,
+    /// creating or truncating, the given path as a file using the host
+    /// process' ambient authority.
+    ///
+    /// # Ambient Authority
+    ///
+    /// This function is not sandboxed and may access any path that the host
+    /// process has access to.
+    #[inline]
+    pub async fn create_ambient<P: AsRef<Path>>(
+        path: P,
+        ambient_authority: AmbientAuthority,
+    ) -> io::Result<Self> {
+        let path = path.as_ref().to_path_buf();
+        spawn_blocking(move || {
+            open_ambient(
+                path.as_ref(),
+                OpenOptions::new().write(true).create(true).truncate(true),
+                ambient_authority,
+            )
+        })
+        .await
+        .map(|f| Self::from_std(f.into()))
+    }
+
     /// Constructs a new instance of `Self` with the options specified by
     /// `options` by opening the given path as a file using the host process'
     /// ambient authority.

cap-async-std/src/fs_utf8/file.rs

@@ -125,6 +125,25 @@ impl File {
             .map(Self::from_cap_std)
     }
 
+    /// Constructs a new instance of `Self` in write-only mode by opening,
+    /// creating or truncating, the given path as a file using the host
+    /// process' ambient authority.
+    ///
+    /// # Ambient Authority
+    ///
+    /// This function is not sandboxed and may access any path that the host
+    /// process has access to.
+    #[inline]
+    pub async fn create_ambient<P: AsRef<Path>>(
+        path: P,
+        ambient_authority: AmbientAuthority,
+    ) -> io::Result<Self> {
+        let path = from_utf8(path)?;
+        crate::fs::File::create_ambient(path, ambient_authority)
+            .await
+            .map(Self::from_cap_std)
+    }
+
     /// Constructs a new instance of `Self` with the options specified by
     /// `options` by opening the given path as a file using the host process'
     /// ambient authority.

cap-std/src/fs/file.rs

@@ -123,6 +123,27 @@ impl File {
         Ok(Self::from_std(std))
     }
 
+    /// Constructs a new instance of `Self` in write-only mode by opening,
+    /// creating or truncating, the given path as a file using the host
+    /// process' ambient authority.
+    ///
+    /// # Ambient Authority
+    ///
+    /// This function is not sandboxed and may access any path that the host
+    /// process has access to.
+    #[inline]
+    pub fn create_ambient<P: AsRef<Path>>(
+        path: P,
+        ambient_authority: AmbientAuthority,
+    ) -> io::Result<Self> {
+        let std = open_ambient(
+            path.as_ref(),
+            OpenOptions::new().write(true).create(true).truncate(true),
+            ambient_authority,
+        )?;
+        Ok(Self::from_std(std))
+    }
+
     /// Constructs a new instance of `Self` with the options specified by
     /// `options` by opening the given path as a file using the host process'
     /// ambient authority.

cap-std/src/fs_utf8/file.rs

@@ -128,6 +128,26 @@ impl File {
         )?))
     }
 
+    /// Constructs a new instance of `Self` in write-only mode by opening,
+    /// creating or truncating, the given path as a file using the host
+    /// process' ambient authority.
+    ///
+    /// # Ambient Authority
+    ///
+    /// This function is not sandboxed and may access any path that the host
+    /// process has access to.
+    #[inline]
+    pub fn create_ambient<P: AsRef<Utf8Path>>(
+        path: P,
+        ambient_authority: AmbientAuthority,
+    ) -> io::Result<Self> {
+        let path = from_utf8(path.as_ref())?;
+        Ok(Self::from_cap_std(crate::fs::File::create_ambient(
+            path,
+            ambient_authority,
+        )?))
+    }
+
     /// Constructs a new instance of `Self` with the options specified by
     /// `options` by opening the given path as a file using the host process'
     /// ambient authority.

tests/open-ambient.rs

@@ -9,6 +9,15 @@ fn test_open_ambient() {
     let _ = File::open_ambient("Cargo.toml", ambient_authority()).unwrap();
 }
 
+#[test]
+fn test_create_ambient() {
+    let dir = tempfile::tempdir().unwrap();
+    let foo_path = dir.path().join("foo");
+    let _ = File::create_ambient(&foo_path, ambient_authority()).unwrap();
+    let _ = File::open_ambient(&foo_path, ambient_authority()).unwrap();
+    let _ = File::create_ambient(&foo_path, ambient_authority()).unwrap();
+}
+
 #[test]
 fn test_create_dir_ambient() {
     let dir = tempfile::tempdir().unwrap();