Struct WriteOptions 

#[non_exhaustive]
pub struct WriteOptions { /* private fields */ }

Options to control how Lofty writes to a file

This acts as a dumping ground for all sorts of format-specific settings. As such, this is best used as an application global config that gets set once.

Implementations

impl WriteOptions

pub const DEFAULT_PREFERRED_PADDING: u32 = 1024

Default preferred padding size in bytes

pub const fn new() -> WriteOptions

Creates a new WriteOptions, alias for Default implementation

See also: WriteOptions::default

Examples

use lofty::config::WriteOptions;

let write_options = WriteOptions::new();

pub fn preferred_padding(self, preferred_padding: u32) -> WriteOptions

Set the preferred padding size in bytes

If the tag format being written supports padding, this will be the size of the padding in bytes.

NOTES:

• Not all tag formats support padding
• The actual padding size may be different from this value, depending on tag size limitations

Examples

use lofty::config::WriteOptions;

// I really don't want my files rewritten, so I'll double the padding size!
let options = WriteOptions::new().preferred_padding(2048);

// ...Or I don't want padding under any circumstances!
let options = WriteOptions::new().preferred_padding(0);

pub fn remove_others(self, remove_others: bool) -> WriteOptions

Whether to remove all other tags when writing

If set to true, only the tag being written will be kept in the file.

Examples

use lofty::config::WriteOptions;
use lofty::prelude::*;
use lofty::tag::{Tag, TagType};

let mut id3v2_tag = Tag::new(TagType::Id3v2);

// ...

// I only want to keep the ID3v2 tag around!
let options = WriteOptions::new().remove_others(true);
id3v2_tag.save_to_path("test.mp3", options)?;

pub fn respect_read_only(self, respect_read_only: bool) -> WriteOptions

Whether to respect read-only tag items

Some tag formats allow for items to be marked as read-only. If set to true, these items will take priority over newly created tag items.

NOTE: In the case of APE tags, one can mark the entire tag as read-only. This will append the existing tag items to the new tag.

Examples

use lofty::config::WriteOptions;
use lofty::prelude::*;
use lofty::tag::{Tag, TagType};

let mut id3v2_tag = Tag::new(TagType::Id3v2);

// ...

// I don't care about read-only items, I want to write my new items!
let options = WriteOptions::new().respect_read_only(false);
id3v2_tag.save_to_path("test.mp3", options)?;

pub fn uppercase_id3v2_chunk(self, uppercase_id3v2_chunk: bool) -> WriteOptions

Whether to uppercase the ID3v2 chunk name

When dealing with RIFF/AIFF files, some software may expect the ID3v2 chunk name to be lowercase.

NOTE: The vast majority of software will be able to read both upper and lowercase chunk names.

Examples

use lofty::config::WriteOptions;
use lofty::prelude::*;
use lofty::tag::{Tag, TagType};

let mut id3v2_tag = Tag::new(TagType::Id3v2);

// ...

// I want to keep the ID3v2 chunk name lowercase
let options = WriteOptions::new().uppercase_id3v2_chunk(false);
id3v2_tag.save_to_path("test.mp3", options)?;

pub fn use_id3v23(&mut self, use_id3v23: bool) -> WriteOptions

Whether or not to use ID3v2.3 when saving TagType::Id3v2 or Id3v2Tag

By default, Lofty will save ID3v2.4 tags. This option allows you to save ID3v2.3 tags instead.

Examples

use lofty::config::WriteOptions;
use lofty::prelude::*;
use lofty::tag::{Tag, TagType};

let mut id3v2_tag = Tag::new(TagType::Id3v2);

// ...

// I need to save ID3v2.3 tags to support older software
let options = WriteOptions::new().use_id3v23(true);
id3v2_tag.save_to_path("test.mp3", options)?;

pub fn lossy_text_encoding(&mut self, lossy_text_encoding: bool) -> WriteOptions

Whether to replace invalid characters when writing strings

Some tag formats are restricted to certain TextEncodings, which may restrict the available character set.

If this is enabled, any invalid characters will be replaced with '?' (e.g lфfty in TextEncoding::Latin1 will return l?fty).

If this is disabled, any writes with non-representable characters will return an ErrorKind::TextEncode.

Examples

use lofty::config::WriteOptions;
use lofty::prelude::*;
use lofty::tag::{Tag, TagType};

let mut id3v1_tag = Tag::new(TagType::Id3v1);

// ID3v1 is restricted to Latin-1, this string can't be written as-is!
id3v1_tag.insert_text(ItemKey::TrackArtist, String::from("lфfty"));

// With lossy encoding disabled, the write will fail!
let options = WriteOptions::new().lossy_text_encoding(false);
id3v1_tag.save_to_path("test.mp3", options)?;

Trait Implementations

impl Clone for WriteOptions

fn clone(&self) -> WriteOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WriteOptions

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

Formats the value using the given formatter.

impl Default for WriteOptions

fn default() -> WriteOptions

The default implementation for WriteOptions

The defaults are as follows:

WriteOptions {
    preferred_padding: 1024,
    remove_others: false,
    respect_read_only: true,
    uppercase_id3v2_chunk: true,
    use_id3v23: false,
    lossy_text_encoding: true,
}

impl PartialEq for WriteOptions

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for WriteOptions

impl Eq for WriteOptions

impl StructuralPartialEq for WriteOptions