diff --git a/rust/src/cells/methods.rs b/rust/src/cells/methods.rs index 2451050e6..7793b2dc4 100644 --- a/rust/src/cells/methods.rs +++ b/rust/src/cells/methods.rs @@ -1,8 +1,8 @@ //! `NcCell` methods and associated functions. use crate::{ - cell_extract, cell_load, cstring, NcCell, NcChannelPair, NcEgc, NcEgcBackstop, NcPlane, - NcStyleMask, NCRESULT_ERR, + cell_extract, cell_load, cstring, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, + NcEgc, NcEgcBackstop, NcPaletteIndex, NcPlane, NcRgb, NcStyleMask, NCRESULT_ERR, }; /// # `NcCell` Constructors @@ -55,10 +55,214 @@ impl NcCell { } } +// ----------------------------------------------------------------------------- +/// ## NcPlane methods: bg|fg `NcChannel`s manipulation. +impl NcCell { + /// Gets the background [NcChannel]. + /// + /// *C style function: [cell_bchannel()][crate::cell_bchannel].* + pub fn bchannel(&self) -> NcChannel { + crate::cell_bchannel(self) + } + + /// Extracts the background [NcAlphaBits] (shifted to LSBs). + /// + /// *C style function: [cell_bg_alpha()][crate::cell_bg_alpha].* + pub fn bg_alpha(&self) -> NcAlphaBits { + crate::cell_bg_alpha(self) + } + + /// Is the background [NcChannel] using the "default background color"? + /// + /// *C style function: [cell_bg_default_p()][crate::cell_bg_default_p].* + pub fn bg_default_p(&self) -> bool { + crate::cell_bg_default_p(self) + } + + /// Gets the [NcPaletteIndex] of the background [NcChannel]. + /// + /// *C style function: [cell_bg_palindex()][crate::cell_bg_palindex].* + pub fn bg_palindex(&self) -> NcPaletteIndex { + crate::cell_bg_palindex(self) + } + + /// Is the background [NcChannel] using an [NcPaletteIndex] indexed + /// [NcPalette][crate::NcPalette] color? + /// + /// *C style function: [cell_bg_palindex_p()][crate::cell_bg_palindex_p].* + pub fn bg_palindex_p(&self) -> bool { + crate::cell_bg_palindex_p(self) + } + + /// Gets the background [NcRgb] (shifted to LSBs). + /// + /// *C style function: [cell_bg_rgb()][crate::cell_bg_rgb].* + pub fn bg_rgb(&self) -> NcRgb { + crate::cell_bg_rgb(self) + } + + /// Gets the background [NcColor] RGB components. + /// + /// *C style function: [cell_bg_rgb8()][crate::cell_bg_rgb8].* + pub fn bg_rgb8(&self) -> (NcColor, NcColor, NcColor) { + let (mut r, mut g, mut b) = (0, 0, 0); + crate::cell_bg_rgb8(self, &mut r, &mut g, &mut b); + (r, g, b) + } + + /// Gets the foreground [NcChannel]. + /// + /// *C style function: [cell_fchannel()][crate::cell_fchannel].* + pub fn fchannel(&self) -> NcChannel { + crate::cell_fchannel(self) + } + + /// Extracts the foreground [NcAlphaBits] (shifted to LSBs). + /// + /// *C style function: [cell_fg_alpha()][crate::cell_fg_alpha].* + pub fn fg_alpha(&self) -> NcAlphaBits { + crate::cell_fg_alpha(self) + } + + /// Is the foreground [NcChannel] using the "default foreground color"? + /// + /// *C style function: [cell_fg_default_p()][crate::cell_fg_default_p].* + pub fn fg_default_p(&self) -> bool { + crate::cell_fg_default_p(self) + } + + /// Gets the [NcPaletteIndex] of the foreground [NcChannel]. + /// + /// *C style function: [cell_fg_palindex()][crate::cell_fg_palindex].* + pub fn fg_palindex(&self) -> NcPaletteIndex { + crate::cell_fg_palindex(self) + } + + /// Is the foreground [NcChannel] using an [NcPaletteIndex] indexed + /// [NcPalette][crate::NcPalette] color? + /// + /// *C style function: [cell_fg_palindex_p()][crate::cell_fg_palindex_p].* + pub fn fg_palindex_p(&self) -> bool { + crate::cell_fg_palindex_p(self) + } + + /// Gets the foreground [NcRgb] (shifted to LSBs). + /// + /// *C style function: [cell_fg_rgb()][crate::cell_fg_rgb].* + pub fn fg_rgb(&self) -> NcRgb { + crate::cell_fg_rgb(self) + } + + /// Gets the foreground [NcColor] RGB components. + /// + /// *C style function: [cell_fg_rgb8()][crate::cell_fg_rgb8].* + pub fn fg_rgb8(&self) -> (NcColor, NcColor, NcColor) { + let (mut r, mut g, mut b) = (0, 0, 0); + crate::cell_fg_rgb8(self, &mut r, &mut g, &mut b); + (r, g, b) + } + + /// Sets the background [NcChannel] and returns the new [NcChannelPair]. + /// + /// *C style function: [cell_set_bchannel()][crate::cell_set_bchannel].* + pub fn set_bchannel(&mut self, channel: NcChannel) -> NcChannelPair { + crate::cell_set_bchannel(self, channel) + } + + /// Sets the background [NcAlphaBits]. + /// + /// *C style function: [cell_set_bg_alpha()][crate::cell_set_bg_alpha].* + pub fn set_bg_alpha(&mut self, alpha: NcAlphaBits) { + crate::cell_set_bg_alpha(self, alpha); + } + + /// Indicates to use the "default color" for the background [NcChannel]. + /// + /// *C style function: [cell_set_bg_default()][crate::cell_set_bg_default].* + pub fn set_bg_default(&mut self) { + crate::cell_set_bg_default(self); + } + + /// Sets the background [NcPaletteIndex]. + /// + /// Also sets [NCCELL_BG_PALETTE][crate::NCCELL_BG_PALETTE] and + /// [NCCELL_ALPHA_OPAQUE][crate::NCCELL_ALPHA_OPAQUE], and clears out + /// [NCCELL_BGDEFAULT_MASK][crate::NCCELL_BGDEFAULT_MASK]. + /// + /// *C style function: [cell_set_bg_palindex()][crate::cell_set_bg_palindex].* + pub fn set_bg_palindex(&mut self, index: NcPaletteIndex) { + crate::cell_set_bg_palindex(self, index); + } + + /// Sets the background [NcRgb] and marks it as not using the default color. + /// + /// *C style function: [cell_set_bg_rgb()][crate::cell_set_bg_rgb].* + pub fn set_bg_rgb(&mut self, rgb: NcRgb) { + crate::cell_set_bg_rgb(self, rgb); + } + + /// Sets the background [NcColor] RGB components, and marks it as not using + /// the "default color". + /// + /// *C style function: [cell_set_bg_rgb8()][crate::cell_set_bg_rgb8].* + pub fn set_bg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) { + crate::cell_set_bg_rgb8(self, red, green, blue); + } + + /// Sets the foreground [NcChannel] and returns the new [NcChannelPair]. + /// + /// *C style function: [cell_set_fchannel()][crate::cell_set_fchannel].* + pub fn set_fchannel(&mut self, channel: NcChannel) -> NcChannelPair { + crate::cell_set_fchannel(self, channel) + } + + /// Sets the foreground [NcAlphaBits]. + /// + /// *C style function: [cell_set_fg_alpha()][crate::cell_set_fg_alpha].* + pub fn set_fg_alpha(&mut self, alpha: NcAlphaBits) { + crate::cell_set_fg_alpha(self, alpha); + } + + /// Indicates to use the "default color" for the foreground [NcChannel]. + /// + /// *C style function: [cell_set_fg_default()][crate::cell_set_fg_default].* + pub fn set_fg_default(&mut self) { + crate::cell_set_fg_default(self); + } + + /// Sets the foreground [NcPaletteIndex]. + /// + /// Also sets [NCCELL_FG_PALETTE][crate::NCCELL_FG_PALETTE] and + /// [NCCELL_ALPHA_OPAQUE][crate::NCCELL_ALPHA_OPAQUE], and clears out + /// [NCCELL_BGDEFAULT_MASK][crate::NCCELL_BGDEFAULT_MASK]. + /// + /// *C style function: [cell_set_fg_palindex()][crate::cell_set_fg_palindex].* + pub fn set_fg_palindex(&mut self, index: NcPaletteIndex) { + crate::cell_set_fg_palindex(self, index); + } + + /// Sets the foreground [NcRgb] and marks it as not using the default color. + /// + /// *C style function: [cell_set_fg_rgb()][crate::cell_set_fg_rgb].* + pub fn set_fg_rgb(&mut self, rgb: NcRgb) { + crate::cell_set_fg_rgb(self, rgb); + } + + /// Sets the foreground [NcColor] RGB components, and marks it as not using + /// the "default color". + /// + /// *C style function: [cell_set_fg_rgb8()][crate::cell_set_fg_rgb8].* + pub fn set_fg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) { + crate::cell_set_fg_rgb8(self, red, green, blue); + } +} + /// # `NcCell` Methods impl NcCell { /// Saves the [NcStyleMask] and the [NcChannelPair], and returns the [NcEgc] /// (the three elements of an NcCell). + /// + /// *C style function: [cell_fg_alpha()][crate::cell_fg_alpha].* pub fn extract( &mut self, plane: &mut NcPlane, @@ -68,22 +272,27 @@ impl NcCell { cell_extract(plane, self, styles, channels) } - /// Saves the [NcChannelPair] of the NcCell. - // not in the C API - pub fn channels(&mut self, plane: &mut NcPlane, channels: &mut NcChannelPair) { - let mut _styles = 0; - let _char = cell_extract(plane, self, &mut _styles, channels); + /// Returns the [NcChannelPair] of the NcCell. + /// + /// *(No equivalent C style function)* + pub fn channels(&mut self, plane: &mut NcPlane) -> NcChannelPair { + let (mut _styles, mut channels) = (0, 0); + let _char = cell_extract(plane, self, &mut _styles, &mut channels); + channels } - /// Saves the [NcStyleMask] of the NcCell. - // not in the C API - pub fn styles(&mut self, plane: &mut NcPlane, styles: &mut NcStyleMask) { - let mut _channels = 0; - let _char = cell_extract(plane, self, styles, &mut _channels); + /// Returns the [NcStyleMask] of the NcCell. + /// + /// *(No equivalent C style function)* + pub fn styles(&mut self, plane: &mut NcPlane) -> NcStyleMask { + let (mut styles, mut _channels) = (0, 0); + let _char = cell_extract(plane, self, &mut styles, &mut _channels); + styles } /// Returns the [NcEgc] of the NcCell. - // not in the C API + /// + /// *(No equivalent C style function)* pub fn egc(&mut self, plane: &mut NcPlane) -> NcEgc { let (mut _styles, mut _channels) = (0, 0); cell_extract(plane, self, &mut _styles, &mut _channels) diff --git a/rust/src/cells/mod.rs b/rust/src/cells/mod.rs index 5a875826a..dd3df7235 100644 --- a/rust/src/cells/mod.rs +++ b/rust/src/cells/mod.rs @@ -13,42 +13,42 @@ // ------------------------------------------ // (X) wont: 2 // (+) done: 40 / 0 -// (W) wrap: 1 / 39 -// (#) test: 26 / 14 +// (W) wrap: 27 +// (#) test: 26 // ------------------------------------------ -// # cell_bchannel -// # cell_bg_alpha -// # cell_bg_default_p -// # cell_bg_palindex -// # cell_bg_palindex_p -// # cell_bg_rgb -// # cell_bg_rgb8 +//W# cell_bchannel +//W# cell_bg_alpha +//W# cell_bg_default_p +//W# cell_bg_palindex +//W# cell_bg_palindex_p +//W# cell_bg_rgb +//W# cell_bg_rgb8 // + cellcmp // + cell_double_wide_p //W+ cell_extract -// # cell_fchannel -// # cell_fg_alpha -// # cell_fg_default_p -// # cell_fg_palindex -// # cell_fg_palindex_p -// # cell_fg_rgb -// # cell_fg_rgb8 +//W# cell_fchannel +//W# cell_fg_alpha +//W# cell_fg_default_p +//W# cell_fg_palindex +//W# cell_fg_palindex_p +//W# cell_fg_rgb +//W# cell_fg_rgb8 // + cell_init // + cell_load_char // + cell_prime -// # cell_set_bchannel -// # cell_set_bg_alpha -// # cell_set_bg_default -// # cell_set_bg_palindex -// # cell_set_bg_rgb -// # cell_set_bg_rgb8 +//W# cell_set_bchannel +//W# cell_set_bg_alpha +//W# cell_set_bg_default +//W# cell_set_bg_palindex +//W# cell_set_bg_rgb +//W# cell_set_bg_rgb8 // X cell_set_bg_rgb8_clipped // unneeded -// # cell_set_fchannel -// # cell_set_fg_alpha -// # cell_set_fg_default -// # cell_set_fg_palindex -// # cell_set_fg_rgb -// # cell_set_fg_rgb8 +//W# cell_set_fchannel +//W# cell_set_fg_alpha +//W# cell_set_fg_default +//W# cell_set_fg_palindex +//W# cell_set_fg_rgb +//W# cell_set_fg_rgb8 // X cell_set_fg_rgb8_clipped // unneeded // + cells_load_box // + cell_strdup @@ -67,7 +67,7 @@ mod reimplemented; pub use reimplemented::*; // NcCell -/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data +/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data. /// /// An `NcCell` corresponds to a single character cell on some [`NcPlane`], /// which can be occupied by a single [`NcEgc`] grapheme cluster (some root diff --git a/rust/src/cells/reimplemented.rs b/rust/src/cells/reimplemented.rs index 7991a74e3..8bf6a5dcf 100644 --- a/rust/src/cells/reimplemented.rs +++ b/rust/src/cells/reimplemented.rs @@ -3,76 +3,88 @@ use libc::strcmp; use crate::{ - cell_extended_gcluster, cell_load, cell_release, channels_bchannel, channels_bg_alpha, - channels_bg_default_p, channels_bg_palindex_p, channels_bg_rgb, channels_bg_rgb8, - channels_fchannel, channels_fg_alpha, channels_fg_default_p, channels_fg_palindex_p, - channels_fg_rgb, channels_fg_rgb8, channels_set_bchannel, channels_set_bg_alpha, - channels_set_bg_default, channels_set_bg_rgb, channels_set_bg_rgb8, channels_set_fchannel, - channels_set_fg_alpha, channels_set_fg_default, channels_set_fg_rgb, channels_set_fg_rgb8, - NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcPaletteIndex, NcPlane, - NcResult, NcRgb, NcStyleMask, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK, NCCELL_BG_PALETTE, - NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCELL_NOBACKGROUND_MASK, NCCELL_WIDEASIAN_MASK, - NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK, + cell_release, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc, NcPaletteIndex, + NcPlane, NcResult, NcRgb, NcStyleMask, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK, + NCCELL_BG_PALETTE, NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCELL_NOBACKGROUND_MASK, + NCCELL_WIDEASIAN_MASK, NCRESULT_ERR, NCRESULT_OK, NCSTYLE_MASK, }; // Alpha ----------------------------------------------------------------------- /// Extracts the foreground [NcAlphaBits] from an [NcCell] (shifted to LSBs). +/// +/// *Method: NcCell.[fg_alpha()][NcCell#method.fg_alpha].* #[inline] pub fn cell_fg_alpha(cell: &NcCell) -> NcAlphaBits { - channels_fg_alpha(cell.channels) + crate::channels_fg_alpha(cell.channels) } /// Extracts the background [NcAlphaBits] from an [NcCell] (shifted to LSBs). +/// +/// *Method: NcCell.[bg_alpha()][NcCell#method.bg_alpha].* #[inline] pub fn cell_bg_alpha(cell: &NcCell) -> NcAlphaBits { - channels_bg_alpha(cell.channels) + crate::channels_bg_alpha(cell.channels) } /// Sets the foreground [NcAlphaBits] of an [NcCell]. +/// +/// *Method: NcCell.[set_fg_alpha()][NcCell#method.set_fg_alpha].* #[inline] pub fn cell_set_fg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) { - channels_set_fg_alpha(&mut cell.channels, alpha); + crate::channels_set_fg_alpha(&mut cell.channels, alpha); } /// Sets the background [NcAlphaBits] of an [NcCell]. +/// +/// *Method: NcCell.[set_bg_alpha()][NcCell#method.set_bg_alpha].* #[inline] pub fn cell_set_bg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) { - channels_set_bg_alpha(&mut cell.channels, alpha); + crate::channels_set_bg_alpha(&mut cell.channels, alpha); } // Channels -------------------------------------------------------------------- /// Gets the foreground [NcChannel] from an [NcCell]. +/// +/// *Method: NcCell.[fchannel()][NcCell#method.fchannel].* #[inline] pub fn cell_fchannel(cell: &NcCell) -> NcChannel { - channels_fchannel(cell.channels) + crate::channels_fchannel(cell.channels) } /// Gets the background [NcChannel] from an [NcCell]. +/// +/// *Method: NcCell.[bchannel()][NcCell#method.bchannel].* #[inline] pub fn cell_bchannel(cell: &NcCell) -> NcChannel { - channels_bchannel(cell.channels) + crate::channels_bchannel(cell.channels) } /// Sets the foreground [NcChannel] of an [NcCell] and returns the new /// [NcChannelPair]. +/// +/// *Method: NcCell.[set_fchannel()][NcCell#method.set_fchannel].* #[inline] pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair { - channels_set_fchannel(&mut cell.channels, channel) + crate::channels_set_fchannel(&mut cell.channels, channel) } /// Sets the background [NcChannel] of an [NcCell] and returns the new /// [NcChannelPair]. +/// +/// *Method: NcCell.[set_bchannel()][NcCell#method.set_bchannel].* #[inline] pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair { - channels_set_bchannel(&mut cell.channels, channel) + crate::channels_set_bchannel(&mut cell.channels, channel) } // NcColor --------------------------------------------------------------------- /// Gets the foreground [NcColor] RGB components of an [NcCell], /// and returns the [NcChannel] (which can have some extra bits set). +/// +/// *Method: NcCell.[fg_rgb8()][NcCell#method.fg_rgb8].* #[inline] pub fn cell_fg_rgb8( cell: &NcCell, @@ -80,11 +92,13 @@ pub fn cell_fg_rgb8( green: &mut NcColor, blue: &mut NcColor, ) -> NcChannel { - channels_fg_rgb8(cell.channels, red, green, blue) + crate::channels_fg_rgb8(cell.channels, red, green, blue) } /// Gets the background [NcColor] RGB components of an [NcCell], /// and returns the [NcChannel] (which can have some extra bits set). +/// +/// *Method: NcCell.[bg_rgb8()][NcCell#method.bg_rgb8].* #[inline] pub fn cell_bg_rgb8( cell: &NcCell, @@ -92,72 +106,90 @@ pub fn cell_bg_rgb8( green: &mut NcColor, blue: &mut NcColor, ) -> NcChannel { - channels_bg_rgb8(cell.channels, red, green, blue) + crate::channels_bg_rgb8(cell.channels, red, green, blue) } -/// Sets the foreground [NcColor] 8-bit RGB components of of the [NcCell], +/// Sets the foreground [NcColor] RGB components of the [NcCell], /// and marks it as not using the "default color". +/// +/// *Method: NcCell.[set_fg_rgb8()][NcCell#method.set_fg_rgb8].* #[inline] pub fn cell_set_fg_rgb8(cell: &mut NcCell, red: NcColor, green: NcColor, blue: NcColor) { - channels_set_fg_rgb8(&mut cell.channels, red, green, blue); + crate::channels_set_fg_rgb8(&mut cell.channels, red, green, blue); } -/// Sets the background [NcColor] 8-bit RGB components of of the [NcCell], +/// Sets the background [NcColor] RGB components of the [NcCell], /// and marks it as not using the "default color". +/// +/// *Method: NcCell.[set_bg_rgb8()][NcCell#method.set_bg_rgb8].* #[inline] pub fn cell_set_bg_rgb8(cell: &mut NcCell, red: NcColor, green: NcColor, blue: NcColor) { - channels_set_bg_rgb8(&mut cell.channels, red, green, blue); + crate::channels_set_bg_rgb8(&mut cell.channels, red, green, blue); } // NcRgb ----------------------------------------------------------------------- /// Gets the foreground [NcRgb] from an [NcCell] (shifted to LSBs). +/// +/// *Method: NcCell.[fg_rgb()][NcCell#method.fg_rgb].* #[inline] pub fn cell_fg_rgb(cell: &NcCell) -> NcRgb { - channels_fg_rgb(cell.channels) + crate::channels_fg_rgb(cell.channels) } /// Gets the background [NcRgb] from an [NcCell] (shifted to LSBs). +/// +/// *Method: NcCell.[bg_rgb()][NcCell#method.bg_rgb].* #[inline] pub fn cell_bg_rgb(cell: &NcCell) -> NcRgb { - channels_bg_rgb(cell.channels) + crate::channels_bg_rgb(cell.channels) } /// Sets the foreground [NcRgb] of an [NcCell], /// and marks it as not using the default color. +/// +/// *Method: NcCell.[set_fg_rgb()][NcCell#method.set_fg_rgb].* #[inline] pub fn cell_set_fg_rgb(cell: &mut NcCell, rgb: NcRgb) { - channels_set_fg_rgb(&mut cell.channels, rgb); + crate::channels_set_fg_rgb(&mut cell.channels, rgb); } /// Sets the background [NcRgb] of an [NcCell], /// and marks it as not using the default color. +/// +/// *Method: NcCell.[set_bg_rgb()][NcCell#method.set_bg_rgb].* #[inline] pub fn cell_set_bg_rgb(cell: &mut NcCell, rgb: NcRgb) { - channels_set_bg_rgb(&mut cell.channels, rgb); + crate::channels_set_bg_rgb(&mut cell.channels, rgb); } // Default --------------------------------------------------------------------- -/// Indicates to use the "default color" for the **foreground** [NcChannel] +/// Indicates to use the "default color" for the foreground [NcChannel] /// of an [NcCell]. +/// +/// *Method: NcCell.[set_fg_default()][NcCell#method.set_fg_default].* #[inline] pub fn cell_set_fg_default(cell: &mut NcCell) { - channels_set_fg_default(&mut cell.channels); + crate::channels_set_fg_default(&mut cell.channels); } -/// Indicates to use the "default color" for the **background** [NcChannel] +/// Indicates to use the "default color" for the background [NcChannel] /// of an [NcCell]. +/// +/// *Method: NcCell.[set_bg_default()][NcCell#method.set_bg_default].* #[inline] pub fn cell_set_bg_default(cell: &mut NcCell) { - channels_set_bg_default(&mut cell.channels); + crate::channels_set_bg_default(&mut cell.channels); } /// Is the foreground [NcChannel] of this [NcCell] using the /// "default foreground color"? +/// +/// *Method: NcCell.[fg_default_p()][NcCell#method.fg_default_p].* #[inline] pub fn cell_fg_default_p(cell: &NcCell) -> bool { - channels_fg_default_p(cell.channels) + crate::channels_fg_default_p(cell.channels) } /// Is the background [NcChannel] of this [NcCell] using the @@ -165,36 +197,46 @@ pub fn cell_fg_default_p(cell: &NcCell) -> bool { /// /// The "default background color" must generally be used to take advantage of /// terminal-effected transparency. +/// +/// *Method: NcCell.[bg_default_p()][NcCell#method.bg_default_p].* #[inline] pub fn cell_bg_default_p(cell: &NcCell) -> bool { - channels_bg_default_p(cell.channels) + crate::channels_bg_default_p(cell.channels) } // Palette --------------------------------------------------------------------- /// Is the foreground [NcChannel] of this [NcCell] using an /// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color? +/// +/// *Method: NcCell.[fg_palindex_p()][NcCell#method.fg_palindex_p].* #[inline] pub fn cell_fg_palindex_p(cell: &NcCell) -> bool { - channels_fg_palindex_p(cell.channels) + crate::channels_fg_palindex_p(cell.channels) } /// Is the background [NcChannel] of this [NcCell] using an /// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color? +/// +/// *Method: NcCell.[bg_palindex_p()][NcCell#method.bg_palindex_p].* #[inline] pub fn cell_bg_palindex_p(cell: &NcCell) -> bool { - channels_bg_palindex_p(cell.channels) + crate::channels_bg_palindex_p(cell.channels) } /// Gets the [NcPaletteIndex] of the foreground [NcChannel] of the [NcCell]. +/// +/// *Method: NcCell.[fg_palindex()][NcCell#method.fg_palindex].* #[inline] -pub fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex { +pub const fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex { ((cell.channels & 0xff00000000 as NcChannelPair) >> 32) as NcPaletteIndex } /// Gets the [NcPaletteIndex] of the background [NcChannel] of the [NcCell]. +/// +/// *Method: NcCell.[bg_palindex()][NcCell#method.bg_palindex].* #[inline] -pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex { +pub const fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex { (cell.channels & 0xff) as NcPaletteIndex } @@ -203,6 +245,8 @@ pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex { /// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE], /// and clears out [NCCELL_FGDEFAULT_MASK]. /// +/// *Method: NcCell.[set_fg_palindex()][NcCell#method.set_fg_palindex].* +// // NOTE: unlike the original C function, this one can't fail #[inline] pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { @@ -218,6 +262,8 @@ pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { /// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE], /// and clears out [NCCELL_BGDEFAULT_MASK]. /// +/// *Method: NcCell.[set_bg_palindex()][NcCell#method.set_bg_palindex].* +// // NOTE: unlike the original C function, this one can't fail #[inline] pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { @@ -231,19 +277,25 @@ pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { // Styles ---------------------------------------------------------------------- /// Extracts the [NcStyleMask] bits from an [NcCell]. +/// +/// *Method: NcCell.[cell_styles()][NcCell#method.cell_styles].* #[inline] -pub fn cell_styles(cell: &NcCell) -> NcStyleMask { +pub const fn cell_styles(cell: &NcCell) -> NcStyleMask { cell.stylemask } /// Adds the specified [NcStyleMask] bits to an [NcCell]'s existing spec., /// whether they're actively supported or not. +/// +/// *Method: NcCell.[styles_on()][NcCell#method.styles_on].* #[inline] pub fn cell_styles_on(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask |= stylebits & NCSTYLE_MASK as u16; } /// Removes the specified [NcStyleMask] bits from an [NcCell]'s existing spec. +/// +/// *Method: NcCell.[styles_off()][NcCell#method.styles_off].* #[inline] pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask &= !(stylebits & NCSTYLE_MASK as u16); @@ -251,6 +303,8 @@ pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) { /// Sets *just* the specified [NcStyleMask] bits for an [NcCell], /// whether they're actively supported or not. +/// +/// *Method: NcCell.[styles_set()][NcCell#method.styles_set].* #[inline] pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask = stylebits & NCSTYLE_MASK as u16; @@ -259,45 +313,79 @@ pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) { // Chars ----------------------------------------------------------------------- /// Does the [NcCell] contain an East Asian Wide codepoint? -// NOTE: remove casting when fixed: -// https://github.com/rust-lang/rust-bindgen/issues/1875 +/// +/// *Method: NcCell.[double_wide_p()][NcCell#method.double_wide_p].* +// +// REMAINDER: remove casting when fixed: +// Waiting for: https://github.com/rust-lang/rust-bindgen/issues/1875 #[inline] -pub fn cell_double_wide_p(cell: &NcCell) -> bool { +pub const fn cell_double_wide_p(cell: &NcCell) -> bool { (cell.channels & NCCELL_WIDEASIAN_MASK as NcChannelPair) != 0 } /// Is this the right half of a wide character? +/// +/// *Method: NcCell.[wide_right_p()][NcCell#method.wide_right_p].* #[inline] -pub fn cell_wide_right_p(cell: &NcCell) -> bool { +pub const fn cell_wide_right_p(cell: &NcCell) -> bool { cell_double_wide_p(cell) && cell.gcluster == 0 } /// Is this the left half of a wide character? +/// +/// *Method: NcCell.[wide_left_p()][NcCell#method.wide_left_p].* #[inline] -pub fn cell_wide_left_p(cell: &NcCell) -> bool { +pub const fn cell_wide_left_p(cell: &NcCell) -> bool { cell_double_wide_p(cell) && cell.gcluster != 0 } /// Loads a 7-bit char into the [NcCell]. +/// +/// *Method: NcCell.[load_char()][NcCell#method.load_char].* +// // NOTE: Unlike the original C function this doesn't return anything. -// REMINDER: remove casting for NCCELL_WIDEASIAN_MASK when fixed: https://github.com/rust-lang/rust-bindgen/issues/1875 +// REMINDER: remove casting for NCCELL_WIDEASIAN_MASK when fixed: +// Waiting for: https://github.com/rust-lang/rust-bindgen/issues/1875 #[inline] pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i32 */ { unsafe { - cell_release(plane, cell); + crate::cell_release(plane, cell); } cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannelPair | NCCELL_NOBACKGROUND_MASK); cell.gcluster = ch as u32; + + /* TODO new version: + + char gcluster[2]; + gcluster[0] = ch; + gcluster[1] = '\0'; + return cell_load(n, c, gcluster); + */ } +// TODO: +// // Load a UTF-8 encoded EGC of up to 4 bytes into the cell `c`. +// static inline int +// cell_load_egc32(struct ncplane* n, cell* c, uint32_t egc){ +// char gcluster[sizeof(egc) + 1]; +// egc = egc.to_le(); +// memcpy(gcluster, &egc, sizeof(egc)); +// gcluster[4] = '\0'; +// return cell_load(n, c, gcluster); +// } + /// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple or complex. /// /// The result is not tied to the [NcPlane], and persists across erases and destruction. +/// +/// *Method: NcCell.[strdup()][NcCell#method.strdup].* #[inline] pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcEgc { - core::char::from_u32(unsafe { libc::strdup(cell_extended_gcluster(plane, cell)) } as i32 as u32) - .expect("wrong char") + core::char::from_u32( + unsafe { libc::strdup(crate::cell_extended_gcluster(plane, cell)) } as i32 as u32, + ) + .expect("wrong char") // Unsafer option B (maybe faster, TODO: bench): // unsafe { @@ -309,6 +397,8 @@ pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcEgc { /// Saves the [NcStyleMask] and the [NcChannelPair], /// and returns the [NcEgc], of an [NcCell]. +/// +/// *Method: NcCell.[extract()][NcCell#method.extract].* #[inline] pub fn cell_extract( plane: &NcPlane, @@ -329,6 +419,9 @@ pub fn cell_extract( /// /// The actual egcpool index needn't be the same--indeed, the planes needn't even /// be the same. Only the expanded NcEgc must be equal. The NcEgc must be bit-equal; +/// +/// *Method: NcCell.[compare()][NcCell#method.compare].* +// // NOTE: FIXME: it would probably be better to test whether they're Unicode-equal #[inline] pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell) -> bool { @@ -340,25 +433,29 @@ pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCel } unsafe { strcmp( - cell_extended_gcluster(plane1, cell1), - cell_extended_gcluster(plane2, cell2), + crate::cell_extended_gcluster(plane1, cell1), + crate::cell_extended_gcluster(plane2, cell2), ) != 0 } } /// Initializes (zeroes out) an [NcCell]. +/// +/// *Method: NcCell.[init()][NcCell#method.init].* #[inline] pub fn cell_init(cell: &mut NcCell) { *cell = unsafe { core::mem::zeroed() } } -/// Same as [cell_load], plus blasts the styling with 'style' and 'channels'. +/// Same as [cell_load][crate::cell_load], plus blasts the styling with +/// `style` and `channels`. /// -/// - Breaks the UTF-8 string in 'gcluster' down, setting up the cell 'cell'. -/// - Returns the number of bytes copied out of 'gcluster', or -1 on failure. +/// - Breaks the UTF-8 string in `gcluster` down, setting up the cell `cell`. +/// - Returns the number of bytes copied out of `gcluster`, or -1 on failure. /// - The styling of the cell is left untouched, but any resources are released. -/// - Blasts the styling with 'style' and 'channels'. +/// - Blasts the styling with `style` and `channels`. /// +/// *Method: NcCell.[prime()][NcCell#method.prime].* pub fn cell_prime( plane: &mut NcPlane, cell: &mut NcCell, @@ -368,7 +465,7 @@ pub fn cell_prime( ) -> NcResult { cell.stylemask = style; cell.channels = channels; - unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) } + unsafe { crate::cell_load(plane, cell, gcluster as u32 as *const i8) } } /// Loads up six cells with the [NcEgc]s necessary to draw a box. @@ -378,6 +475,7 @@ pub fn cell_prime( /// On error, any [NcCell]s this function might have loaded before the error /// are [cell_release]d. There must be at least six [NcEgc]s in gcluster. /// +/// *Method: NcCell.[load_box()][NcCell#method.load_box].* pub fn cells_load_box( plane: &mut NcPlane, style: NcStyleMask, diff --git a/rust/src/plane/mod.rs b/rust/src/plane/mod.rs index dd62bf6a0..5dc10f81b 100644 --- a/rust/src/plane/mod.rs +++ b/rust/src/plane/mod.rs @@ -55,16 +55,16 @@ //W ncplane_pulse // ncplane_putchar_stained // ncplane_putc_yx -// X ncplane_putegc_stained -// X ncplane_putegc_yx +// X ncplane_putegc_stained // unneeded +// X ncplane_putegc_yx // unneeded // ncplane_putnstr_aligned // ncplane_putnstr_yx // ncplane_putstr_aligned // ncplane_putstr_stained // ncplane_putstr_yx // ncplane_puttext -// X ncplane_putwegc_stained -// X ncplane_putwstr_stained +// X ncplane_putwegc_stained // unneeded +// X ncplane_putwstr_stained // unneeded // ncplane_qrcode //W ncplane_reparent //W ncplane_reparent_family @@ -82,7 +82,7 @@ //W ncplane_set_bg_palindex //W ncplane_set_bg_rgb //W ncplane_set_bg_rgb8 -// X ncplane_set_bg_rgb8_clipped +// X ncplane_set_bg_rgb8_clipped // unneeded //W# ncplane_set_channels //W# ncplane_set_fchannel //W ncplane_set_fg_alpha @@ -90,7 +90,7 @@ //W ncplane_set_fg_palindex //W ncplane_set_fg_rgb //W ncplane_set_fg_rgb8 -// X ncplane_set_fg_rgb8_clipped +// X ncplane_set_fg_rgb8_clipped // unneeded //W ncplane_set_resizecb //W ncplane_set_scrolling //W ncplane_set_styles @@ -108,7 +108,7 @@ //W ncplane_y //W ncplane_yx // -// functions manually reimplemented: 42 +// functions manually reimplemented: 41 // ------------------------------------------ // (X) wont: 9 // (+) done: 34 / 0 @@ -141,17 +141,17 @@ // + ncplane_putc // + ncplane_putchar // + ncplane_putchar_yx -// X ncplane_putegc +// X ncplane_putegc // unneeded // + ncplane_putnstr //W+ ncplane_putstr -// X ncplane_putwc -// X ncplane_putwc_stained -// X ncplane_putwc_yx -// X ncplane_putwegc -// X ncplane_putwegc_yx -// X ncplane_putwstr -// X ncplane_putwstr_aligned -// X ncplane_putwstr_yx +// X ncplane_putwc // unneeded +// X ncplane_putwc_stained // unneeded +// X ncplane_putwc_yx // unneeded +// X ncplane_putwegc // unneeded +// X ncplane_putwegc_yx // unneeded +// X ncplane_putwstr // unneeded +// X ncplane_putwstr_aligned // unneeded +// X ncplane_putwstr_yx // unneeded //W# ncplane_resize_simple // + ncplane_rounded_box // + ncplane_rounded_box_sized