### and Method Examples Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates the behavior of the `and` method with different combinations of `Ok` and `Err` variants. ```rust let x: Result = Ok(2); let y: Result<&str, &str> = Err("late error"); assert_eq!(x.and(y), Err("late error")); ``` ```rust let x: Result = Err("early error"); let y: Result<&str, &str> = Ok("foo"); assert_eq!(x.and(y), Err("early error")); ``` ```rust let x: Result = Err("not a 2"); let y: Result<&str, &str> = Err("late error"); assert_eq!(x.and(y), Err("not a 2")); ``` ```rust let x: Result = Ok(2); let y: Result<&str, &str> = Ok("different result type"); assert_eq!(x.and(y), Ok("different result type")); ``` -------------------------------- ### Tag::new Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Creates a new, empty FLAC tag. This is the starting point for building a tag from scratch. ```APIDOC ## Tag::new ### Description Creates a new FLAC tag with no blocks. ### Method `Tag::new()` ### Returns A new `Tag` instance. ``` -------------------------------- ### Create a new FLAC tag Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search= Initializes a new Tag instance with no blocks. Use this to start building a tag from scratch. ```rust use metaflac::Tag; let mut tag = Tag::new(); ``` -------------------------------- ### Handling File Metadata Operations with `and_then` Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Illustrates using `and_then` to chain fallible file system operations, such as retrieving metadata and then its modification time. This example shows how to handle potential errors like file not found. ```rust use std::{io::ErrorKind, path::Path}; // Note: on Windows "/" maps to "C:\" let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); assert!(root_modified_time.is_ok()); let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified()); assert!(should_fail.is_err()); assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound); ``` -------------------------------- ### Handling File Metadata Operations Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Shows how to use `and_then` to chain fallible operations like getting file metadata. It handles both successful retrieval and cases where the path is invalid. ```rust use std::{io::ErrorKind, path::Path}; // Note: on Windows "/" maps to "C:\\" let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); assert!(root_modified_time.is_ok()); let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified()); assert!(should_fail.is_err()); assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound); ``` -------------------------------- ### into_ok for Infallible Results Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Example of `into_ok` used with a function that returns a `Result` with an infallible error type (`!`). ```rust fn only_good_news() -> Result { Ok("this is fine".into()) } let s: String = only_good_news().into_ok(); println!("{s}"); ``` -------------------------------- ### Sum with Iterator of Results Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Illustrates summing integers from a vector using `sum()`. The example shows how `sum()` returns `Ok` for a valid sum and `Err` if a negative element is encountered, as defined by the mapping function. ```rust let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) }; let v = vec![1, 2]; let res: Result = v.iter().map(f).sum(); assert_eq!(res, Ok(3)); let v = vec![1, -2]; let res: Result = v.iter().map(f).sum(); assert_eq!(res, Err("Negative element found")); ``` -------------------------------- ### Get StreamInfo from a Tag Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Demonstrates checking for the presence of a StreamInfo block in a Tag, first when it's absent and then after it has been set. ```rust use metaflac::Tag; use metaflac::block::StreamInfo; let mut tag = Tag::new(); assert!(tag.get_streaminfo().is_none()); tag.set_streaminfo(StreamInfo::new()); assert!(tag.get_streaminfo().is_some()); ``` -------------------------------- ### Get Mutable Reference to Vorbis Comments Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Illustrates how to get a mutable reference to the Vorbis comment block, adding one if it doesn't exist, and then modifying its contents. ```rust use metaflac::Tag; let mut tag = Tag::new(); assert!(tag.vorbis_comments().is_none()); let key = "key".to_owned(); let value1 = "value1".to_owned(); let value2 = "value2".to_owned(); tag.vorbis_comments_mut().comments.insert(key.clone(), vec!(value1.clone(), value2.clone())); assert!(tag.vorbis_comments().is_some()); assert!(tag.vorbis_comments().unwrap().comments.get(&key).is_some()); ``` -------------------------------- ### type_id Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Gets the TypeId of self. ```APIDOC ## fn type_id(&self) -> TypeId ### Description Gets the `TypeId` of `self`. ### Returns A `TypeId` representing the type of `self`. ``` -------------------------------- ### Using expect for Environment Variable Retrieval Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=u32+-%3E+bool Demonstrates a recommended style for using expect to retrieve environment variables, providing a clear message about why the variable is expected to be set. ```Rust let path = std::env::var("IMPORTANT_PATH") .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); ``` -------------------------------- ### Application::new() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a new `Application` instance with an empty ID and data. ```rust pub fn new() -> Application ``` -------------------------------- ### Get Block Type Source: https://docs.rs/metaflac/0.2.8/metaflac/block/enum.Block.html?search= Returns the corresponding block type byte for the given Block. ```rust pub fn block_type(&self) -> BlockType ``` -------------------------------- ### New CueSheetTrack Initialization Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheetTrack.html Creates a new CueSheetTrack instance. This function initializes a track as audio type, without pre-emphasis, and with default zero/empty values for its fields. ```rust pub fn new() -> CueSheetTrack ``` -------------------------------- ### Error Cause (Deprecated) Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Error.html Deprecated method to get the underlying cause of the error. Replaced by Error::source. ```rust fn cause(&self) -> Option<&dyn Error> ``` -------------------------------- ### New CueSheet for CD Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheet.html Returns a new CueSheet instance initialized for a CD with default/empty values. Useful for creating a new cuesheet from scratch. ```rust pub fn new() -> CueSheet ``` -------------------------------- ### into_err for Infallible Results Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Example of `into_err` used with a function that returns a `Result` with an infallible success type (`!`). ```rust fn only_bad_news() -> Result { Err("Oops, it failed".into()) } let error: String = only_bad_news().into_err(); println!("{error}"); ``` -------------------------------- ### Create and Remove Padding Blocks Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Demonstrates how to create a new Tag, add Padding blocks, and then remove all blocks of a specific type. ```rust use metaflac::{Tag, Block, BlockType}; let mut tag = Tag::new(); tag.push_block(Block::Padding(10)); tag.push_block(Block::Unknown((20, Vec::new()))); tag.push_block(Block::Padding(15)); tag.remove_blocks(BlockType::Padding); assert_eq!(tag.blocks().count(), 1); ``` -------------------------------- ### StreamInfo::new Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.StreamInfo.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a new `StreamInfo` instance with default zero/empty values. ```APIDOC ## fn new() -> StreamInfo Returns a new `StreamInfo` with zero/empty values. ``` -------------------------------- ### Get StreamInfo Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search= Retrieves a reference to the first streaminfo block found in the tag. Returns `None` if no streaminfo blocks are present. ```APIDOC ## Get StreamInfo ### Description Returns a reference to the first streaminfo block. Returns `None` if no streaminfo blocks are found. ### Method `get_streaminfo` ### Returns - `Option<&StreamInfo>`: A reference to the `StreamInfo` block, or `None`. ### Example ```rust use metaflac::Tag; use metaflac::block::StreamInfo; let mut tag = Tag::new(); assert!(tag.get_streaminfo().is_none()); tag.set_streaminfo(StreamInfo::new()); assert!(tag.get_streaminfo().is_some()); ``` ``` -------------------------------- ### PartialEq Implementation for Application Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Defines equality comparison for `Application` structs. ```rust fn eq(&self, other: &Application) -> bool ``` ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### Get Vorbis Comment Values by Key Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Demonstrates how to retrieve all string values associated with a specific Vorbis comment key. ```rust use metaflac::Tag; let mut tag = Tag::new(); let key = "key".to_owned(); let value1 = "value1".to_owned(); let value2 = "value2".to_owned(); tag.set_vorbis(&key, vec!(&value1, &value2)); assert_eq!(tag.get_vorbis(&key).unwrap().collect::>(), &[&value1, &value2]); ``` -------------------------------- ### Basic Usage of unwrap Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates the basic usage of the `unwrap` method on a `Result` type when the value is `Ok`. ```rust let x: Result = Ok(2); assert_eq!(x.unwrap(), 2); ``` -------------------------------- ### Error Description (Deprecated) Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Error.html Deprecated method to get a string description of the error. Use the Display impl or to_string() instead. ```rust fn description(&self) -> &str ``` -------------------------------- ### Application::clone() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html Creates a duplicate of an existing `Application` instance. ```rust fn clone(&self) -> Application ``` -------------------------------- ### Product with Iterator of Results Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Demonstrates multiplying numbers from a vector of strings using `product()`. It shows how `product()` returns `Ok` if all elements parse successfully, and `Err` if any element fails to parse. ```rust let nums = vec!["5", "10", "1", "2"]; let total: Result = nums.iter().map(|w| w.parse::()).product(); assert_eq!(total, Ok(100)); let nums = vec!["5", "10", "one", "2"]; let total: Result = nums.iter().map(|w| w.parse::()).product(); assert!(total.is_err()); ``` -------------------------------- ### Enumerate Iterator Method (Unstable) Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Creates an iterator that yields pairs of the current iteration count (starting from 0) and the element. This is an unstable feature. ```rust fn enumerate(self) -> Enumerate where Self: Sized, ``` -------------------------------- ### Unsafe Example: Calling `unwrap_err_unchecked` on Ok Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E This snippet explicitly shows the unsafe usage of `unwrap_err_unchecked` on an `Ok` variant, highlighting that this leads to undefined behavior. ```rust let x: Result = Ok(2); unsafe { x.unwrap_err_unchecked() }; // Undefined behavior! ``` -------------------------------- ### PartialEq Implementation for CueSheet Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheet.html?search= Enables comparison of CueSheet instances for equality. ```rust fn eq(&self, other: &CueSheet) -> bool ``` ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### Unsafe Example: Calling `unwrap_unchecked` on Err Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E This snippet explicitly shows the unsafe usage of `unwrap_unchecked` on an `Err` variant, highlighting that this leads to undefined behavior. ```rust let x: Result = Err("emergency failure"); unsafe { x.unwrap_unchecked() }; // Undefined behavior! ``` -------------------------------- ### into_ok Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Returns the contained Ok value, but never panics. This is an experimental API. ```APIDOC ## pub const fn into_ok(self) -> T ### Description Returns the contained `Ok` value, but never panics. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur. ### Parameters - `self`: The Result instance. ### Returns The contained `Ok` value. ### Examples ```rust fn only_good_news() -> Result { Ok("this is fine".into()) } let s: String = only_good_news().into_ok(); println!("{s}"); // Output: this is fine ``` ``` -------------------------------- ### PartialEq Implementation for CueSheetTrack Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheetTrack.html Defines how to test two CueSheetTrack instances for equality. ```rust fn eq(&self, other: &CueSheetTrack) -> bool ``` ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### Getting a Reference to the Result's Value Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Use `as_ref()` to convert a `&Result` into a `Result<&T, &E>`, allowing access to the contained values without consuming the original Result. ```rust let x: Result = Ok(2); assert_eq!(x.as_ref(), Ok(&2)); let x: Result = Err("Error"); assert_eq!(x.as_ref(), Err(&"Error")); ``` -------------------------------- ### Getting a Mutable Reference to the Result's Value Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Use `as_mut()` to convert a `&mut Result` into a `Result<&mut T, &mut E>`, enabling in-place modification of the contained values. ```rust fn mutate(r: &mut Result) { match r.as_mut() { Ok(v) => *v = 42, Err(e) => *e = 0, } } let mut x: Result = Ok(2); mutate(&mut x); assert_eq!(x.unwrap(), 42); let mut x: Result = Err(13); mutate(&mut x); assert_eq!(x.unwrap_err(), 0); ``` -------------------------------- ### take Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ```APIDOC ## fn take(self, n: usize) -> Take ### Description Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ### Parameters - `n`: The maximum number of elements to yield. ### Returns A `Take` iterator. ``` -------------------------------- ### Unwrapping Result with expect (Panics on Err) Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Use expect to get the Ok value, providing a custom panic message if the Result is an Err. This method is discouraged in favor of safer error handling. ```Rust let x: Result = Err("emergency failure"); x.expect("Testing expect"); // panics with `Testing expect: emergency failure` ``` ```Rust let path = std::env::var("IMPORTANT_PATH") .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); ``` -------------------------------- ### Default Implementation for Application Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Provides a default value for the `Application` struct. ```rust fn default() -> Self ``` -------------------------------- ### New Picture Instance Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Picture.html Creates a new `Picture` instance with default or zeroed values. Useful for initializing a picture block before populating it. ```rust pub fn new() -> Picture ``` -------------------------------- ### Unwrapping Result with unwrap Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Use `unwrap` to get the `Ok` value, panicking if the Result is `Err`. This method is discouraged due to its potential to abort the program. Prefer `?`, pattern matching, or `unwrap_or` variants. ```rust let x: Result = Err("emergency failure"); x.unwrap(); // panics ``` -------------------------------- ### Application::eq() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html Tests if two `Application` instances are equal. ```rust fn eq(&self, other: &Application) -> bool ``` -------------------------------- ### Clone Implementation for Application Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Provides methods for cloning and clone-from operations on the `Application` struct. ```rust fn clone(&self) -> Application ``` ```rust fn clone_from(&mut self, source: &Self) ``` -------------------------------- ### into_ok Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Returns the contained `Ok` value, but never panics. This is an experimental API. ```APIDOC ## into_ok ### Description Returns the contained `Ok` value, but never panics. This is a nightly-only experimental API. ### Method `into_ok` ### Parameters None ### Request Example ```rust fn only_good_news() -> Result { Ok("this is fine".into()) } let s: String = only_good_news().into_ok(); println!("{s}"); ``` ### Response #### Success Response Returns the `Ok` value. ``` -------------------------------- ### PartialEq and Eq Implementations for Picture Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Picture.html?search=std%3A%3Avec Enables comparison of Picture instances for equality. ```rust fn eq(&self, other: &Picture) -> bool ``` ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### try_from Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search= Performs the conversion from one type to another, returning a Result. ```APIDOC ## try_from ### Description Performs the conversion from one type to another. This method is part of the `TryFrom` trait. ### Method N/A (Method on a trait implementation) ### Parameters - **value** (*U*) - Required - The value to convert. ### Request Example N/A ### Response #### Success Response - **T** (Type) - The successfully converted value. #### Error Response - **Error** (>::Error) - The error type returned if conversion fails. ``` -------------------------------- ### Application Struct Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=std%3A%3Avec Represents an APPLICATION block in a FLAC file, containing a registered application ID and associated data. ```APIDOC ## Struct Application ### Description A structure representing an APPLICATION block. ### Fields * **id** (`Vec`) - Required - Registered application ID. * **data** (`Vec`) - Required - Application data. ### Methods #### `new()` Returns a new `Application` with a zero id and no data. #### `from_bytes(bytes: &[u8]) -> Application` Parses the bytes as an application block. #### `to_bytes(&self) -> Vec` Returns a vector representation of the application block suitable for writing to a file. ``` -------------------------------- ### Set StreamInfo for a Tag Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Illustrates how to set a StreamInfo block for a Tag and then confirm that a StreamInfo block is now present. ```rust use metaflac::Tag; use metaflac::block::StreamInfo; let mut tag = Tag::new(); tag.set_streaminfo(StreamInfo::new()); assert!(tag.get_streaminfo().is_some()); ``` -------------------------------- ### StructuralPartialEq Implementation for CueSheet Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheet.html?search=std%3A%3Avec Indicates that CueSheet supports structural partial equality comparisons. ```rust impl StructuralPartialEq for CueSheet ``` -------------------------------- ### StreamInfo::new() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.StreamInfo.html?search=std%3A%3Avec Creates a new StreamInfo instance with default zero/empty values. ```rust pub fn new() -> StreamInfo ``` -------------------------------- ### Add and Count Picture Blocks Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Demonstrates how to add a picture block to a Tag and then count the total number of pictures. ```rust use metaflac::Tag; use metaflac::block::PictureType::CoverFront; let mut tag = Tag::new(); assert_eq!(tag.pictures().count(), 0); tag.add_picture("image/jpeg", CoverFront, vec!(0xFF)); assert_eq!(tag.pictures().count(), 1); ``` -------------------------------- ### TryInto::try_into() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html Attempts to convert an `Application` instance into another type. Returns `Result` indicating success or failure. ```rust fn try_into(self) -> Result>::Error> ``` -------------------------------- ### PartialEq and Eq Implementations for SeekPoint Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekPoint.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Enables comparison of SeekPoint instances for equality. ```rust fn eq(&self, other: &SeekPoint) -> bool ``` ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### Application::from_bytes() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Parses a byte slice into an `Application` block. ```rust pub fn from_bytes(bytes: &[u8]) -> Application ``` -------------------------------- ### SeekPoint::new() Constructor Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekPoint.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a new SeekPoint with all fields initialized to zero. ```rust pub fn new() -> SeekPoint ``` -------------------------------- ### Debug Implementation for Application Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Allows the `Application` struct to be formatted for debugging output. ```rust fn fmt(&self, out: &mut Formatter<'_>) -> Result ``` -------------------------------- ### SeekPoint::new Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekPoint.html Creates a new SeekPoint with all zero values. ```APIDOC ## SeekPoint::new ### Description Returns a new `SeekPoint` with all zero values. ### Signature ```rust pub fn new() -> SeekPoint ``` ``` -------------------------------- ### and with Ok and Err Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Demonstrates the `and` method, which returns the second `Result` if the first is `Ok`, otherwise returns the `Err` from the first `Result`. Arguments are eagerly evaluated. ```Rust let x: Result = Ok(2); let y: Result<&str, &str> = Err("late error"); assert_eq!(x.and(y), Err("late error")); let x: Result = Err("early error"); let y: Result<&str, &str> = Ok("foo"); assert_eq!(x.and(y), Err("early error")); let x: Result = Err("not a 2"); let y: Result<&str, &str> = Err("late error"); assert_eq!(x.and(y), Err("not a 2")); let x: Result = Ok(2); let y: Result<&str, &str> = Ok("different result type"); assert_eq!(x.and(y), Ok("different result type")); ``` -------------------------------- ### VorbisComment::new Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.VorbisComment.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a new VorbisComment instance with an empty vendor string and no comments. ```APIDOC ## VorbisComment::new ### Description Returns a new `VorbisComment` with an empty vendor string and no comments. ### Returns - `VorbisComment`: A new, empty VorbisComment instance. ``` -------------------------------- ### and_then for Chaining Operations Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Illustrates the use of `and_then` for chaining operations that return `Result`. ```rust let x: Result = Ok(2); let y: Result<&str, &str> = Err("late error"); assert_eq!(x.and_then(|v| if v == 2 { Ok("foo") } else { Err("bar") }), Ok("foo")); ``` -------------------------------- ### TryFrom Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html Enables fallible type conversions from one type to another. It's the inverse of TryInto. ```APIDOC ## impl TryFrom for T where U: Into ### Associated Types #### type Error = Infallible - Description: The type returned in the event of a conversion error. 'Infallible' indicates that this conversion cannot fail. ### Methods #### fn try_from(value: U) -> Result>::Error> - Description: Performs the conversion from type U to type T. Returns a Result indicating success or failure. ``` -------------------------------- ### New CueSheetTrackIndex Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheetTrackIndex.html Creates a new CueSheetTrackIndex initialized with all zero values. ```rust pub fn new() -> CueSheetTrackIndex ``` -------------------------------- ### TryFrom::try_from() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html Attempts to convert a value into an `Application` instance. Returns `Result` indicating success or failure. ```rust fn try_from(value: U) -> Result>::Error> ``` -------------------------------- ### Add and Verify a Picture to a Tag Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Demonstrates how to add a JPEG picture with front cover type and specific data to a Tag, and then verify its properties. ```rust use metaflac::Tag; use metaflac::block::PictureType::CoverFront; let mut tag = Tag::new(); assert_eq!(tag.pictures().count(), 0); tag.add_picture("image/jpeg", CoverFront, vec!(0xFF)); let picture = tag.pictures().next().unwrap(); assert_eq!(&picture.mime_type, "image/jpeg"); assert_eq!(picture.picture_type, CoverFront); assert_eq!(&picture.data, &vec!(0xFF)); ``` -------------------------------- ### Providing an Alternative Result with `or` Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Shows how `or` is used to return the `Ok` value of the first `Result` if it's `Ok`, otherwise it returns the second `Result`. Arguments to `or` are eagerly evaluated. ```rust let x: Result = Ok(2); let y: Result = Err("late error"); assert_eq!(x.or(y), Ok(2)); let x: Result = Err("early error"); let y: Result = Ok(2); assert_eq!(x.or(y), Ok(2)); let x: Result = Err("not a 2"); let y: Result = Err("late error"); assert_eq!(x.or(y), Err("late error")); let x: Result = Ok(2); let y: Result = Ok(100); assert_eq!(x.or(y), Ok(2)); ``` -------------------------------- ### Clone Implementation for CueSheetTrack Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheetTrack.html Provides a method to create a duplicate of a CueSheetTrack instance. ```rust fn clone(&self) -> CueSheetTrack ``` -------------------------------- ### product Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Iterates over the entire iterator, multiplying all the elements. The element type must implement the `Product` trait. ```APIDOC ## fn product

(self) -> P where Self: Sized, P: Product, ### Description Iterates over the entire iterator, multiplying all the elements. ### Type Parameters - `P`: The type of the product, which must implement `Product` for the iterator's item type. ### Returns - The product of all elements in the iterator. ``` -------------------------------- ### step_by() Method Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates an iterator that yields elements at a specified step interval. ```rust fn step_by(self, step: usize) -> StepBy ``` -------------------------------- ### partition Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Consumes an iterator, creating two collections based on a predicate. ```APIDOC ## fn partition(self, f: F) -> (B, B) ### Description Consumes an iterator, creating two collections from it. ### Parameters - `f`: A closure that takes a reference to an item and returns a boolean indicating which partition it belongs to. ### Constraints `B` must implement `Default` and `Extend`. ### Returns A tuple containing two collections of type `B`. ``` -------------------------------- ### Application::ne() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html Tests if two `Application` instances are not equal. ```rust fn ne(&self, other: &Rhs) -> bool ``` -------------------------------- ### From and Into Implementations for Generic Types Source: https://docs.rs/metaflac/0.2.8/metaflac/block/enum.BlockType.html Facilitates conversions between types where a From for U or Into for T implementation exists. ```rust fn from(t: T) -> T ``` ```rust fn into(self) -> U ``` -------------------------------- ### PartialEq Implementation for Picture Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Picture.html Enables comparison of two `Picture` instances for equality. Two pictures are considered equal if all their fields match. ```rust fn eq(&self, other: &Picture) -> bool ``` -------------------------------- ### product Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html Iterates over the entire iterator, multiplying all the elements. ```APIDOC ## fn product

(self) -> P ### Description Iterates over the entire iterator, multiplying all the elements. ### Type Parameters - `P`: The type to store the product in, must implement `Product` for the iterator's item type. ### Returns The product of the elements in the iterator. ``` -------------------------------- ### product Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Iterates over the entire iterator, multiplying all the elements. ```APIDOC ## fn product

(self) -> P where Self: Sized, P: Product, ### Description Iterates over the entire iterator, multiplying all the elements. ### Method `product` ### Return Value Returns the product of all elements in the iterator. ``` -------------------------------- ### Application::to_bytes() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Application.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Converts an `Application` block into a byte vector suitable for file writing. ```rust pub fn to_bytes(&self) -> Vec ``` -------------------------------- ### Iterating over Result Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Demonstrates how to convert a Result into an iterator. An Ok value yields one item, while an Err value yields no items. ```rust let x: Result = Ok(5); let v: Vec = x.into_iter().collect(); assert_eq!(v, [5]); ``` ```rust let x: Result = Err("nothing!"); let v: Vec = x.into_iter().collect(); assert_eq!(v, []); ``` -------------------------------- ### CueSheet Struct Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.CueSheet.html?search=std%3A%3Avec Represents a CUESHEET block with media catalog number, lead-in samples, CD status, and tracks. ```APIDOC ## Struct CueSheet ### Description A structure representing a CUESHEET block. ### Fields * `catalog_num` (String) - Media catalog number. * `num_leadin` (u64) - The number of lead-in samples. * `is_cd` (bool) - True if the cuesheet corresponds to a compact disc. * `tracks` (Vec) - One or more tracks. ### Implementations #### fn new() -> CueSheet Returns a new `CueSheet` for a CD with zero/empty values. #### fn from_bytes(bytes: &[u8]) -> Result Parses the bytes as a cuesheet block. #### fn to_bytes(&self) -> Vec Returns a vector representation of the cuesheet block suitable for writing to a file. ``` -------------------------------- ### Block Implementation Methods Source: https://docs.rs/metaflac/0.2.8/metaflac/block/enum.Block.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E This section details the methods available for the `Block` enum, including functions for reading from and writing to a data stream, and for retrieving the block type. ```APIDOC ## impl Block ### `pub fn read_from(reader: &mut dyn Read) -> Result<(bool, u32, Block)>` **Description:** Attempts to read a block from the reader. Returns a tuple containing a boolean indicating if the block was the last block, the length of the block in bytes, and the new `Block`. ### `pub fn write_to(&self, is_last: bool, writer: &mut dyn Write) -> Result` **Description:** Attempts to write the block to the writer. Returns the length of the block in bytes. ### `pub fn block_type(&self) -> BlockType` **Description:** Returns the corresponding block type byte for the block. ``` -------------------------------- ### SeekTable::new() - Create a new SeekTable Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekTable.html Creates and returns a new, empty `SeekTable` instance. Use this when initializing a SeekTable without any predefined seek points. ```rust pub fn new() -> SeekTable ``` -------------------------------- ### zip() Method Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates an iterator that yields pairs of elements from this iterator and another. ```rust fn zip(self, other: U) -> Zip::IntoIter> ``` -------------------------------- ### TryInto Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html Enables fallible type conversions to another type. It's the inverse of TryFrom. ```APIDOC ## impl TryInto for T where U: TryFrom ### Associated Types #### type Error = >::Error - Description: The type returned in the event of a conversion error. ### Methods #### fn try_into(self) -> Result>::Error> - Description: Performs the conversion from type T to type U. Returns a Result indicating success or failure. ``` -------------------------------- ### CloneToUninit Trait Implementation for BlockType Source: https://docs.rs/metaflac/0.2.8/metaflac/block/enum.BlockType.html?search=u32+-%3E+bool An experimental nightly-only API for copying BlockType values to uninitialized memory. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8) ``` -------------------------------- ### read_from Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search=u32+-%3E+bool Attempts to read a FLAC tag from the reader. ```APIDOC ## read_from ### Description Attempts to read a FLAC tag from the reader. ### Method `metaflac::read_from` ### Parameters - `reader`: `&mut dyn Read` - The reader to read from. ### Return Value `Result` containing the read tag or an error. ``` -------------------------------- ### Converting Result to Option (Ok value) Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Use `ok()` to convert a `Result` into an `Option`. The `Ok` value is preserved, while an `Err` becomes `None`. ```rust let x: Result = Ok(2); assert_eq!(x.ok(), Some(2)); let x: Result = Err("Nothing here"); assert_eq!(x.ok(), None); ``` -------------------------------- ### try_into Source: https://docs.rs/metaflac/0.2.8/metaflac/struct.Tag.html?search= Performs the conversion into another type, returning a Result. ```APIDOC ## try_into ### Description Performs the conversion into another type. This method is part of the `TryInto` trait. ### Method N/A (Method on a trait implementation) ### Parameters None ### Request Example N/A ### Response #### Success Response - **U** (Type) - The successfully converted value. #### Error Response - **Error** (>::Error) - The error type returned if conversion fails. ``` -------------------------------- ### map_windows Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Calls a function for each contiguous window of size `N` over the iterator and returns an iterator over the outputs. ```APIDOC ## fn map_windows(self, f: F) -> MapWindows ### Description Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well. ### Parameters - `f`: A closure that takes a slice representing the window and returns a value `R`. ### Returns A `MapWindows` iterator. ### Note This is a nightly-only experimental API. ``` -------------------------------- ### StructuralPartialEq Implementation for SeekPoint Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekPoint.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Indicates structural equality comparison is supported for SeekPoint. ```rust impl StructuralPartialEq for SeekPoint ``` -------------------------------- ### fn from_residual(_ : Yeet) -> Result Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=u32+-%3E+bool Constructs a Result from a compatible Residual type (Yeet). This is a nightly-only experimental API. ```APIDOC ## fn from_residual(_ : Yeet) -> Result ### Description Constructs the type from a compatible `Residual` type. This is a nightly-only experimental API. ### Method N/A (Associated function) ### Endpoint N/A ### Parameters - **_** (Yeet) - The residual to construct from. ### Request Example None ### Response #### Success Response (200) - **Result** (type) - The constructed Result type. ### Response Example None ``` -------------------------------- ### VorbisComment::set_lyrics() Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.VorbisComment.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Sets the lyrics comments. ```rust pub fn set_lyrics>(&mut self, lyrics: Vec) ``` -------------------------------- ### SeekPoint Methods Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.SeekPoint.html?search=std%3A%3Avec This section details the public methods available for the SeekPoint struct, allowing for creation, parsing from bytes, and serialization to bytes. ```APIDOC ## pub fn new() ### Description Returns a new `SeekPoint` with all zero values. ### Method `SeekPoint::new()` ### Returns A new `SeekPoint` instance with zeroed fields. ``` ```APIDOC ## pub fn from_bytes(bytes: &[u8]) -> SeekPoint ### Description Parses the provided byte slice into a `SeekPoint` structure. ### Method `SeekPoint::from_bytes(bytes)` ### Parameters #### Path Parameters - **bytes** (slice of u8) - The byte slice to parse. ### Returns A `SeekPoint` instance parsed from the bytes. ``` ```APIDOC ## pub fn to_bytes(&self) -> Vec ### Description Serializes the `SeekPoint` instance into a vector of bytes, suitable for writing to a file. ### Method `seek_point_instance.to_bytes()` ### Returns A `Vec` representing the `SeekPoint`. ``` -------------------------------- ### impl PartialEq for Result Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Provides equality comparison for Result, requiring that both T and E implement the PartialEq trait. ```APIDOC ## fn eq(&self, other: &Result) -> bool ### Description Tests for `self` and `other` values to be equal, and is used by `==`. ### Parameters #### Path Parameters - **other** (&Result) - Required - The other Result to compare against. ``` ```APIDOC ## fn ne(&self, other: &Rhs) -> bool ### Description Tests for `!=`. ### Parameters #### Path Parameters - **other** (&Rhs) - Required - The other Result to compare against. ``` -------------------------------- ### pub fn unwrap(self) -> T Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`. ```APIDOC ## pub fn unwrap(self) -> T ### Description Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`. Panics are meant for unrecoverable errors, and may abort the entire program. ### Request Example ```rust let x: Result = Ok(2); assert_eq!(x.unwrap(), 2); ``` ``` -------------------------------- ### next_chunk() Method (Nightly) Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Advances the iterator and returns an array of N items. This is a nightly-only experimental API. ```rust fn next_chunk( &mut self, ) -> Result<[Self::Item; N], IntoIter> ``` -------------------------------- ### expect Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html Returns the contained Ok value, consuming the self value. Panics if the value is an Err. ```APIDOC #### pub fn expect(self, msg: &str) -> T where E: Debug, Returns the contained `Ok` value, consuming the `self` value. Because this function may panic, its use is generally discouraged. Instead, prefer to use pattern matching and handle the `Err` case explicitly, or call `unwrap_or`, `unwrap_or_else`, or `unwrap_or_default`. ### Panics Panics if the value is an `Err`, with a panic message including the passed message, and the content of the `Err`. ### Recommended Message Style We recommend that `expect` messages are used to describe the reason you _expect_ the `Result` should be `Ok`. ### Examples ⓘ```rust let x: Result = Err("emergency failure"); x.expect("Testing expect"); // panics with `Testing expect: emergency failure` ``` ⓘ```rust let path = std::env::var("IMPORTANT_PATH") .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); ``` **Hint** : If you’re having trouble remembering how to phrase expect error messages remember to focus on the word “should” as in “env variable should be set by blah” or “the given binary should be available and executable by the current user”. For more detail on expect message styles and the reasoning behind our recommendation please refer to the section on “Common Message Styles” in the `std::error` module docs. ``` -------------------------------- ### pub fn expect(self, msg: &str) -> T Source: https://docs.rs/metaflac/0.2.8/metaflac/type.Result.html?search=std%3A%3Avec Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`. ```APIDOC ## pub fn expect(self, msg: &str) -> T ### Description Returns the contained `Ok` value, consuming the `self` value. Panics if the value is an `Err`, with a panic message including the passed message, and the content of the `Err`. ### Parameters #### Path Parameters - `msg` (&str): The message to include in the panic if the `Result` is `Err`. ### Panics Panics if the value is an `Err`, with a panic message including the passed message, and the content of the `Err`. ### Request Example ```rust let x: Result = Err("emergency failure"); x.expect("Testing expect"); // panics with `Testing expect: emergency failure` ``` ### Recommended Message Style We recommend that `expect` messages are used to describe the reason you _expect_ the `Result` should be `Ok`. ```rust let path = std::env::var("IMPORTANT_PATH") .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); ``` ``` -------------------------------- ### VorbisComment::fmt Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.VorbisComment.html?search= Formats the VorbisComment instance for display. ```APIDOC ## VorbisComment::fmt ### Description Formats the value using the given formatter. ### Method `VorbisComment::fmt(&self, f: &mut Formatter<'_>) -> Result` ### Parameters #### Path Parameters - `f` ( &mut Formatter<'_> ) - The formatter to use. ### Returns - `Result`: A `Result` indicating success or failure of the formatting operation. ``` -------------------------------- ### by_ref Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=u32+-%3E+bool Creates a "by reference" adapter for an iterator, allowing mutable borrowing of the iterator itself. ```APIDOC ## fn by_ref(&mut self) -> &mut Self ### Description Creates a “by reference” adapter for this instance of `Iterator`. ### Returns A mutable reference to the iterator itself. ``` -------------------------------- ### from Source: https://docs.rs/metaflac/0.2.8/metaflac/block/struct.Blocks.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Returns the argument unchanged. ```APIDOC ## fn from(t: T) -> T ### Description Returns the argument unchanged. ### Parameters - `t`: The value to be converted. ### Returns The same value `t` that was passed in. ```