Struct libxivdat::xiv_macro::Macro

pub struct Macro {
    pub icon_key: String,
    pub icon_id: String,
    pub lines: Vec<String>,
    pub title: String,
}

Resource definition for a Final Fantasy XIV macro. Macro owns its constituent data and is returned from helper functions like read_macro(). To build a section with refrences to a pre-allocated buffer, use MacroData.

Game client macro spec

Title: No more than 20 utf-8 characters. Icon: Icon id and key are a matching pair corresponding to a valid MacroIcon. Lines: Exactly 15 lines of no more than 180 utf-8 characters.

Data Structure

The expected pattern of sections is “T” (Title), “I” (Icon), “K”, (Key), and repeating “L“s (Lines). Valid macros always contain exactly 15 lines, even if their contents are blank. This library does not strictly enforce this pattern, and will read lines until the next title.

Fields

icon_key: String

The index of the icon in the GUI icon selection menu as 3 hexadecimal digits. This value must match the icon_id to be considered valid. Use change_icon() to update both icon-related values at once.

icon_id: String

The index of the icon in the game data files as 7 hexadecimal digits. This value must match the icon_key to be considered valid. Use change_icon() to update both icon-related values at once.

lines: Vec<String>

A vector of macro lines. Macros created by the game client are always 15 lines long, even if those lines are blank. Lines must be shorter than 180 utf-8 characters. This is a character limit, not a byte limit. This library does not enforce these standards, but attempting to write a macro of a different size and use it in the game client may produce undefined behavior. Macro lines may contain an extended, FFXIV-specific character set (including game icons such as the HQ icon and item link icon). These are likely to render improperly on other platforms.

title: String

The title of the macro. Titles have a maximum length of 20 utf-8 characters in the game client. This is a character limit, not a byte limit. Longer titles may produce undefined behavior.

Implementations

impl Macro

pub fn as_sections(&self) -> Result<Vec<Section>, DATError>

Returns a Vec of Sections representing the Macro.

Errors

Returns a DATError::Overflow if the content of a section would exceed the maximum allowable length. (u16::MAX - 1)

Examples

use libxivdat::xiv_macro::Macro;
use libxivdat::xiv_macro::icon::MacroIcon;

let a_macro = Macro::new(
    "Title".to_string(),
    vec!["Circle".to_string()],
    MacroIcon::SymbolCircle
).unwrap();

let sections = a_macro.as_sections().unwrap();

assert_eq!(sections[0].content, "Title");

pub fn change_icon(&mut self, icon: MacroIcon)

Changes the icon_key and icon_id to a valid pair based on an input MacroIcon.

Examples

use libxivdat::xiv_macro::Macro;
use libxivdat::xiv_macro::icon::MacroIcon;

let mut a_macro = Macro::new(
    "Title".to_string(),
    Vec::<String>::new(),
    MacroIcon::NoIcon
).unwrap();

assert_eq!(a_macro.icon_id, "0000000");
assert_eq!(a_macro.icon_key, "000");

a_macro.change_icon(MacroIcon::SymbolArrowUp);
assert_eq!(a_macro.icon_id, "00102FF");
assert_eq!(a_macro.icon_key, "037");

pub fn from_sections(sections: Vec<Section>) -> Result<Macro, DATError>

Builds a Macro from a Vec of Sections. The expected pattern of section tags is “T” (Title), “I” (Icon), “K”, (Key), and repeating “L“s (Lines). Valid macros always contain exactly 15 lines, even if their contents are blank. This function checks the data for validity, unlick from_sections_unsafe()

This is equivalent to calling from_sections_unsafe() followed by validate() on the resulting Macro.

Macro spec

Title: No more than 20 utf-8 characters. Icon: Icon id and key are a matching pair corresponding to a valid MacroIcon. Lines: Exactly 15 lines of no more than 180 utf-8 characters.

Errors

Returns DATError::InvalidInput if the sections are not provided in the order described above or the icon id and key specified are not a valid pair.

Returns DATError::Overflow if the title or any line is too long, or if there are too many lines.

Returns DATError::Underflow if there are too few lines.

Examples

use libxivdat::section::Section;
use libxivdat::xiv_macro::Macro;

let mut sections = vec![
    Section { content: "Title".to_string(), content_size: 6, tag: "T".to_string() },
    Section { content: "0000000".to_string(), content_size: 8, tag: "I".to_string() },
    Section { content: "000".to_string(), content_size: 4, tag: "K".to_string() }
];
for line in std::iter::repeat(String::new()).take(15) {
    sections.push(Section { content: line, content_size: 1, tag: "L".to_string() });
}
let result_macro = Macro::from_sections(sections).unwrap();

assert_eq!(result_macro.title, "Title");

pub fn from_sections_unsafe(sections: Vec<Section>) -> Result<Macro, DATError>

Builds a Macro from a Vec of Sections. The expected pattern of section tags is “T” (Title), “I” (Icon), “K”, (Key), and repeating “L“s (Lines). Valid macros always contain exactly 15 lines, even if their contents are blank. This library does not strictly enforce this pattern, and will read lines until the next title.

This function does not check that the actual section content is valid. To perform validity checks, use from_sections().

Errors

Returns DATError::InvalidInput if the sections are not provided in the order described above or any sections are missing.

Examples

use libxivdat::section::Section;
use libxivdat::xiv_macro::Macro;

let sections = vec![
    Section { content: "Title".to_string(), content_size: 6, tag: "T".to_string() },
    Section { content: "0000000".to_string(), content_size: 8, tag: "I".to_string() },
    Section { content: "000".to_string(), content_size: 4, tag: "K".to_string() },
    Section { content: "A one line macro!?".to_string(), content_size: 19, tag: "L".to_string() }
];
let result_macro = Macro::from_sections_unsafe(sections).unwrap();

assert_eq!(result_macro.title, "Title");
assert_eq!(result_macro.lines.len(), 1);

pub fn get_icon(&self) -> Option<MacroIcon>

Gets the MacroIcon correpsonding to the current icon_key and icon_id. Returns None if the id and key do not correspond to a known valid icon.

Examples

use libxivdat::xiv_macro::Macro;
use libxivdat::xiv_macro::icon::MacroIcon;

let a_macro = Macro::new(
    "Title".to_string(),
    Vec::<String>::new(),
    MacroIcon::SymbolArrowUp
).unwrap();
assert_eq!(a_macro.get_icon().unwrap(), MacroIcon::SymbolArrowUp);

pub fn new(
    title: String,
    lines: Vec<String>,
    icon: MacroIcon
) -> Result<Macro, DATError>

Builds a new Macro with a given title, MacroIcon, and content. This ensures that the macro meets the spec described below, which is used by the game client. If the provided line count is less than 15, the count will be padded with blank lines.

To create an unvalidated Macro, you can directly instantiate a struct literal.

Errors

Returns DATError::Overflow if the title or content are too long, or if there are too many lines.

Examples

use libxivdat::xiv_macro::Macro;
use libxivdat::xiv_macro::icon::MacroIcon;

let a_macro = Macro::new(
    "Title".to_string(),
    vec!["Circle".to_string()],
    MacroIcon::SymbolCircle
).unwrap();

assert_eq!(a_macro.title, "Title");
assert_eq!(a_macro.lines[0], "Circle");
assert_eq!(a_macro.get_icon().unwrap(), MacroIcon::SymbolCircle);

Trait Implementations

impl AsBytes for Macro

fn as_bytes(&self) -> Result<Vec<u8>, DATError>

Returns a byte vector representing the struct. This can then be written back to the DAT file on disk.

impl Clone for Macro

fn clone(&self) -> Macro

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Macro

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

Formats the value using the given formatter.

impl From<&'_ MacroData<'_>> for Macro

fn from(x: &MacroData<'_>) -> Self

Performs the conversion.

impl<'a> From<&'a Macro> for MacroData<'a>

fn from(x: &'a Macro) -> Self

Performs the conversion.

impl PartialEq<Macro> for Macro

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

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

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

This method tests for !=.

impl Validate for Macro

fn validate(&self) -> Option<DATError>

Validates the struct data against the spec expected by the game client. Returns a DATError describing the error if validation fails, or None if validation is successful.

impl Eq for Macro

impl StructuralEq for Macro

impl StructuralPartialEq for Macro