Struct cfile_rs::CFile

pub struct CFile {
    pub path: CString,
    // some fields omitted
}

A wrapper around C's file type. Attempts to mimic the functionality if rust's std::fs::File while still allowing complete control of all I/O operations.

Fields

path: CString

Methods

impl CFile

fn open_random_access<P: AsRef<Path>>(path: P) -> Result<CFile, Error>

Attempts to open a file in random access mode (i.e. rb+). However, unlike rb+, if the file doesn't exist, it will be created. To avoid createion, simply call CFile::open(path, "rb+"), which will return an error if the file doesn't exist.

Failure

This function will return Err for a whole bunch of reasons, the errno id will be returned as an Error::Errno(u64). For more information on what that number actually means see

fn create_file<P: AsRef<Path>>(path: &P) -> Result<(), Error>

Attempts to create a file, and then immedietly close it. If the file already exists, this function will not do anything. If the file does exist, then it will be created with no and nothing more (it will be empty).

fn open<P: AsRef<Path>>(path: P, mode: &str) -> Result<CFile, Error>

Attempt to open the file with path p.

Examples

use cfile_rs;
use cfile_rs::*;
use cfile_rs::CFile;
use cfile_rs::TRUNCATAE_RANDOM_ACCESS_MODE;
use std::str::from_utf8;

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", TRUNCATAE_RANDOM_ACCESS_MODE).unwrap();

fn delete(self) -> Result<(), Error>

Deletes the file from the filesystem, and consumes the object.

Errors

On error Error::Errno(errno) is returned.

Examples

use cfile_rs;
use cfile_rs::*;
use cfile_rs::CFile;
use cfile_rs::UPDATE;
use std::str::from_utf8;

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", UPDATE).unwrap();
let _ = file.write_all("Howdy folks".as_bytes());   // Write some data!
let _ = file.delete();                              // The file is gone!

fn close(self) -> Result<(), Error>

Attempts to close the file. Consumes the file as well

Errors

On error Error::Errno(errno) is returned.

unsafe fn file<'a>(&'a mut self) -> &'a mut FILE

Returns the underlying file pointer as a reference. It is returned as a reference to, in theory, prevent it from being used after the file is closed.

fn current_pos(&self) -> Result<u64, Error>

Returns the current position in the file.

Errors

On error Error::Errno(errno) is returned.

Trait Implementations

impl Write for CFile

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write all of the bytes in buf to the file.

Errors

If an error occurs during writing, Error::WriteError(bytes_written, errno) will be returned.

Examples

use cfile_rs;
use cfile_rs::*;
use cfile_rs::CFile;
use cfile_rs::TRUNCATAE_RANDOM_ACCESS_MODE;
use std::str::from_utf8;

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", TRUNCATAE_RANDOM_ACCESS_MODE).unwrap();
let _ = file.write_all("Howdy folks".as_bytes());   // Write some data!

fn write(&mut self, buf: &[u8]) -> Result<usize, Error>

Attempts to write all of the bytes in buf to the file.

Errors

If an error occurs during writing, Error::WriteError(bytes_written, errno) will be returned.

Examples

use cfile_rs;
use cfile_rs::*;
use cfile_rs::CFile;
use cfile_rs::TRUNCATAE_RANDOM_ACCESS_MODE;
use std::str::from_utf8;

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", TRUNCATAE_RANDOM_ACCESS_MODE).unwrap();
let _ = file.write("Howdy folks".as_bytes());   // Write some data!

fn flush(&mut self) -> Result<(), Error>

Flushes the underlying output stream, meaning it actually writes everything to the filesystem.

Examples

use cfile_rs;
use cfile_rs::SeekFrom;
use cfile_rs::CFile;
use cfile_rs::TRUNCATAE_RANDOM_ACCESS_MODE;
use cfile_rs::*;

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", TRUNCATAE_RANDOM_ACCESS_MODE).unwrap();
match file.write_all("Howdy folks!".as_bytes()) {
    Ok(()) => println!("Successfully wrote to the file!"),
    Err(err) => {
        println!("Encountered error: {}", err);
    }
};
let _ = file.flush();   // Upon this call, all data waiting in the output
                        // stream will be written to the file

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.

impl Read for CFile

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads the entire file starting from the current position, expanding buf as needed. On a successful read, this function will return Ok(bytes_read).

Errors

If an error occurs during reading, some varient of error will be returned.

Examples

use cfile_rs;
use cfile_rs::CFile;
use cfile_rs::TRUNCATAE_RANDOM_ACCESS_MODE;
use std::str::from_utf8;
use std::io::{ Seek, SeekFrom, Read, Write };

// Truncate random access mode will overwrite the old "data.txt" file if it exists.
let mut file = CFile::open("data.txt", TRUNCATAE_RANDOM_ACCESS_MODE).unwrap();
let _ = file.write_all("Howdy folks".as_bytes());   // Write some data!
let _ = file.seek(SeekFrom::Start(0));              // Move back to the beginning of the file
let mut buffer = cfile_rs::buffer(10);              // Create a buffer (a Vec<u8>) to read into
match file.read_to_end(&mut buffer) {               // Read the entire file, expanding our buffer as needed
    Ok(bytes_read) => {
        // It is a bad idea to do this unless you know it is valid utf8
        let as_str = from_utf8(&buffer[0..bytes_read]).unwrap();
        println!("Read '{}' from the file.", as_str);
    },
    Err(err) => {
        println!("Encountered error: {}", err);
    }
};

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Reads exactly the number of bytes required to fill buf.

Errors

If the end of the file is reached before buf is filled, Err(EndOfFile(bytes_read)) will be returned. The data that was read before that will still have been placed into buf.

Upon some other error, Err(Errno(errno)) will be returned.

Examples

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads exactly the number of bytes required to fill buf.

Errors

If the end of the file is reached before buf is filled, Err(EndOfFile(bytes_read)) will be returned. The data that was read before that will still have been placed into buf.

Upon some other error, Err(Errno(errno)) will be returned.

Examples

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an Iterator over its bytes.

fn chars(self) -> Chars<Self>

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an Iterator over chars.

fn chain<R>(self, next: R) -> Chain<Self, R> where R: Read

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl Seek for CFile

fn seek(&mut self, pos: SeekFrom) -> Result<u64, Error>

Changes the current position in the file using the SeekFrom enum.

To set relative to the beginning of the file (i.e. index is 0 + offset): SeekFrom::Start(offset) To set relative to the end of the file (i.e. index is file_lenth - 1 - offset): SeekFrom::End(offset) To set relative to the current position: SeekFrom::End(offset)

Errors

On error Error::Errno(errno) is returned.

impl Drop for CFile

fn drop(&mut self)

Ensures the file stream is closed before abandoning the data.