@@ -375,6 +375,44 @@ impl File {
375375 OpenOptions :: new ( ) . read ( true ) . open ( path. as_ref ( ) )
376376 }
377377
378+ /// Attempts to open a file in read-only mode with buffering.
379+ ///
380+ /// See the [`OpenOptions::open`] method, the [`BufReader`][io::BufReader] type,
381+ /// and the [`BufRead`][io::BufRead] trait for more details.
382+ ///
383+ /// If you only need to read the entire file contents,
384+ /// consider [`std::fs::read()`][self::read] or
385+ /// [`std::fs::read_to_string()`][self::read_to_string] instead.
386+ ///
387+ /// # Errors
388+ ///
389+ /// This function will return an error if `path` does not already exist.
390+ /// Other errors may also be returned according to [`OpenOptions::open`].
391+ ///
392+ /// # Examples
393+ ///
394+ /// ```no_run
395+ /// #![feature(file_buffered)]
396+ /// use std::fs::File;
397+ /// use std::io::BufRead;
398+ ///
399+ /// fn main() -> std::io::Result<()> {
400+ /// let mut f = File::open_buffered("foo.txt")?;
401+ /// assert!(f.capacity() > 0);
402+ /// for (line, i) in f.lines().zip(1..) {
403+ /// println!("{i:6}: {}", line?);
404+ /// }
405+ /// Ok(())
406+ /// }
407+ /// ```
408+ #[ unstable( feature = "file_buffered" , issue = "130804" ) ]
409+ pub fn open_buffered < P : AsRef < Path > > ( path : P ) -> io:: Result < io:: BufReader < File > > {
410+ // Allocate the buffer *first* so we don't affect the filesystem otherwise.
411+ let buffer = io:: BufReader :: < Self > :: try_new_buffer ( ) ?;
412+ let file = File :: open ( path) ?;
413+ Ok ( io:: BufReader :: with_buffer ( file, buffer) )
414+ }
415+
378416 /// Opens a file in write-only mode.
379417///
380418/// This function will create a file if it does not exist,
@@ -404,6 +442,45 @@ impl File {
404442 OpenOptions :: new ( ) . write ( true ) . create ( true ) . truncate ( true ) . open ( path. as_ref ( ) )
405443 }
406444
445+ /// Opens a file in write-only mode with buffering.
446+ ///
447+ /// This function will create a file if it does not exist,
448+ /// and will truncate it if it does.
449+ ///
450+ /// Depending on the platform, this function may fail if the
451+ /// full directory path does not exist.
452+ ///
453+ /// See the [`OpenOptions::open`] method and the
454+ /// [`BufWriter`][io::BufWriter] type for more details.
455+ ///
456+ /// See also [`std::fs::write()`][self::write] for a simple function to
457+ /// create a file with some given data.
458+ ///
459+ /// # Examples
460+ ///
461+ /// ```no_run
462+ /// #![feature(file_buffered)]
463+ /// use std::fs::File;
464+ /// use std::io::Write;
465+ ///
466+ /// fn main() -> std::io::Result<()> {
467+ /// let mut f = File::create_buffered("foo.txt")?;
468+ /// assert!(f.capacity() > 0);
469+ /// for i in 0..100 {
470+ /// writeln!(&mut f, "{i}")?;
471+ /// }
472+ /// f.flush()?;
473+ /// Ok(())
474+ /// }
475+ /// ```
476+ #[ unstable( feature = "file_buffered" , issue = "130804" ) ]
477+ pub fn create_buffered < P : AsRef < Path > > ( path : P ) -> io:: Result < io:: BufWriter < File > > {
478+ // Allocate the buffer *first* so we don't affect the filesystem otherwise.
479+ let buffer = io:: BufWriter :: < Self > :: try_new_buffer ( ) ?;
480+ let file = File :: create ( path) ?;
481+ Ok ( io:: BufWriter :: with_buffer ( file, buffer) )
482+ }
483+
407484 /// Creates a new file in read-write mode; error if the file exists.
408485///
409486/// This function will create a file if it does not exist, or return an error if it does. This
0 commit comments