Struct same_file::Handle

source ·
pub struct Handle(/* private fields */);
Expand description

A handle to a file that can be tested for equality with other handles.

If two files are the same, then any two handles of those files will compare equal. If two files are not the same, then any two handles of those files will compare not-equal.

A handle consumes an open file resource as long as it exists.

Equality is determined by comparing inode numbers on Unix and a combination of identifier, volume serial, and file size on Windows. Note that it’s possible for comparing two handles to produce a false positive on some platforms. Namely, two handles can compare equal even if the two handles don’t point to the same file. Check the source for specific implementation details.

Implementations§

source§

impl Handle

source

pub fn from_path<P: AsRef<Path>>(p: P) -> Result<Handle>

Construct a handle from a path.

Note that the underlying File is opened in read-only mode on all platforms.

§Errors

This method will return an io::Error if the path cannot be opened, or the file’s metadata cannot be obtained. The most common reasons for this are: the path does not exist, or there were not enough permissions.

§Examples

Check that two paths are not the same file:

use same_file::Handle;

let source = Handle::from_path("./source")?;
let target = Handle::from_path("./target")?;
assert_ne!(source, target, "The files are the same.");
source

pub fn from_file(file: File) -> Result<Handle>

Construct a handle from a file.

§Errors

This method will return an io::Error if the metadata for the given File cannot be obtained.

§Examples

Check that two files are not in fact the same file:

use same_file::Handle;

let source = File::open("./source")?;
let target = File::open("./target")?;

assert_ne!(
    Handle::from_file(source)?,
    Handle::from_file(target)?,
    "The files are the same."
);
source

pub fn stdin() -> Result<Handle>

Construct a handle from stdin.

§Errors

This method will return an io::Error if stdin cannot be opened due to any I/O-related reason.

§Examples
use same_file::Handle;

let stdin = Handle::stdin()?;
let stdout = Handle::stdout()?;
let stderr = Handle::stderr()?;

if stdin == stdout {
    println!("stdin == stdout");
}
if stdin == stderr {
    println!("stdin == stderr");
}
if stdout == stderr {
    println!("stdout == stderr");
}

The output differs depending on the platform.

On Linux:

$ ./example
stdin == stdout
stdin == stderr
stdout == stderr
$ ./example > result
$ cat result
stdin == stderr
$ ./example > result 2>&1
$ cat result
stdout == stderr

Windows:

> example
> example > result 2>&1
> type result
stdout == stderr
source

pub fn stdout() -> Result<Handle>

Construct a handle from stdout.

§Errors

This method will return an io::Error if stdout cannot be opened due to any I/O-related reason.

§Examples

See the example for stdin().

source

pub fn stderr() -> Result<Handle>

Construct a handle from stderr.

§Errors

This method will return an io::Error if stderr cannot be opened due to any I/O-related reason.

§Examples

See the example for stdin().

source

pub fn as_file(&self) -> &File

Return a reference to the underlying file.

§Examples

Ensure that the target file is not the same as the source one, and copy the data to it:

use std::io::prelude::*;
use std::io::Write;
use std::fs::File;
use same_file::Handle;

let source = File::open("source")?;
let target = File::create("target")?;

let source_handle = Handle::from_file(source)?;
let mut target_handle = Handle::from_file(target)?;
assert_ne!(source_handle, target_handle, "The files are the same.");

let mut source = source_handle.as_file();
let target = target_handle.as_file_mut();

let mut buffer = Vec::new();
// data copy is simplified for the purposes of the example
source.read_to_end(&mut buffer)?;
target.write_all(&buffer)?;
source

pub fn as_file_mut(&mut self) -> &mut File

Return a mutable reference to the underlying file.

§Examples

See the example for as_file().

source

pub fn dev(&self) -> u64

Return the underlying device number of this handle.

Note that this only works on unix platforms.

source

pub fn ino(&self) -> u64

Return the underlying inode number of this handle.

Note that this only works on unix platforms.

Trait Implementations§

source§

impl AsRawFd for Handle

source§

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

impl Debug for Handle

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Hash for Handle

source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl IntoRawFd for Handle

source§

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor. Read more
source§

impl PartialEq for Handle

source§

fn eq(&self, other: &Handle) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Eq for Handle

source§

impl StructuralPartialEq for Handle

Auto Trait Implementations§

§

impl Freeze for Handle

§

impl RefUnwindSafe for Handle

§

impl Send for Handle

§

impl Sync for Handle

§

impl Unpin for Handle

§

impl UnwindSafe for Handle

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.