Struct bonsaidb_files::direct::File

pub struct File<Database: Clone, Config: FileConfig = BonsaiFiles> { /* private fields */ }

A handle to a file stored in a database.

Implementations

impl<Database, Config> File<Blocking<Database>, Config>

where Database: Connection + Clone, Config: FileConfig,

pub fn children(&self) -> Result<Vec<Self>, Error>

Return all direct descendants of this file. For example, consider this list of files:

• /top-level
• /top-level/sub-level
• /top-level/sub-level/file.txt

If this instance were /top-level, this function would return sub-level but not sub-level/file.txt.

pub fn move_to(&mut self, new_path: &str) -> Result<(), Error>

Moves this file to a new location. If new_path ends with a /, the file will be moved to that path with its name preserved. Otherwise, the file will be renamed as part of the move.

For example, moving /a/file.txt to /b/ will result in the full path being /b/file.txt. Moving /a/file.txt to /b/new-name.txt will result in the full path being /b/new-name.txt.

pub fn rename(&mut self, new_name: String) -> Result<(), Error>

Renames this file to the new name.

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

Deletes the file.

pub fn len(&mut self) -> Result<u64, Error>

Returns the length of the file.

pub fn is_empty(&mut self) -> Result<bool, Error>

Returns true if this file contains no data.

pub fn last_appended_at( &mut self ) -> Result<Option<TimestampAsNanoseconds>, Error>

Returns the timestamp of the last append to the file. This function returns 0 when the file is empty, even if the file was previously written to.

pub fn contents(&self) -> Result<Contents<Blocking<Database>, Config>, Error>

Returns the contents of the file, which allows random and buffered access to the file stored in the database.

The default buffer size is ten times Config::BLOCK_SIZE.

pub fn truncate(&self, new_length: u64, from: Truncate) -> Result<(), Error>

Truncates the file, removing data from either the start or end of the file until the file is within Config::BLOCK_SIZE of new_length. Truncating currently will not split a block, causing the resulting length to not always match the length requested.

If new_length is 0 and this call succeeds, the file’s length is guaranteed to be 0.

pub fn append(&self, data: &[u8]) -> Result<(), Error>

Appends data to the end of the file. The data will be split into chunks no larger than Config::BLOCK_SIZE when stored in the database.

pub fn append_buffered(&mut self) -> BufferedAppend<'_, Config, Database>

Returns a writer that will buffer writes to the end of the file.

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

Stores changes to the metadata of this document.

impl<Database, Config> File<Async<Database>, Config>

where Database: AsyncConnection + Clone, Config: FileConfig,

pub async fn children(&self) -> Result<Vec<Self>, Error>

Return all direct descendants of this file. For example, consider this list of files:

• /top-level
• /top-level/sub-level
• /top-level/sub-level/file.txt

If this instance were /top-level, this function would return sub-level but not sub-level/file.txt.

pub async fn move_to(&mut self, new_path: &str) -> Result<(), Error>

Moves this file to a new location. If new_path ends with a /, the file will be moved to that path with its name preserved. Otherwise, the file will be renamed as part of the move.

For example, moving /a/file.txt to /b/ will result in the full path being /b/file.txt. Moving /a/file.txt to /b/new-name.txt will result in the full path being /b/new-name.txt.

pub async fn rename(&mut self, new_name: String) -> Result<(), Error>

Renames this file to the new name.

pub async fn delete(&self) -> Result<(), Error>

Deletes the file.

pub async fn len(&mut self) -> Result<u64, Error>

Returns the length of the file.

pub async fn is_empty(&mut self) -> Result<bool, Error>

Returns true if this file contains no data.

pub async fn last_appended_at( &mut self ) -> Result<Option<TimestampAsNanoseconds>, Error>

Returns the timestamp of the last append to the file. This function returns 0 when the file is empty, even if the file was previously written to.

pub async fn contents(&self) -> Result<Contents<Async<Database>, Config>, Error>

Returns the contents of the file, which allows random and buffered access to the file stored in the database.

The default buffer size is ten times Config::BLOCK_SIZE.

pub async fn truncate( &self, new_length: u64, from: Truncate ) -> Result<(), Error>

Truncates the file, removing data from either the start or end of the file until the file is within Config::BLOCK_SIZE of new_length. Truncating currently will not split a block, causing the resulting length to not always match the length requested.

If new_length is 0 and this call succeeds, the file’s length is guaranteed to be 0.

pub async fn append(&self, data: &[u8]) -> Result<(), Error>

Appends data to the end of the file. The data will be split into chunks no larger than Config::BLOCK_SIZE when stored in the database.

pub fn append_buffered(&mut self) -> AsyncBufferedAppend<'_, Config, Database>

Returns a writer that will buffer writes to the end of the file.

pub async fn update_metadata(&mut self) -> Result<(), Error>

Stores changes to the metadata of this document.

impl<Database, Config> File<Database, Config>

where Database: Clone, Config: FileConfig,

pub fn id(&self) -> u32

Returns the unique id of this file. The file id is only unique within a single database and FileConfig.

pub fn containing_path(&self) -> &str

Returns the path containing this file. For example, if the full path to the file is /some-path/file.txt, this function will return /some-path/.

pub fn name(&self) -> &str

Returns the name of this file.

pub fn path(&self) -> String

Returns the absolute path of this file.

pub fn created_at(&self) -> TimestampAsNanoseconds

Returns the timestamp the file was created at.

pub fn metadata(&self) -> &Config::Metadata

Returns the metadata for this file.

pub fn metadata_mut(&mut self) -> &mut Config::Metadata

Returns mutable access metadata for this file. Modifying the metadata will not update it in the database. Be sure to call update_metadata() or another operation that persists the file.

Trait Implementations

impl<Database: Clone, Config: FileConfig> Clone for File<Database, Config>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Database: Clone, Config: FileConfig> Debug for File<Database, Config>

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

Formats the value using the given formatter.

impl<Database, Config> PartialEq for File<Database, Config>

where Database: Clone, Config: FileConfig,

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

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

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.