From 1206a281ecf3cc8060131ed018b4287fcae6b719 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Wed, 2 Dec 2020 02:12:12 +0100 Subject: [PATCH] rust: keep refactoring and improving docs - remove the use of inline code markings inside rustdoc [`links`], because they are too visually distracting. - Use descriptive language in the doc comments, instead of imperative. - Rename NcChannels to NcChannelPair, for improved clarity. - Improve more comments, add inner links. - Improve some tests. - separate tests and constructors into submodules for cells and channels --- rust/src/bindings.rs | 38 ++----- rust/src/cells/constructors.rs | 15 +-- rust/src/cells/mod.rs | 182 ++++++++++++++++----------------- rust/src/cells/tests.rs | 10 +- rust/src/channel/mod.rs | 179 +++++++++++++++++--------------- rust/src/channel/tests.rs | 12 +-- rust/src/input.rs | 2 +- rust/src/lib.rs | 6 +- rust/src/notcurses/mod.rs | 7 +- rust/src/palette.rs | 4 +- rust/src/pixel.rs | 2 +- rust/src/plane/mod.rs | 32 +++--- rust/src/types/cell.rs | 26 ++--- rust/src/types/channel.rs | 10 +- rust/src/types/mod.rs | 4 +- rust/src/visual.rs | 2 +- rust/src/widgets/menu.rs | 8 +- rust/tests/notcurses.rs | 2 +- 18 files changed, 272 insertions(+), 269 deletions(-) diff --git a/rust/src/bindings.rs b/rust/src/bindings.rs index 87d1d0f96..4ec5927dc 100644 --- a/rust/src/bindings.rs +++ b/rust/src/bindings.rs @@ -1,15 +1,9 @@ -//! Curated re-exports of the [`bindgen`] bindings +//! A selection of the [bindgen] bindings intended to be used directly. //! -//! The full list of bindings is under the -//! [`bindgen`] submodule +//! The full list of bindings is under the [bindgen] submodule //! -//! This module publicly re-exports bindgen generated functions and constants, -//! while privately re-exporting other functions, constants and all structs -//! in order to wrap them up or crate new aliases for them. -// -// WARNING: DO NOT EXECUTE RUSTFMT ON THIS FILE. -// Custom formatting permits easier maintenance. -// +//! This module publicly re-exports bindgen generated functions and constants +//! for their direct usage. // [clippy & bindgen](https://github.com/rust-lang/rust-bindgen/issues/1470) #[allow(clippy::all)] @@ -17,20 +11,15 @@ pub mod bindgen { //! Automatically generated Rust FFI bindings //! //! All of the notcurses functions and some of the constants are reexported - //! by the [`bindings`][crate::bindings] module. - //! While the structs, enums and some other constants are type aliased in - //! the [`types`][crate::types] module, in order to follow the - //! Rust API Guidelines as much as possible. + //! by the private `bindings` module, while the structs, enums and some + //! other constants are type aliased in the `types` private module. //! include!(concat!(env!("OUT_DIR"), "/bindings.rs")); } // Miscellaneous --------------------------------------------------------------- -pub(crate) use bindgen::{ - // structs - timespec, -}; +pub(crate) use bindgen::timespec; #[doc(inline)] pub use bindgen::{ @@ -191,7 +180,6 @@ pub use bindgen::{ ncdirect_vline_interp, }; - // ncfadectx ------------------------------------------------------------------- // // already wrapped: @@ -293,10 +281,7 @@ pub use bindgen::{ // IPREFIXSTRLEN, #[doc(inline)] -pub use bindgen::{ - // structs - ncmetric -}; +pub use bindgen::ncmetric; // ncmultiselector ------------------------------------------------------------- // @@ -323,8 +308,8 @@ pub use bindgen::{ pub use bindgen::{ // functions ncpile_create, - ncpile_render, ncpile_rasterize, + ncpile_render, }; // ncplane --------------------------------------------------------------------- @@ -722,10 +707,7 @@ pub use bindgen::{ // sig ------------------------------------------------------------------------- -pub(crate) use bindgen::{ - // type definitions - sigset_t, -}; +pub(crate) use bindgen::sigset_t; #[doc(inline)] pub use bindgen::{ diff --git a/rust/src/cells/constructors.rs b/rust/src/cells/constructors.rs index 83a97f153..ff127b705 100644 --- a/rust/src/cells/constructors.rs +++ b/rust/src/cells/constructors.rs @@ -1,11 +1,12 @@ -//! Handy [`NcCell`] constructors +//! Handy [NcCell] constructors -pub use crate::{NcCell, NcChannels, NcCharBackstop, NcStyleMask}; +pub use crate::{NcCell, NcChannelPair, NcCharBackstop, NcStyleMask}; impl NcCell { - /// [`NcCell`] constructor expecting [`char`], [`NcStyleMask`] and [`NcChannels`] + /// [NcCell] constructor expecting [char], [NcStyleMask] and + /// [NcChannelPair] #[inline] - pub const fn new(ch: char, stylemask: NcStyleMask, channels: NcChannels) -> Self { + pub const fn new(ch: char, stylemask: NcStyleMask, channels: NcChannelPair) -> Self { NcCell { gcluster: ch as u32, gcluster_backstop: 0 as NcCharBackstop, @@ -15,13 +16,13 @@ impl NcCell { } } - /// [`NcCell`] simple constructor just expecting a [`char`] + /// [NcCell] simple constructor just expecting a [char] #[inline] pub const fn with_char(ch: char) -> Self { - Self::new(ch, 0 as NcStyleMask, 0 as NcChannels) + Self::new(ch, 0 as NcStyleMask, 0 as NcChannelPair) } - /// [`NcCell`] simple constructor for an empty cell + /// [NcCell] simple constructor for an empty cell #[inline] pub const fn new_blank() -> Self { Self::with_char(0 as char) diff --git a/rust/src/cells/mod.rs b/rust/src/cells/mod.rs index bd556f2b8..8ba42616e 100644 --- a/rust/src/cells/mod.rs +++ b/rust/src/cells/mod.rs @@ -1,4 +1,4 @@ -//! [`NcCell`] `cell*_*` static functions reimplementations +//! [NcCell] `cell*_*` static functions reimplementations // functions already exported by bindgen : 6 // ----------------------------------------- @@ -73,25 +73,18 @@ use crate::{ 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, - types::{ - NcAlphaBits, NcCell, NcChannel, NcChannels, NcChar, NcColor, 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, + NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcChar, NcColor, 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_load(), plus blast the styling with 'style' and 'channels'. +/// Same as [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. /// - The styling of the cell is left untouched, but any resources are released. -/// - blast the styling with 'style' and 'channels' -/// -/// # Safety -/// -/// Until we can change gcluster to a safer type, this function will remain unsafe +/// - Blasts the styling with 'style' and 'channels'. /// #[allow(unused_unsafe)] pub unsafe fn cell_prime( @@ -99,29 +92,25 @@ pub unsafe fn cell_prime( cell: &mut NcCell, gcluster: NcChar, style: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ) -> NcResult { cell.stylemask = style; cell.channels = channels; unsafe { cell_load(plane, cell, gcluster as u32 as *const i8) } } -/// load up six cells with the [`NcChar`]s necessary to draw a box. -/// -/// returns 0 on success, -1 on error. -/// -/// on error, any cells this function might have loaded before the error -/// are cell_release()d. There must be at least six `NcChar`s in gcluster. +/// Loads up six cells with the [NcChar]s necessary to draw a box. /// -/// # Safety +/// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error. /// -/// Until we can change gcluster to a safer type, this function will remain unsafe +/// On error, any [NcCell]s this function might have loaded before the error +/// are [cell_release]d. There must be at least six [NcChar]s in gcluster. /// #[allow(unused_unsafe)] pub unsafe fn cells_load_box( plane: &mut NcPlane, style: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ul: &mut NcCell, ur: &mut NcCell, ll: &mut NcCell, @@ -182,67 +171,70 @@ pub unsafe fn cells_load_box( NCRESULT_ERR } -/// Initialize (zero out) the [`NcCell`]. +/// Initializes (zeroes out) an [NcCell]. #[inline] pub fn cell_init(cell: &mut NcCell) { *cell = unsafe { core::mem::zeroed() } } -/// Set *only* the specified [`NcStyleMask`] bits for the [`NcCell`], +/// Sets *just* the specified [NcStyleMask] bits for an [NcCell], /// whether they're actively supported or not. #[inline] pub fn cell_styles_set(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask = stylebits & NCSTYLE_MASK as u16; } -/// Extract the [`NcStyleMask`] bits from the [`NcCell`]. +/// Extracts the [NcStyleMask] bits from an [NcCell]. #[inline] pub fn cell_styles(cell: &NcCell) -> NcStyleMask { cell.stylemask } -/// Add the specified [`NcStyleMask`] bits to the [`NcCell`]'s existing spec, +/// Adds the specified [NcStyleMask] bits to an [NcCell]'s existing spec., /// whether they're actively supported or not. #[inline] pub fn cell_styles_on(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask |= stylebits & NCSTYLE_MASK as u16; } -/// Remove the specified [`NcStyleMask`] bits from the cell's existing spec. +/// Removes the specified [NcStyleMask] bits from an [NcCell]'s existing spec. #[inline] pub fn cell_styles_off(cell: &mut NcCell, stylebits: NcStyleMask) { cell.stylemask &= !(stylebits & NCSTYLE_MASK as u16); } -/// Use the default color for the foreground [`NcChannel`] of this [`NcCell`]. +/// Indicates to use the "default color" for the **foreground** [NcChannel] +/// of an [NcCell]. #[inline] pub fn cell_set_fg_default(cell: &mut NcCell) { channels_set_fg_default(&mut cell.channels); } -/// Use the default color for the background [`NcChannel`] of this [`NcCell`]. +/// Indicates to use the "default color" for the **background** [NcChannel] +/// of an [NcCell]. #[inline] pub fn cell_set_bg_default(cell: &mut NcCell) { channels_set_bg_default(&mut cell.channels); } -/// Set the foreground [`NcAlphaBits`]. +/// Sets the foreground [NcAlphaBits] of an [NcCell]. #[inline] pub fn cell_set_fg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) { channels_set_fg_alpha(&mut cell.channels, alpha); } -/// Set the background [`NcAlphaBits`]. +/// Sets the background [NcAlphaBits] of an [NcCell]. #[inline] pub fn cell_set_bg_alpha(cell: &mut NcCell, alpha: NcAlphaBits) { channels_set_bg_alpha(&mut cell.channels, alpha); } -/// Does the [`NcCell`] contain an East Asian Wide codepoint? -// NOTE: remove casting when fixed: https://github.com/rust-lang/rust-bindgen/issues/1875 +/// Does the [NcCell] contain an East Asian Wide codepoint? +// NOTE: remove casting when fixed: +// https://github.com/rust-lang/rust-bindgen/issues/1875 #[inline] pub fn cell_double_wide_p(cell: &NcCell) -> bool { - (cell.channels & NCCELL_WIDEASIAN_MASK as NcChannels) != 0 + (cell.channels & NCCELL_WIDEASIAN_MASK as NcChannelPair) != 0 } /// Is this the right half of a wide character? @@ -257,8 +249,11 @@ pub fn cell_wide_left_p(cell: &NcCell) -> bool { cell_double_wide_p(cell) && cell.gcluster != 0 } -/// copy the UTF8-encoded NcChar out of the cell, whether simple or complex. the -/// result is not tied to the ncplane, and persists across erases / destruction. +/// Copies the UTF8-encoded [NcChar] out of the cell, whether simple +/// or complex. +/// +/// The result is not tied to the [NcPlane], and persists +/// across erases and destruction. #[inline] pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcChar { core::char::from_u32(unsafe { libc::strdup(cell_extended_gcluster(plane, cell)) } as i32 as u32) @@ -270,14 +265,14 @@ pub fn cell_strdup(plane: &NcPlane, cell: &NcCell) -> NcChar { // } } -/// Extract the three elements of a cell: save the [`NcStyleMask`] and -/// [`NcChannels`], and return the [`NcChar`]. +/// Saves the [NcStyleMask] and [NcChannelPair] and returns the [NcChar] +/// (the three elements of an [NcCell]. #[inline] pub fn cell_extract( plane: &NcPlane, cell: &NcCell, stylemask: &mut NcStyleMask, - channels: &mut NcChannels, + channels: &mut NcChannelPair, ) -> NcChar { if *stylemask != 0 { *stylemask = cell.stylemask; @@ -288,7 +283,7 @@ pub fn cell_extract( cell_strdup(plane, cell) } -/// Returns true if the two cells are distinct [`NcChar`]s, attributes, or channels +/// Returns true if the two cells are distinct [NcChar]s, attributes, or channels /// /// The actual egcpool index needn't be the same--indeed, the planes needn't even /// be the same. Only the expanded NcChar must be equal. The NcChar must be bit-equal; @@ -309,71 +304,73 @@ pub fn cellcmp(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCel } } -/// +/// Loads a 7-bit char into the [NcCell]. // NOTE: remove casting for NCCELL_WIDEASIAN_MASK when fixed: https://github.com/rust-lang/rust-bindgen/issues/1875 #[inline] pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcChar) -> i32 { unsafe { cell_release(plane, cell); } - cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannels | NCCELL_NOBACKGROUND_MASK); + cell.channels &= !(NCCELL_WIDEASIAN_MASK as NcChannelPair | NCCELL_NOBACKGROUND_MASK); cell.gcluster = ch as u32; 1 } -/// Extract the 32-bit background channel from an [`NcCell`]. +/// Extracts the 32-bit background [NcChannel] from an [NcCell]. #[inline] pub fn cell_bchannel(cell: &NcCell) -> NcChannel { channels_bchannel(cell.channels) } -/// Extract the 32-bit foreground channel from an [`NcCell`]. +/// Extracts the 32-bit foreground [NcChannel] from an [NcCell]. #[inline] pub fn cell_fchannel(cell: &NcCell) -> NcChannel { channels_fchannel(cell.channels) } -/// Set the 32-bit background [`NcChannel`] of an [`NcCell`] and return the -/// [`NcChannels`]. +/// Sets the 32-bit background [NcChannel] of an [NcCell] and returns its new +/// [NcChannelPair]. #[inline] -pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannels { +pub fn cell_set_bchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair { channels_set_bchannel(&mut cell.channels, channel) } -/// Set the 32-bit foreground [`NcChannel`] of an [`NcCell`] and return the -/// [`NcChannels`]. +/// Sets the 32-bit foreground [NcChannel] of an [NcCell] and returns its new +/// [NcChannelPair]. #[inline] -pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannels { +pub fn cell_set_fchannel(cell: &mut NcCell, channel: NcChannel) -> NcChannelPair { channels_set_fchannel(&mut cell.channels, channel) } -/// Extract 24 bits of foreground [`NcRgb`] from the [`NcCell`] (shifted to LSBs). +/// Extracts the foreground [NcRgb] 24-bit value from an [NcCell] +/// (shifted to LSBs). #[inline] pub fn cell_fg_rgb(cell: &NcCell) -> NcRgb { channels_fg_rgb(cell.channels) } -/// Extract 24 bits of background RGB from the [`NcCell`] (shifted to LSBs). +/// Extracts the background [NcRgb] 24-bit value from an [NcCell] +/// (shifted to LSBs). #[inline] pub fn cell_bg_rgb(cell: &NcCell) -> NcRgb { channels_bg_rgb(cell.channels) } -/// Extract 2 bits of foreground alpha from the [`NcCell`] (shifted to LSBs). +/// Extracts the foreground [NcAlphaBits] from an [NcCell] (shifted to LSBs). #[inline] pub fn cell_fg_alpha(cell: &NcCell) -> NcAlphaBits { channels_fg_alpha(cell.channels) } -/// Extract 2 bits of background alpha from the [`NcCell`] (shifted to LSBs). +/// Extracts the background [NcAlphaBits] from an [NcCell] (shifted to LSBs). #[inline] pub fn cell_bg_alpha(cell: &NcCell) -> NcAlphaBits { channels_bg_alpha(cell.channels) } -/// Extract 24 bits of foreground [`NcRgb`] from the [`NcCell`] and save split -/// into [`NcColor`] components. Also return the corresponding [`NcChannel`] -/// (which can have some extra bits set). +/// Extracts the foreground [NcRgb] 24-bit value from an [NcCell] and saves it +/// split into three [NcColor] 8-bit components. Also returns the corresponding +/// [NcChannel] (which can have some extra bits set). #[inline] pub fn cell_fg_rgb8( cell: &NcCell, @@ -384,9 +381,9 @@ pub fn cell_fg_rgb8( channels_fg_rgb8(cell.channels, red, green, blue) } -/// Extract 24 bits of background [`NcRgb`] from the [`NcCell`] and save split -/// into [`NcColor`] components. Also return the corresponding [`NcChannel`] -/// (which can have some extra bits set). +/// Extracts the background [NcRgb] 24-bit value from an [NcCell] and saves it +/// split into three [NcColor] 8-bit components. Also returns the corresponding +/// [NcChannel] (which can have some extra bits set). #[inline] pub fn cell_bg_rgb8( cell: &NcCell, @@ -397,23 +394,24 @@ pub fn cell_bg_rgb8( channels_bg_rgb8(cell.channels, red, green, blue) } -/// Set the RGB [`NcColor`] components for the foreground [`NcChannel`] of this -/// [`NcCell`], and mark it as not using the default color. +/// Sets the RGB [NcColor] components for the foreground [NcChannel] of an +/// [NcCell], and marks it as not using the default color. #[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); } -/// Set the [`NcRgb`] 24-bit value for the foreground [`NcChannel`] of this -/// [`NcCell`], and mark it as not using the default color. +/// Sets the 24-bit [NcRgb] value for the foreground [NcChannel] of an +/// [NcCell], and marks it as not using the default color. #[inline] pub fn cell_set_fg_rgb(cell: &mut NcCell, rgb: NcRgb) { channels_set_fg_rgb(&mut cell.channels, rgb); } -/// Set the cell's foreground [`NcPaletteIndex`], set the foreground palette index -/// bit ([`NCCELL_FG_PALETTE`]), set it foreground-opaque ([`NCCELL_ALPHA_OPAQUE`]), -/// and clear the foreground default color bit ([`NCCELL_FGDEFAULT_MASK`]). +/// Sets an [NcCell]'s foreground [NcPaletteIndex]. +/// +/// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE], +/// and clears out [NCCELL_FGDEFAULT_MASK]. /// // NOTE: unlike the original C function, this one can't fail #[inline] @@ -421,67 +419,67 @@ pub fn cell_set_fg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { cell.channels |= NCCELL_FGDEFAULT_MASK; cell.channels |= NCCELL_FG_PALETTE; cell_set_fg_alpha(cell, NCCELL_ALPHA_OPAQUE); - cell.channels &= 0xff000000ffffffff as NcChannels; - cell.channels |= (index as NcChannels) << 32; + cell.channels &= 0xff000000ffffffff as NcChannelPair; + cell.channels |= (index as NcChannelPair) << 32; } -/// Return the [`NcPaletteIndex`] of the foreground [`NcChannel`] of the -/// [`NcCell`] +/// Returns the [NcPaletteIndex] of the foreground [NcChannel] of the +/// [NcCell] #[inline] pub fn cell_fg_palindex(cell: &NcCell) -> NcPaletteIndex { - ((cell.channels & 0xff00000000 as NcChannels) >> 32) as NcPaletteIndex + ((cell.channels & 0xff00000000 as NcChannelPair) >> 32) as NcPaletteIndex } -/// Set the RGB [`NcColor`] components for the background [`NcChannel`] of this -/// [`NcCell`], and mark it as not using the default color. +/// Sets the [NcColor] 8-bit RGB components of the background [NcChannel] +/// of the [NcCell], and marks it as not using the "default color". #[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); } -/// Set the [`NcRgb`] 24-bit value for the background [`NcChannel`] of this -/// [`NcCell`], and mark it as not using the default color. +/// Sets the [NcRgb] 24-bit value for the background [NcChannel] of this +/// [NcCell], and marks it as not using the default color. #[inline] pub fn cell_set_bg_rgb(cell: &mut NcCell, rgb: NcRgb) { channels_set_bg_rgb(&mut cell.channels, rgb); } -/// Set the cell's background [`NcPaletteIndex`], set the background palette index -/// bit ([`NCCELL_BG_PALETTE`]), set it background-opaque ([`NCCELL_ALPHA_OPAQUE`]), -/// and clear the background default color bit ([`NCCELL_BGDEFAULT_MASK`]). +/// Sets an [NcCell]'s background [NcPaletteIndex]. +/// +/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE], +/// and clears out [NCCELL_BGDEFAULT_MASK]. /// // NOTE: unlike the original C function, this one can't fail #[inline] pub fn cell_set_bg_palindex(cell: &mut NcCell, index: NcPaletteIndex) { - cell.channels |= NCCELL_BGDEFAULT_MASK as NcChannels; - cell.channels |= NCCELL_BG_PALETTE as NcChannels; + cell.channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair; + cell.channels |= NCCELL_BG_PALETTE as NcChannelPair; cell_set_bg_alpha(cell, NCCELL_ALPHA_OPAQUE); cell.channels &= 0xffffffffff000000; - cell.channels |= index as NcChannels; + cell.channels |= index as NcChannelPair; } -/// Return the [`NcPaletteIndex`] of the background [`NcChannel`] of the -/// [`NcCell`] +/// Returns the [NcPaletteIndex] of the background [NcChannel] of the [NcCell] #[inline] pub fn cell_bg_palindex(cell: &NcCell) -> NcPaletteIndex { (cell.channels & 0xff) as NcPaletteIndex } -/// Is the foreground [`NcChannel`] of this [`NcCell`] using the +/// Is the foreground [NcChannel] of this [NcCell] using the /// "default foreground color"? #[inline] pub fn cell_fg_default_p(cell: &NcCell) -> bool { channels_fg_default_p(cell.channels) } -/// Is the foreground [`NcChannel`] of this [`NcCell`] using an -/// [`NcPaletteIndex`] indexed [`NcPalette`][crate::NcPalette] color? +/// Is the foreground [NcChannel] of this [NcCell] using an +/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color? #[inline] pub fn cell_fg_palindex_p(cell: &NcCell) -> bool { channels_fg_palindex_p(cell.channels) } -/// Is the background [`NcChannel`] of this [`NcCell`] using the +/// Is the background [NcChannel] of this [NcCell] using the /// "default background color"? /// /// The "default background color" must generally be used to take advantage of @@ -491,8 +489,8 @@ pub fn cell_bg_default_p(cell: &NcCell) -> bool { channels_bg_default_p(cell.channels) } -/// Is the background [`NcChannel`] of this [`NcCell`] using an -/// [`NcPaletteIndex`] indexed [`NcPalette`][`crate::NcPalette] color? +/// Is the background [NcChannel] of this [NcCell] using an +/// [NcPaletteIndex] [indexed][NcPaletteIndex] [NcPalette][crate::NcPalette] color? #[inline] pub fn cell_bg_palindex_p(cell: &NcCell) -> bool { channels_bg_palindex_p(cell.channels) diff --git a/rust/src/cells/tests.rs b/rust/src/cells/tests.rs index 55c724837..f75986228 100644 --- a/rust/src/cells/tests.rs +++ b/rust/src/cells/tests.rs @@ -21,10 +21,12 @@ fn channels() { assert_eq![0, crate::cell_fchannel(&c1)]; assert_eq![0, crate::cell_bchannel(&c1)]; - crate::cell_set_fchannel(&mut c1, 0x77112233); - assert_eq![0x77112233, crate::cell_fchannel(&c1)]; - crate::cell_set_bchannel(&mut c1, 0x88445566); - assert_eq![0x88445566, crate::cell_bchannel(&c1)]; + let mut channels = crate::cell_set_fchannel(&mut c1, 0xAA112233); + assert_eq![0xAA112233, crate::cell_fchannel(&c1)]; + assert_eq![0xAA11223300000000, channels]; + channels = crate::cell_set_bchannel(&mut c1, 0xBB445566); + assert_eq![0xBB445566, crate::cell_bchannel(&c1)]; + assert_eq![0xAA112233BB445566, channels]; let c2 = NcCell::new(' ', 0, 0x0011223300445566); assert_eq![0x112233, crate::cell_fchannel(&c2)]; diff --git a/rust/src/channel/mod.rs b/rust/src/channel/mod.rs index 3bdfe202a..d59dfdc98 100644 --- a/rust/src/channel/mod.rs +++ b/rust/src/channel/mod.rs @@ -1,4 +1,4 @@ -//! [`NcChannel`] & [`NcChannels`] `channel*_*` static_function reinmplementations +//! [`NcChannel`] & [`NcChannelPair`] `channel*_*` static fn reimplementations // ----------------------------------------------------------------------------- // - The channel components are u8 instead of u32. @@ -65,31 +65,31 @@ #[cfg(test)] mod tests; -use crate::types::{ - NcAlphaBits, NcChannel, NcChannels, NcColor, NcPaletteIndex, NcRgb, NCCELL_ALPHA_HIGHCONTRAST, - NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK, NCCELL_BG_PALETTE, NCCELL_BG_RGB_MASK, - NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCHANNEL_ALPHA_MASK, +use crate::{ + NcAlphaBits, NcChannel, NcChannelPair, NcColor, NcPaletteIndex, NcRgb, + NCCELL_ALPHA_HIGHCONTRAST, NCCELL_ALPHA_OPAQUE, NCCELL_BGDEFAULT_MASK, NCCELL_BG_PALETTE, + NCCELL_BG_RGB_MASK, NCCELL_FGDEFAULT_MASK, NCCELL_FG_PALETTE, NCCHANNEL_ALPHA_MASK, }; -/// Extract the 8-bit red component from a 32-bit channel. +/// Extracts the [NcColor] 8-bit red component from a 32-bit [NcChannel]. #[inline] -pub fn channel_r(channel: NcChannel) -> NcColor { +pub const fn channel_r(channel: NcChannel) -> NcColor { ((channel & 0xff0000) >> 16) as NcColor } -/// Extract the 8-bit green component from a 32-bit channel. +/// Extracts the [NcColor] 8-bit green component from a 32-bit [NcChannel]. #[inline] -pub fn channel_g(channel: NcChannel) -> NcColor { +pub const fn channel_g(channel: NcChannel) -> NcColor { ((channel & 0x00ff00) >> 8) as NcColor } -/// Extract the 8-bit blue component from a 32-bit channel. +/// Extracts the [NcColor] 8-bit blue component from a 32-bit [NcChannel]. #[inline] -pub fn channel_b(channel: NcChannel) -> NcColor { +pub const fn channel_b(channel: NcChannel) -> NcColor { (channel & 0x0000ff) as NcColor } -/// Extract the three 8-bit R/G/B components from a 32-bit channel. +/// Extracts the three [NcColor] 8-bit RGB components from a 32-bit [NcChannel]. #[inline] pub fn channel_rgb8( channel: NcChannel, @@ -103,27 +103,28 @@ pub fn channel_rgb8( channel } -/// Set the three 8-bit components of a 32-bit channel, and mark it as not using -/// the default color. Retain the other bits unchanged. +/// Sets the three [NcColor] 8-bit components of a 32-bit [NcChannel], and marks +/// it as not using the "default color". Retain the other bits unchanged. #[inline] pub fn channel_set_rgb8(channel: &mut NcChannel, r: NcColor, g: NcColor, b: NcColor) { let rgb: NcRgb = (r as NcChannel) << 16 | (g as NcChannel) << 8 | (b as NcChannel); *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | rgb; } -/// Same as channel_set_rgb8(), but provide an assembled, packed 24 bits of rgb. +/// Sets the [NcRgb] 24-bit RGB value of a 32-bit [NcChannel], and marks it as +/// not using the "default color". Retain the other bits unchanged. #[inline] pub fn channel_set(channel: &mut NcChannel, rgb: NcRgb) { *channel = (*channel & !NCCELL_BG_RGB_MASK) | NCCELL_BGDEFAULT_MASK | (rgb & 0x00ffffff); } -/// Extract the 2-bit alpha component from a 32-bit channel. +/// Extracts the [NcAlphaBits] 2-bit component from a 32-bit [NcChannel]. #[inline] pub fn channel_alpha(channel: NcChannel) -> NcAlphaBits { channel & NCCHANNEL_ALPHA_MASK } -/// Set the 2-bit alpha component of the 32-bit channel. +/// Sets the [NcAlphaBits] 2-bit component of a 32-bit [NcChannel]. #[inline] pub fn channel_set_alpha(channel: &mut NcChannel, alpha: NcAlphaBits) { let alpha_clean = alpha & NCCHANNEL_ALPHA_MASK; @@ -135,88 +136,92 @@ pub fn channel_set_alpha(channel: &mut NcChannel, alpha: NcAlphaBits) { } } -/// Is this channel using the "default color" rather than RGB/palette-indexed? +/// Is this [NcChannel] using the "default color" rather than RGB/palette-indexed? #[inline] pub fn channel_default_p(channel: NcChannel) -> bool { (channel & NCCELL_BGDEFAULT_MASK) == 0 } -/// Is this channel using palette-indexed color rather than RGB? +/// Is this [NcChannel] using palette-indexed color rather than RGB? #[inline] pub fn channel_palindex_p(channel: NcChannel) -> bool { !(channel_default_p(channel) && (channel & NCCELL_BG_PALETTE) == 0) } -/// Mark the channel as using its default color, which also marks it opaque. +/// Marks an [NcChannel] as using its "default color", which also marks it opaque. #[inline] pub fn channel_set_default(channel: &mut NcChannel) -> NcChannel { *channel &= !(NCCELL_BGDEFAULT_MASK | NCCELL_ALPHA_HIGHCONTRAST); *channel } -/// Extract the 32-bit background channel from a channel pair. +/// Extracts the 32-bit background [NcChannel] from a [NcChannelPair]. #[inline] -pub fn channels_bchannel(channels: NcChannels) -> NcChannel { +pub fn channels_bchannel(channels: NcChannelPair) -> NcChannel { (channels & 0xffffffff_u64) as NcChannel } -/// Extract the 32-bit foreground channel from a channel pair. +/// Extracts the 32-bit foreground [NcChannel] from an [NcChannelPair]. #[inline] -pub fn channels_fchannel(channels: NcChannels) -> NcChannel { +pub fn channels_fchannel(channels: NcChannelPair) -> NcChannel { channels_bchannel(channels >> 32) } -/// Set the 32-bit background channel of a channel pair. +/// Sets the 32-bit background [NcChannel] of an [NcChannelPair]. #[inline] -pub fn channels_set_bchannel(channels: &mut NcChannels, bchannel: NcChannel) -> NcChannels { +pub fn channels_set_bchannel(channels: &mut NcChannelPair, bchannel: NcChannel) -> NcChannelPair { *channels = (*channels & 0xffffffff00000000_u64) | bchannel as u64; *channels } -/// Set the 32-bit foreground channel of a channel pair. +/// Sets the 32-bit foreground [NcChannel] of an [NcChannelPair]. #[inline] -pub fn channels_set_fchannel(channels: &mut NcChannels, fchannel: NcChannel) -> NcChannels { +pub fn channels_set_fchannel(channels: &mut NcChannelPair, fchannel: NcChannel) -> NcChannelPair { *channels = (*channels & 0xffffffff_u64) | (fchannel as u64) << 32; *channels } -/// Combine two channels into a channel pair. +/// Combines two [NcChannel]s into a [NcChannelPair]. #[inline] -pub fn channels_combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannels { - let mut channels: NcChannels = 0; +pub fn channels_combine(fchannel: NcChannel, bchannel: NcChannel) -> NcChannelPair { + let mut channels: NcChannelPair = 0; channels_set_fchannel(&mut channels, fchannel); channels_set_bchannel(&mut channels, bchannel); channels } -/// Extract 24 bits of foreground RGB from 'channels', shifted to LSBs. +/// Extracts the foreground [NcRgb] 24-bit value from an [NcChannelPair], +/// shifted to LSBs. #[inline] -pub fn channels_fg_rgb(channels: NcChannels) -> NcChannel { +pub fn channels_fg_rgb(channels: NcChannelPair) -> NcChannel { channels_fchannel(channels) & NCCELL_BG_RGB_MASK } -/// Extract 24 bits of background RGB from 'channels', shifted to LSBs. +/// Extracts the background [NcRgb] 24-bit value from an [NcChannelPair], +/// shifted to LSBs. #[inline] -pub fn channels_bg_rgb(channels: NcChannels) -> NcChannel { +pub fn channels_bg_rgb(channels: NcChannelPair) -> NcChannel { channels_bchannel(channels) & NCCELL_BG_RGB_MASK } -/// Extract 2 bits of foreground alpha from 'channels', shifted to LSBs. +/// Extracts the foreground [NcAlphabits] from an [NcChannelPair], shifted to LSBs. #[inline] -pub fn channels_fg_alpha(channels: NcChannels) -> NcAlphaBits { +pub fn channels_fg_alpha(channels: NcChannelPair) -> NcAlphaBits { channel_alpha(channels_fchannel(channels)) } -/// Extract 2 bits of background alpha from 'channels', shifted to LSBs. +/// Extracts the background [NcAlphabits] from an [NcChannelPair], shifted to LSBs. #[inline] -pub fn channels_bg_alpha(channels: NcChannels) -> NcAlphaBits { +pub fn channels_bg_alpha(channels: NcChannelPair) -> NcAlphaBits { channel_alpha(channels_bchannel(channels)) } -/// Extract 24 bits of foreground RGB from 'channels', split into subchannels. +/// Extracts the foreground [NcRgb] 24-bit value from an [NcChannelPair], and +/// saves it split into three [NcColor] 8-bit components. Also returns the +/// corresponding [NcChannel] (which can have some extra bits set). #[inline] pub fn channels_fg_rgb8( - channels: NcChannels, + channels: NcChannelPair, r: &mut NcColor, g: &mut NcColor, b: &mut NcColor, @@ -224,10 +229,12 @@ pub fn channels_fg_rgb8( channel_rgb8(channels_fchannel(channels), r, g, b) } -/// Extract 24 bits of background RGB from 'channels', split into subchannels. +/// Extracts the background [NcRgb] 24-bit value from an [NcChannelPair], and +/// saves it split into three [NcColor] 8-bit components. Also returns the +/// corresponding [NcChannel] (which can have some extra bits set). #[inline] pub fn channels_bg_rgb8( - channels: NcChannels, + channels: NcChannelPair, r: &mut NcColor, g: &mut NcColor, b: &mut NcColor, @@ -235,51 +242,53 @@ pub fn channels_bg_rgb8( channel_rgb8(channels_bchannel(channels), r, g, b) } -/// Set the r, g, and b channels for the foreground component of this 64-bit -/// 'channels' variable, and mark it as not using the default color. +/// Sets the RGB [NcColor] components for the foreground [NcChannel] of an +/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color". #[inline] -pub fn channels_set_fg_rgb8(channels: &mut NcChannels, r: NcColor, g: NcColor, b: NcColor) { +pub fn channels_set_fg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor, b: NcColor) { let mut channel = channels_fchannel(*channels); channel_set_rgb8(&mut channel, r, g, b); *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64; } -/// Same as channels_set_fg_rgb8 but set an assembled 24 bit channel at once. +/// Sets the [NcRgb] 24-bit value for the foreground [NcChannel] of an +/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color". #[inline] -pub fn channels_set_fg_rgb(channels: &mut NcChannels, rgb: NcRgb) { +pub fn channels_set_fg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) { let mut channel = channels_fchannel(*channels); channel_set(&mut channel, rgb); *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64; } -/// Set the r, g, and b channels for the background component of this 64-bit -/// 'channels' variable, and mark it as not using the default color. +/// Sets the RGB [NcColor] components for the background [NcChannel] of an +/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color". #[inline] -pub fn channels_set_bg_rgb8(channels: &mut NcChannels, r: NcColor, g: NcColor, b: NcColor) { +pub fn channels_set_bg_rgb8(channels: &mut NcChannelPair, r: NcColor, g: NcColor, b: NcColor) { let mut channel = channels_bchannel(*channels); channel_set_rgb8(&mut channel, r, g, b); channels_set_bchannel(channels, channel); } -/// Same as channels_set_bg_rgb8 but set an assembled 24 bit channel at once. +/// Sets the [NcRgb] 24-bit value for the background [NcChannel] of an +/// [NcChannelPair] 64-bit variable, and marks it as not using the "default color". #[inline] -pub fn channels_set_bg_rgb(channels: &mut NcChannels, rgb: NcRgb) { +pub fn channels_set_bg_rgb(channels: &mut NcChannelPair, rgb: NcRgb) { let mut channel = channels_bchannel(*channels); channel_set(&mut channel, rgb); channels_set_bchannel(channels, channel); } -/// Set the 2-bit alpha component of the foreground channel. +/// Sets the [NcAlphaBits] of the foreground [NcChannel] of an [NcChannelPair]. #[inline] -pub fn channels_set_fg_alpha(channels: &mut NcChannels, alpha: NcAlphaBits) { +pub fn channels_set_fg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) { let mut channel = channels_fchannel(*channels); channel_set_alpha(&mut channel, alpha); - *channels = (channel as NcChannels) << 32 | *channels & 0xffffffff_u64; + *channels = (channel as NcChannelPair) << 32 | *channels & 0xffffffff_u64; } -/// Set the 2-bit alpha component of the background channel. +/// Sets the [NcAlphaBits] of the background [NcChannel] of an [NcChannelPair]. #[inline] -pub fn channels_set_bg_alpha(channels: &mut NcChannels, alpha: NcAlphaBits) { +pub fn channels_set_bg_alpha(channels: &mut NcChannelPair, alpha: NcAlphaBits) { let mut alpha_clean = alpha; if alpha == NCCELL_ALPHA_HIGHCONTRAST { // forbidden for background alpha, so makes it opaque @@ -290,15 +299,16 @@ pub fn channels_set_bg_alpha(channels: &mut NcChannels, alpha: NcAlphaBits) { channels_set_bchannel(channels, channel); } -/// Is the foreground using the "default foreground color"? +/// Is the foreground of an [NcChannelPair] using the "default foreground color"? #[inline] -pub fn channels_fg_default_p(channels: NcChannels) -> bool { +pub fn channels_fg_default_p(channels: NcChannelPair) -> bool { channel_default_p(channels_fchannel(channels)) } -/// Is the foreground using indexed palette color? +/// Is the foreground of an [NcChannelPair] using an [indexed][NcPaletteIndex] +/// [NcPalette][crate::NcPalette] color? #[inline] -pub fn channels_fg_palindex_p(channels: NcChannels) -> bool { +pub fn channels_fg_palindex_p(channels: NcChannelPair) -> bool { channel_palindex_p(channels_fchannel(channels)) } @@ -306,50 +316,57 @@ pub fn channels_fg_palindex_p(channels: NcChannels) -> bool { /// background color" must generally be used to take advantage of /// terminal-effected transparency. #[inline] -pub fn channels_bg_default_p(channels: NcChannels) -> bool { +pub fn channels_bg_default_p(channels: NcChannelPair) -> bool { channel_default_p(channels_bchannel(channels)) } -/// Is the background using indexed palette color? +/// Is the background of an [NcChannelPair] using an [indexed][NcPaletteIndex] +/// [NcPalette][crate::NcPalette] color? #[inline] -pub fn channels_bg_palindex_p(channels: NcChannels) -> bool { +pub fn channels_bg_palindex_p(channels: NcChannelPair) -> bool { channel_palindex_p(channels_bchannel(channels)) } -/// Set the cell's background palette index, set the background palette index -/// bit, set it background-opaque, and clear the background default color bit. +/// Sets an [NcCell]'s background [NcPaletteIndex]. +/// +/// Also sets [NCCELL_BG_PALETTE] and [NCCELL_ALPHA_OPAQUE], +/// and clears out [NCCELL_BGDEFAULT_MASK]. #[inline] -pub fn channels_set_bg_palindex(channels: &mut NcChannels, index: NcPaletteIndex) { - *channels |= NCCELL_BGDEFAULT_MASK as NcChannels; - *channels |= NCCELL_BG_PALETTE as NcChannels; +pub fn channels_set_bg_palindex(channels: &mut NcChannelPair, index: NcPaletteIndex) { + *channels |= NCCELL_BGDEFAULT_MASK as NcChannelPair; + *channels |= NCCELL_BG_PALETTE as NcChannelPair; channels_set_bg_alpha(channels, NCCELL_ALPHA_OPAQUE); *channels &= 0xffffffffff000000; - *channels |= index as NcChannels; + *channels |= index as NcChannelPair; } -/// Set the cell's foreground palette index, set the foreground palette index -/// bit, set it foreground-opaque, and clear the foreground default color bit. +/// Sets an [NcCell]'s foreground [NcPaletteIndex]. +/// +/// Also sets [NCCELL_FG_PALETTE] and [NCCELL_ALPHA_OPAQUE], +/// and clears out [NCCELL_FGDEFAULT_MASK]. #[inline] -pub fn channels_set_fg_palindex(channels: &mut NcChannels, index: NcPaletteIndex) { +pub fn channels_set_fg_palindex(channels: &mut NcChannelPair, index: NcPaletteIndex) { *channels |= NCCELL_FGDEFAULT_MASK; - *channels |= NCCELL_FG_PALETTE as NcChannels; + *channels |= NCCELL_FG_PALETTE as NcChannelPair; channels_set_fg_alpha(channels, NCCELL_ALPHA_OPAQUE); - *channels &= 0xff000000ffffffff as NcChannels; - *channels |= (index as NcChannels) << 32; + *channels &= 0xff000000ffffffff as NcChannelPair; + *channels |= (index as NcChannelPair) << 32; } -/// Mark the foreground channel as using its default color. +/// Marks the foreground of an [NcChannelPair] as using its "default color", +/// and returns the new [NcChannelPair]. #[inline] -pub fn channels_set_fg_default(channels: &mut NcChannels) -> NcChannels { +pub fn channels_set_fg_default(channels: &mut NcChannelPair) -> NcChannelPair { let mut channel = channels_fchannel(*channels); channel_set_default(&mut channel); *channels = (channel as u64) << 32 | *channels & 0xffffffff_u64; *channels } -/// Mark the background channel as using its default color. +/// Marks the background of an [NcChannelPair] as using its "default color", +/// and returns the new [NcChannelPair]. #[inline] -pub fn channels_set_bg_default(channels: &mut NcChannels) -> NcChannels { +pub fn channels_set_bg_default(channels: &mut NcChannelPair) -> NcChannelPair { let mut channel = channels_bchannel(*channels); channel_set_default(&mut channel); channels_set_bchannel(channels, channel); diff --git a/rust/src/channel/tests.rs b/rust/src/channel/tests.rs index 8d4f41b5f..d9de9a3a0 100644 --- a/rust/src/channel/tests.rs +++ b/rust/src/channel/tests.rs @@ -1,7 +1,7 @@ -//! [`NcChannel`] & [`NcChannels`] tests +//! [`NcChannel`] & [`NcChannelPair`] tests use crate::{ - NcChannel, NcChannels, NCCELL_ALPHA_BLEND, NCCELL_ALPHA_HIGHCONTRAST, NCCELL_ALPHA_OPAQUE, + NcChannel, NcChannelPair, NCCELL_ALPHA_BLEND, NCCELL_ALPHA_HIGHCONTRAST, NCCELL_ALPHA_OPAQUE, NCCELL_ALPHA_TRANSPARENT, }; @@ -106,7 +106,7 @@ fn channel_default_p() { #[allow(non_snake_case)] fn channels_set_fchannel__channels_fchannel() { let fc: NcChannel = 0x112233; - let mut cp: NcChannels = 0; + let mut cp: NcChannelPair = 0; crate::channels_set_fchannel(&mut cp, fc); assert_eq!(crate::channels_fchannel(cp), fc); } @@ -116,7 +116,7 @@ fn channels_set_fchannel__channels_fchannel() { #[allow(non_snake_case)] fn channels_set_bchannel__channels_bchannel() { let bc: NcChannel = 0x112233; - let mut cp: NcChannels = 0; + let mut cp: NcChannelPair = 0; crate::channels_set_bchannel(&mut cp, bc); assert_eq!(crate::channels_bchannel(cp), bc); } @@ -126,8 +126,8 @@ fn channels_set_bchannel__channels_bchannel() { fn channels_combine() { let bc: NcChannel = 0x112233; let fc: NcChannel = 0x445566; - let mut cp1: NcChannels = 0; - let mut _cp2: NcChannels = 0; + let mut cp1: NcChannelPair = 0; + let mut _cp2: NcChannelPair = 0; crate::channels_set_bchannel(&mut cp1, bc); crate::channels_set_fchannel(&mut cp1, fc); _cp2 = crate::channels_combine(fc, bc); diff --git a/rust/src/input.rs b/rust/src/input.rs index 42ab3d4d3..f3d8471f6 100644 --- a/rust/src/input.rs +++ b/rust/src/input.rs @@ -8,7 +8,7 @@ // ------------------------------------------ //+ ncinput_equal_p -use crate::types::NcInput; +use crate::NcInput; /// Compare two ncinput structs for data equality by doing a field-by-field /// comparison for equality (excepting seqnum). diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 2aa738a0d..b477e68b1 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -17,11 +17,11 @@ #![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)] #![allow(clippy::too_many_arguments)] -pub mod bindings; -pub mod types; - +mod bindings; #[doc(inline)] pub use bindings::*; + +mod types; #[doc(inline)] pub use types::*; diff --git a/rust/src/notcurses/mod.rs b/rust/src/notcurses/mod.rs index b5af639dc..54bd4a0d6 100644 --- a/rust/src/notcurses/mod.rs +++ b/rust/src/notcurses/mod.rs @@ -70,7 +70,12 @@ use crate::{ notcurses_getc, notcurses_stdplane, notcurses_stdplane_const, - types::{NcAlign, NcInput, NcPlane, Notcurses, NCALIGN_CENTER, NCALIGN_LEFT}, + NcAlign, + NcInput, + NcPlane, + Notcurses, + NCALIGN_CENTER, + NCALIGN_LEFT, }; /// return the offset into 'availcols' at which 'cols' ought be output given the requirements of 'align' diff --git a/rust/src/palette.rs b/rust/src/palette.rs index f082d2c6c..0c6185693 100644 --- a/rust/src/palette.rs +++ b/rust/src/palette.rs @@ -18,8 +18,8 @@ //+ palette256_set_rgb use crate::{ - channel_rgb8, channel_set, channel_set_rgb8, - types::{NcChannel, NcColor, NcPalette, NcPaletteIndex, NcRgb}, + channel_rgb8, channel_set, channel_set_rgb8, NcChannel, NcColor, NcPalette, NcPaletteIndex, + NcRgb, }; /// Set the different color components of an entry inside a palette store. diff --git a/rust/src/pixel.rs b/rust/src/pixel.rs index 4188c21ff..aed246d8b 100644 --- a/rust/src/pixel.rs +++ b/rust/src/pixel.rs @@ -27,7 +27,7 @@ //+ ncpixel_set_r //+ ncpixel_set_rgb -use crate::types::{NcColor, NcPixel}; +use crate::{NcColor, NcPixel}; // NcPixel Structure: // diff --git a/rust/src/plane/mod.rs b/rust/src/plane/mod.rs index ee0a44d1f..173102059 100644 --- a/rust/src/plane/mod.rs +++ b/rust/src/plane/mod.rs @@ -171,18 +171,14 @@ use libc::free; use std::ffi::CString; use crate::{ - bindgen::__va_list_tag, - cell_load, cell_release, cells_double_box, cells_rounded_box, channels_bchannel, - channels_bg_alpha, channels_bg_default_p, channels_bg_rgb, channels_bg_rgb8, channels_fchannel, - channels_fg_alpha, channels_fg_default_p, channels_fg_rgb, channels_fg_rgb8, ncplane_at_cursor, - ncplane_at_yx, ncplane_box, ncplane_channels, ncplane_cursor_move_yx, ncplane_cursor_yx, - ncplane_dim_yx, ncplane_gradient, ncplane_hline_interp, ncplane_putc_yx, ncplane_putegc_yx, - ncplane_putnstr_yx, ncplane_putstr_yx, ncplane_resize, ncplane_styles, ncplane_vline_interp, - ncplane_vprintf_yx, notcurses_align, - types::{ - NcAlign, NcAlphaBits, NcCell, NcChannel, NcChannels, NcColor, NcPlane, NcResult, - NcStyleMask, NCRESULT_ERR, NCRESULT_OK, - }, + bindgen::__va_list_tag, cell_load, cell_release, cells_double_box, cells_rounded_box, + channels_bchannel, channels_bg_alpha, channels_bg_default_p, channels_bg_rgb, channels_bg_rgb8, + channels_fchannel, channels_fg_alpha, channels_fg_default_p, channels_fg_rgb, channels_fg_rgb8, + ncplane_at_cursor, ncplane_at_yx, ncplane_box, ncplane_channels, ncplane_cursor_move_yx, + ncplane_cursor_yx, ncplane_dim_yx, ncplane_gradient, ncplane_hline_interp, ncplane_putc_yx, + ncplane_putegc_yx, ncplane_putnstr_yx, ncplane_putstr_yx, ncplane_resize, ncplane_styles, + ncplane_vline_interp, ncplane_vprintf_yx, notcurses_align, NcAlign, NcAlphaBits, NcCell, + NcChannel, NcChannelPair, NcColor, NcPlane, NcResult, NcStyleMask, NCRESULT_ERR, NCRESULT_OK, }; // Static Functions ------------------------------------------------------------ @@ -290,7 +286,7 @@ pub fn ncplane_dim_y(plane: &NcPlane) -> i32 { pub fn ncplane_double_box( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ystop: i32, xstop: i32, ctlword: u32, @@ -336,7 +332,7 @@ pub fn ncplane_double_box( pub fn ncplane_double_box_sized( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ylen: i32, xlen: i32, ctlword: u32, @@ -386,7 +382,7 @@ pub fn ncplane_perimeter( pub fn ncplane_perimeter_double( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ctlword: u32, ) -> NcResult { if unsafe { ncplane_cursor_move_yx(plane, 0, 0) } != NCRESULT_OK { @@ -435,7 +431,7 @@ pub fn ncplane_perimeter_double( pub fn ncplane_perimeter_rounded( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ctlword: u32, ) -> NcResult { if unsafe { ncplane_cursor_move_yx(plane, 0, 0) } != NCRESULT_OK { @@ -696,7 +692,7 @@ pub fn ncplane_bg_rgb8( pub fn ncplane_rounded_box( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ystop: i32, xstop: i32, ctlword: u32, @@ -741,7 +737,7 @@ pub fn ncplane_rounded_box( pub fn ncplane_rounded_box_sized( plane: &mut NcPlane, stylemask: NcStyleMask, - channels: NcChannels, + channels: NcChannelPair, ylen: i32, xlen: i32, ctlword: u32, diff --git a/rust/src/types/cell.rs b/rust/src/types/cell.rs index b0a9512b0..9430ea18a 100644 --- a/rust/src/types/cell.rs +++ b/rust/src/types/cell.rs @@ -28,7 +28,7 @@ use crate::{NcAlphaBits, NcChannel, NcPlane}; /// /// GCLUSTER GCLUSTER GCLUSTER GCLUSTER 1. NcChar /// 00000000 ~~~~~~~~ 11111111 11111111 2. NcCharBackstop + 3. reserved + 4. NcStyleMask -/// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB 5. NcChannels +/// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB 5. NcChannelPair /// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB | /// /// 1. (32b) Extended Grapheme Cluster, presented either as: @@ -48,7 +48,7 @@ use crate::{NcAlphaBits, NcChannel, NcPlane}; /// 4. (16b) NcStyleMask /// 11111111 11111111 /// -/// 5. (64b) NcChannels +/// 5. (64b) NcChannelPair /// ~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB|~~AA~~~~ RRRRRRRR GGGGGGGG BBBBBBBB /// ``` /// @@ -122,7 +122,7 @@ pub const NCCELL_ALPHA_TRANSPARENT: u32 = crate::bindings::bindgen::CELL_ALPHA_T /// If this bit is set, we are *not* using the default background color /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: This can also be used against a single [`NcChannel`] pub const NCCELL_BGDEFAULT_MASK: u32 = crate::bindings::bindgen::CELL_BGDEFAULT_MASK; @@ -130,7 +130,7 @@ pub const NCCELL_BGDEFAULT_MASK: u32 = crate::bindings::bindgen::CELL_BGDEFAULT_ /// Extract these bits to get the background alpha mask /// ([`NcAlphaBits`]) /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: This can also be used against a single [`NcChannel`] pub const NCCELL_BG_ALPHA_MASK: u32 = crate::bindings::bindgen::CELL_BG_ALPHA_MASK; @@ -138,21 +138,21 @@ pub const NCCELL_BG_ALPHA_MASK: u32 = crate::bindings::bindgen::CELL_BG_ALPHA_MA /// If this bit *and* [`NCCELL_BGDEFAULT_MASK`] are set, we're using a /// palette-indexed background color /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: This can also be used against a single [`NcChannel`] pub const NCCELL_BG_PALETTE: u32 = crate::bindings::bindgen::CELL_BG_PALETTE; /// Extract these bits to get the background [`NcRgb`][crate::NcRgb] value /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: This can also be used against a single [`NcChannel`] pub const NCCELL_BG_RGB_MASK: u32 = crate::bindings::bindgen::CELL_BG_RGB_MASK; /// If this bit is set, we are *not* using the default foreground color /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: When working with a single [`NcChannel`] use [`NCCELL_BGDEFAULT_MASK`]; pub const NCCELL_FGDEFAULT_MASK: u64 = crate::bindings::bindgen::CELL_FGDEFAULT_MASK; @@ -160,29 +160,29 @@ pub const NCCELL_FGDEFAULT_MASK: u64 = crate::bindings::bindgen::CELL_FGDEFAULT_ /// Extract these bits to get the foreground alpha mask /// ([`NcAlphaBits`]) /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: When working with a single [`NcChannel`] use [`NCCELL_BG_ALPHA_MASK`]; pub const NCCELL_FG_ALPHA_MASK: u64 = crate::bindings::bindgen::CELL_FG_ALPHA_MASK; -/// If this bit *and* [`NCCELL_BGDEFAULT_MASK`] are set, we're using a +/// If this bit *and* [`NCCELL_FGDEFAULT_MASK`] are set, we're using a /// palette-indexed background color /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: When working with a single [`NcChannel`] use [`NCCELL_BG_PALETTE`]; pub const NCCELL_FG_PALETTE: u64 = crate::bindings::bindgen::CELL_FG_PALETTE; /// Extract these bits to get the foreground [`NcRgb`][crate::NcRgb] value /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] /// /// NOTE: When working with a single [`NcChannel`] use [`NCCELL_BG_RGB_MASK`]; pub const NCCELL_FG_RGB_MASK: u64 = crate::bindings::bindgen::CELL_FG_RGB_MASK; /// Indicates the glyph is entirely foreground /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] pub const NCCELL_NOBACKGROUND_MASK: u64 = crate::bindings::bindgen::CELL_NOBACKGROUND_MASK; /// If this bit is set, the cell is part of a multicolumn glyph. @@ -190,7 +190,7 @@ pub const NCCELL_NOBACKGROUND_MASK: u64 = crate::bindings::bindgen::CELL_NOBACKG /// Whether a cell is the left or right side of the glyph can be determined /// by checking whether ->gcluster is zero. /// -/// See the detailed diagram at [`NcChannels`][crate::NcChannels] +/// See the detailed diagram at [`NcChannelPair`][crate::NcChannelPair] pub const NCCELL_WIDEASIAN_MASK: u64 = crate::bindings::bindgen::CELL_WIDEASIAN_MASK as u64; // NcChar diff --git a/rust/src/types/channel.rs b/rust/src/types/channel.rs index 723184794..1b78e8592 100644 --- a/rust/src/types/channel.rs +++ b/rust/src/types/channel.rs @@ -12,7 +12,7 @@ use crate::NcChar; /// - 2 bits of [`NcAlphaBits`] /// - 6 bits of context-dependent info /// -/// The context details are documented in [`NcChannels`] +/// The context details are documented in [`NcChannelPair`] /// /// ## Diagram /// @@ -41,7 +41,7 @@ pub const NCCHANNEL_ALPHA_MASK: u32 = crate::bindings::bindgen::CHANNEL_ALPHA_MA /// pub type NcAlphaBits = u32; -// NcChannels +// NcChannelPair // /// 64 bits containing a foreground and background [`NcChannel`] /// @@ -126,7 +126,7 @@ pub type NcAlphaBits = u32; /// - [`NCCELL_NOBACKGROUND_MASK`][crate::NCCELL_NOBACKGROUND_MASK] /// - [`NCCELL_WIDEASIAN_MASK`][crate::NCCELL_WIDEASIAN_MASK] /// -pub type NcChannels = u64; +pub type NcChannelPair = u64; // NcRgb // @@ -177,7 +177,9 @@ pub type NcColor = u8; // NOTE: the order of the colors is different than in NcChannel. pub type NcPixel = u32; -/// NcPalette structure consisting of an array of 256 [`NcChannel`]s +/// NcPalette structure consisting of an array of 256 [`NcChannel`]s. +/// +/// See also [NcPaletteIndex]. /// /// Some terminals only support 256 colors, but allow the full /// palette to be specified with arbitrary RGB colors. In all cases, it's more diff --git a/rust/src/types/mod.rs b/rust/src/types/mod.rs index 633bfe3c0..e0220ef9a 100644 --- a/rust/src/types/mod.rs +++ b/rust/src/types/mod.rs @@ -31,8 +31,8 @@ pub use cell::{ NCSTYLE_UNDERLINE, }; pub use channel::{ - NcAlphaBits, NcBlitSet, NcChannel, NcChannels, NcColor, NcFadeCtx, NcPalette, NcPaletteIndex, - NcPixel, NcRgb, NCCHANNEL_ALPHA_MASK, + NcAlphaBits, NcBlitSet, NcChannel, NcChannelPair, NcColor, NcFadeCtx, NcPalette, + NcPaletteIndex, NcPixel, NcRgb, NCCHANNEL_ALPHA_MASK, }; pub use file::{NcFile, FILE_LIBC, FILE_NC}; pub use misc::{ diff --git a/rust/src/visual.rs b/rust/src/visual.rs index 15d4764ec..d0bb844e5 100644 --- a/rust/src/visual.rs +++ b/rust/src/visual.rs @@ -25,7 +25,7 @@ // ------------------------------------------ // ncvisual_default_blitter -use crate::types::{NCBLIT_1x1, NCBLIT_2x1, NCBLIT_2x2, NcBlitter, NcScale, NCSCALE_STRETCH}; +use crate::{NCBLIT_1x1, NCBLIT_2x1, NCBLIT_2x2, NcBlitter, NcScale, NCSCALE_STRETCH}; /// Returns the best default blitter available /// diff --git a/rust/src/widgets/menu.rs b/rust/src/widgets/menu.rs index ca1b7c70a..c55b6b78b 100644 --- a/rust/src/widgets/menu.rs +++ b/rust/src/widgets/menu.rs @@ -17,8 +17,8 @@ use std::ffi::CString; use crate::{ - ncmenu_create, - types::{NcChannels, NcInput, NcMenu, NcMenuItem, NcMenuOptions, NcMenuSection, NcPlane}, + ncmenu_create, NcChannelPair, NcInput, NcMenu, NcMenuItem, NcMenuOptions, NcMenuSection, + NcPlane, }; impl NcMenu { @@ -43,8 +43,8 @@ impl NcMenuOptions { pub fn with_options( sections: &mut [NcMenuSection], count: u32, - headerc: NcChannels, - sectionc: NcChannels, + headerc: NcChannelPair, + sectionc: NcChannelPair, flags: u64, ) -> Self { Self { diff --git a/rust/tests/notcurses.rs b/rust/tests/notcurses.rs index 57d58adf1..740889a43 100644 --- a/rust/tests/notcurses.rs +++ b/rust/tests/notcurses.rs @@ -30,7 +30,7 @@ fn create_notcurses_context() { margin_r: 0, margin_b: 0, margin_l: 0, - flags: (sys::types::NCOPTION_NO_ALTERNATE_SCREEN | sys::types::NCOPTION_INHIBIT_SETLOCALE | sys::types::NCOPTION_SUPPRESS_BANNERS), + flags: (sys::NCOPTION_NO_ALTERNATE_SCREEN | sys::NCOPTION_INHIBIT_SETLOCALE | sys::NCOPTION_SUPPRESS_BANNERS), }; let nc = sys::notcurses_init(&opts, null_mut()); sys::notcurses_stop(nc);