Trait FileExt 

pub trait FileExt {
    // Required methods
    fn seek_read(&self, buf: &mut [u8], offset: u64) -> Result<usize>;
    fn seek_write(&self, buf: &[u8], offset: u64) -> Result<usize>;

    // Provided methods
    fn seek_read_exact(&self, buf: &mut [u8], offset: u64) -> Result<()> { ... }
    fn seek_read_buf(
        &self,
        buf: BorrowedCursor<'_, u8>,
        offset: u64,
    ) -> Result<()> { ... }
    fn seek_write_all(&self, buf: &[u8], offset: u64) -> Result<()> { ... }
}

Available on Windows only.

Windows-specific extensions to fs::File.

Required Methods

fn seek_read(&self, buf: &mut [u8], offset: u64) -> Result<usize>

Seeks to a given position and reads a number of bytes.

Returns the number of bytes read.

The offset is relative to the start of the file and thus independent from the current cursor. The current cursor is affected by this function, it is set to the end of the read.

Reading beyond the end of the file will always return with a length of 0.

Note that similar to File::read, it is not an error to return with a short read. When returning from such a short read, the file pointer is still updated.

Examples

use std::io;
use std::fs::File;
use std::os::windows::prelude::*;

fn main() -> io::Result<()> {
    let mut file = File::open("foo.txt")?;
    let mut buffer = [0; 10];

    // Read 10 bytes, starting 72 bytes from the
    // start of the file.
    file.seek_read(&mut buffer[..], 72)?;
    Ok(())
}

fn seek_write(&self, buf: &[u8], offset: u64) -> Result<usize>

Seeks to a given position and writes a number of bytes.

Returns the number of bytes written.

The offset is relative to the start of the file and thus independent from the current cursor. The current cursor is affected by this function, it is set to the end of the write.

When writing beyond the end of the file, the file is appropriately extended and the intermediate bytes are set to zero.

Note that similar to File::write, it is not an error to return a short write. When returning from such a short write, the file pointer is still updated.

Examples

use std::fs::File;
use std::os::windows::prelude::*;

fn main() -> std::io::Result<()> {
    let mut buffer = File::create("foo.txt")?;

    // Write a byte string starting 72 bytes from
    // the start of the file.
    buffer.seek_write(b"some bytes", 72)?;
    Ok(())
}

Provided Methods

fn seek_read_exact(&self, buf: &mut [u8], offset: u64) -> Result<()>

🔬This is a nightly-only experimental API. (seek_read_exact_seek_write_all #162868)

Seeks to a given position and reads the exact number of bytes required to fill buf.

The offset is relative to the start of the file and thus independent from the current cursor. The current cursor is affected by this function, it is set to the end of the read.

Similar to io::Read::read_exact but uses seek_read instead of read.

Errors

If this function encounters an error of the kind io::ErrorKind::Interrupted then the error is ignored and the operation will continue.

If this function encounters an “end of file” before completely filling the buffer, it returns an error of the kind io::ErrorKind::UnexpectedEof. The contents of buf are unspecified in this case.

If any other read error is encountered then this function immediately returns. The contents of buf are unspecified in this case.

If this function returns an error, it is unspecified how many bytes it has read, but it will never read more than would be necessary to completely fill the buffer.

Examples

#![feature(seek_read_exact_seek_write_all)]

use std::io;
use std::fs::File;
use std::os::windows::prelude::*;

fn main() -> io::Result<()> {
    let mut file = File::open("foo.txt")?;
    let mut buffer = [0; 10];

    // Read 10 bytes, starting 72 bytes from the
    // start of the file.
    file.seek_read_exact(&mut buffer[..], 72)?;
    Ok(())
}

fn seek_read_buf(&self, buf: BorrowedCursor<'_, u8>, offset: u64) -> Result<()>

🔬This is a nightly-only experimental API. (read_buf_at #140771)

Seeks to a given position and reads some bytes into the buffer.

This is equivalent to the seek_read method, except that it is passed a BorrowedCursor rather than &mut [u8] to allow use with uninitialized buffers. The new data will be appended to any existing contents of buf.

Reading beyond the end of the file will always succeed without reading any bytes.

Examples

#![feature(core_io_borrowed_buf)]
#![feature(read_buf_at)]

use std::io;
use std::io::BorrowedBuf;
use std::fs::File;
use std::mem::MaybeUninit;
use std::os::windows::prelude::*;

fn main() -> io::Result<()> {
    let mut file = File::open("pi.txt")?;

    // Read some bytes starting from offset 2
    let mut buf: [MaybeUninit<u8>; 10] = [MaybeUninit::uninit(); 10];
    let mut buf = BorrowedBuf::from(buf.as_mut_slice());
    file.seek_read_buf(buf.unfilled(), 2)?;

    assert!(buf.filled().starts_with(b"1"));

    Ok(())
}

fn seek_write_all(&self, buf: &[u8], offset: u64) -> Result<()>

🔬This is a nightly-only experimental API. (seek_read_exact_seek_write_all #162868)

Seeks to a given position and attempts to write an entire buffer.

The offset is relative to the start of the file and thus independent from the current cursor. The current cursor is affected by this function, it is set to the end of the write.

This method will continuously call seek_write until there is no more data to be written or an error of non-io::ErrorKind::Interrupted kind is returned. This method will not return until the entire buffer has been successfully written or such an error occurs. The first error that is not of io::ErrorKind::Interrupted kind generated from this method will be returned.

Errors

This function will return the first error of non-io::ErrorKind::Interrupted kind that seek_write returns.

Examples

#![feature(seek_read_exact_seek_write_all)]

use std::fs::File;
use std::os::windows::prelude::*;

fn main() -> std::io::Result<()> {
    let mut buffer = File::create("foo.txt")?;

    // Write a byte string starting 72 bytes from
    // the start of the file.
    buffer.seek_write_all(b"some bytes", 72)?;
    Ok(())
}

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl FileExt for File