Archives/notcurses
2
0
Fork 0
mirror of https://github.com/dankamongmen/notcurses.git synced 2024-10-31 15:20:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

rust: add most NcCell methods

Browse Source 
- add & fix comments.
- add methods links.
This commit is contained in:
joseLuís 2020-12-30 00:48:09 +01:00
parent 279d9a7f43
commit 624bee6d71
5 changed files with 278 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
rust/src/cells/methods.rs
View File

@ -1,11 +1,11 @@
//! `NcCell` methods and associated functions.
use crate::{
cell_extract, cell_load, cstring, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor,
NcEgc, NcEgcBackstop, NcPaletteIndex, NcPlane, NcRgb, NcStyleMask, NCRESULT_ERR,
cell_load, cstring, error, NcAlphaBits, NcCell, NcChannel, NcChannelPair, NcColor, NcEgc,
NcEgcBackstop, NcPaletteIndex, NcPlane, NcResult, NcRgb, NcStyleMask, NCRESULT_ERR,
};
/// # `NcCell` Constructors
/// # NcCell constructors
impl NcCell {
/// New NcCell, expects a 7-bit [char].
#[inline]
@ -42,11 +42,82 @@ impl NcCell {
pub const fn new() -> Self {
Self::with_char7b(0 as char)
}
// TODO: it's not clear what it does
//
// /// Breaks the UTF-8 string in `gcluster` down, setting up this NcCell,
// /// and returns the number of bytes copied out of `gcluster`.
// ///
// /// The styling of the cell is left untouched, but any resources are released.
// /// *C style function: [cell_load()][crate::cell_load].*
// pub fn load(
// plane: &mut NcPlane,
// cell: &mut NcCell,
// gcluster: NcEgc,
// ) -> NcResult<u32> {
// let bytes = unsafe { crate::cell_load(plane, cell, gcluster as u32 as *const i8)};
// error![bytes, bytes as u32]
// }
/// Same as [load][NcCell#method.load], plus blasts the styling with
/// `style` and `channels`.
///
/// - Breaks the UTF-8 string in `gcluster` down, setting up this NcCell.
/// - Returns the number of bytes copied out of `gcluster`.
/// - The styling of the cell is left untouched, but any resources are released.
/// - Blasts the styling with `style` and `channels`.
///
/// *C style function: [cell_prime()][crate::cell_prime].*
pub fn prime(
plane: &mut NcPlane,
cell: &mut NcCell,
gcluster: NcEgc,
style: NcStyleMask,
channels: NcChannelPair,
) -> NcResult<u32> {
let bytes = crate::cell_prime(plane, cell, gcluster, style, channels);
error![bytes, bytes as u32]
}
/// Duplicate this NcCell into another one.
///
/// Both must be or will be bound to `common_plane`.
///
/// *C style function: [cell_duplicate()][crate::cell_duplicate].*
pub fn duplicate(&self, target: &mut NcCell, common_plane: &mut NcPlane) -> NcResult<()> {
error![unsafe { crate::cell_duplicate(common_plane, target, self) }]
}
/// Initializes (zeroes out) the NcCell.
///
/// *C style function: [cell_init()][crate::cell_init].*
#[inline]
pub fn init(&mut self) {
crate::cell_init(self);
}
/// Releases resources held by the current cell in the [NcPlane] `plane`.
///
/// *C style function: [cell_release()][crate::cell_release].*
pub fn release(&mut self, plane: &mut NcPlane) {
unsafe {
crate::cell_release(plane, self);
}
}
}
// -----------------------------------------------------------------------------
/// ## NcPlane methods: bg|fg `NcChannel`s manipulation.
/// ## NcCell methods: bg|fg `NcChannel`s manipulation.
impl NcCell {
/// 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 = crate::cell_extract(plane, self, &mut _styles, &mut channels);
channels
}
/// Gets the background [NcChannel].
///
/// *C style function: [cell_bchannel()][crate::cell_bchannel].*
@ -246,8 +317,19 @@ impl NcCell {
}
}
/// # `NcCell` Methods
/// # `NcCell` methods: other components
impl NcCell {
/// Returns true if the two cells have distinct [NcEgc]s, attributes,
/// or [NcChannel]s.
///
/// The actual egcpool index needn't be the same--indeed, the planes
/// needn't even be the same. Only the expanded NcEgc must be bit-equal.
///
/// *C style function: [cellcmp()][crate::cellcmp].*
pub fn compare(plane1: &NcPlane, cell1: &NcCell, plane2: &NcPlane, cell2: &NcCell) -> bool {
crate::cellcmp(plane1, cell1, plane2, cell2)
}
/// Saves the [NcStyleMask] and the [NcChannelPair], and returns the [NcEgc]
/// (the three elements of an NcCell).
///
@ -258,32 +340,154 @@ impl NcCell {
styles: &mut NcStyleMask,
channels: &mut NcChannelPair,
) -> NcEgc {
cell_extract(plane, self, 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
}
/// 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
crate::cell_extract(plane, self, styles, channels)
}
/// Returns the [NcEgc] of the NcCell.
///
/// See also: [extended_gcluster][NcCell#method.extended_gcluster] method.
///
/// *(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)
crate::cell_extract(plane, self, &mut _styles, &mut _channels)
}
/// Returns the [NcStyleMask] bits.
///
/// *C style function: [cell_styles()][crate::cell_styles].*
pub fn styles(&mut self) -> NcStyleMask {
crate::cell_styles(self)
}
/// Removes the specified [NcStyleMask] bits.
///
/// *C style function: [cell_off()][crate::cell_off_styles].*
pub fn off_styles(&mut self, stylebits: NcStyleMask) {
crate::cell_off_styles(self, stylebits)
}
/// Adds the specified [NcStyleMask] bits.
///
/// *C style function: [cell_on()][crate::cell_on_styles].*
pub fn on_styles(&mut self, stylebits: NcStyleMask) {
crate::cell_on_styles(self, stylebits)
}
/// Sets just the specified [NcStyleMask] bits.
///
/// *C style function: [cell_set_styles()][crate::cell_set_styles].*
pub fn set_styles(&mut self, stylebits: NcStyleMask) {
crate::cell_set_styles(self, stylebits)
}
}
/// # `NcCell` methods: text
impl NcCell {
// /// Returns a pointer to the [NcEgc] of this NcCell in the [NcPlane] `plane`.
// ///
// /// This pointer can be invalidated by any further operation on the referred
// /// plane, so… watch out!
// ///
// /// *C style function: [cell_extended_gcluster()][crate::cell_wide_left_p].*
// pub fn extended_gcluster(&self, plane: &NcPlane) -> u32 {
// let egcpointer = unsafe { crate::cell_extended_gcluster(plane, self) };
// egcpointer
// }
/// Copies the UTF8-encoded [NcEgc] out of this NcCell,
/// whether simple or complex.
///
/// The result is not tied to the [NcPlane],
/// and persists across erases and destruction.
///
/// *C style function: [cell_strdup()][crate::cell_strdup].*
pub fn strdup(&self, plane: &NcPlane) -> NcEgc {
crate::cell_strdup(plane, self)
}
/// Does this NcCell contain an East Asian Wide codepoint?
///
/// *C style function: [cell_double_wide_p()][crate::cell_double_wide_p].*
pub fn double_wide_p(&self) -> bool {
crate::cell_double_wide_p(self)
}
/// Is this the left half of a wide character?
///
/// *C style function: [cell_wide_left_p()][crate::cell_wide_left_p].*
pub fn wide_left_p(&self) -> bool {
crate::cell_wide_right_p(self)
}
/// Is this the right half of a wide character?
///
/// *C style function: [cell_wide_right_p()][crate::cell_wide_right_p].*
pub fn wide_right_p(&self) -> bool {
crate::cell_wide_right_p(self)
}
}
/// # `NcCell` methods: boxes
impl NcCell {
/// Loads up six cells with the [NcEgc]s necessary to draw a box.
///
/// 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`.
///
/// *C style function: [cells_load_box()][crate::cells_load_box].*
pub fn load_box(
plane: &mut NcPlane,
style: NcStyleMask,
channels: NcChannelPair,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell,
gcluster: NcEgc,
) -> NcResult<()> {
error![crate::cells_load_box(
plane, style, channels, ul, ur, ll, lr, hl, vl, gcluster
)]
}
/// NcCell.[load_box()][NcCell#method.box] with the double box-drawing characters.
///
/// *C style function: [cells_double_box()][crate::cells_double_box].*
pub fn double_box(
plane: &mut NcPlane,
style: NcStyleMask,
channels: NcChannelPair,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell,
) -> NcResult<()> {
error![unsafe {
crate::cells_double_box(plane, style as u32, channels, ul, ur, ll, lr, hl, vl)
}]
}
/// NcCell.[load_box()][NcCell#method.box] with the rounded box-drawing characters.
///
/// *C style function: [cells_rounded_box()][crate::cells_double_box].*
pub fn rounded_box(
plane: &mut NcPlane,
style: NcStyleMask,
channels: NcChannelPair,
ul: &mut NcCell,
ur: &mut NcCell,
ll: &mut NcCell,
lr: &mut NcCell,
hl: &mut NcCell,
vl: &mut NcCell,
) -> NcResult<()> {
error![unsafe {
crate::cells_rounded_box(plane, style as u32, channels, ul, ur, ll, lr, hl, vl)
}]
}
}

62
rust/src/cells/mod.rs
View File

@ -2,18 +2,21 @@
// functions already exported by bindgen : 6
// -----------------------------------------
// cell_duplicate
// cell_extended_gcluster
// cell_load
// cell_release
// cells_double_box
// cells_rounded_box
// (W) wrap: 4
// (#) test: 0
// ------------------------------------------
//W cell_duplicate
//… cell_extended_gcluster
//… cell_load
//W cell_release
//W cells_double_box
//W cells_rounded_box
//
// functions manually reimplemented: 43
// ------------------------------------------
// (X) wont: 2
// (+) done: 40
// (W) wrap: 27
// (+) done: 38
// (W) wrap: 40
// (#) test: 26
// ------------------------------------------
//W# cell_bchannel
@ -23,8 +26,8 @@
//W# cell_bg_palindex_p
//W# cell_bg_rgb
//W# cell_bg_rgb8
// + cellcmp
// + cell_double_wide_p
//W+ cellcmp
//W+ cell_double_wide_p
//W+ cell_extract
//W# cell_fchannel
//W# cell_fg_alpha
@ -33,12 +36,12 @@
//W# cell_fg_palindex_p
//W# cell_fg_rgb
//W# cell_fg_rgb8
// + cell_init
// + cell_load_char
//W+ cell_init
//…… cell_load_char
// cell_load_egc32
// + cell_off_styles
// + cell_on_styles
// + cell_prime
//W+ cell_off_styles
//W+ cell_on_styles
//W+ cell_prime
//W# cell_set_bchannel
//W# cell_set_bg_alpha
//W# cell_set_bg_default
@ -53,12 +56,12 @@
//W# cell_set_fg_rgb
//W# cell_set_fg_rgb8
// X cell_set_fg_rgb8_clipped // unneeded
// + cell_set_styles
// + cells_load_box
// + cell_strdup
// + cell_styles
// + cell_wide_left_p
// + cell_wide_right_p
//W+ cell_set_styles
//W+ cells_load_box
//W+ cell_strdup
//W+ cell_styles
//W+ cell_wide_left_p
//W+ cell_wide_right_p
#[cfg(test)]
mod test;
@ -70,11 +73,24 @@ pub use reimplemented::*;
// NcCell
/// A coordinate on an [`NcPlane`][crate::NcPlane] storing 128 bits of data.
///
/// An `NcCell` corresponds to a single character cell on some [`NcPlane`],
/// # Methods & Associated Functions
///
/// - [Constructors & Destructors](#nccell-constructors-and-destructors)
///
/// - [bg|fg `NcChannel`s manipulation](#nccell-methods-bgfg-ncchannels-manipulation)
/// - [Other components](#nccell-methods-other-components)
/// - [Text](#nccell-methods-text)
///
/// # Description
///
/// An `NcCell` corresponds to a single character cell on some NcPlane`,
/// which can be occupied by a single [`NcEgc`] grapheme cluster (some root
/// spacing glyph, along with possible combining characters, which might span
/// multiple columns).
///
/// An NcCell is bounded to an NcPlane, but the cell doesn't know which plane it is.
/// The extended grapheme information
///
/// At any `NcCell`, we can have a theoretically arbitrarily long UTF-8 string,
/// a foreground color, a background color, and an [`NcStyleMask`] attribute set.
///
@ -120,6 +136,8 @@ pub use reimplemented::*;
///
/// `type in C: cell (struct)`
///
/// # More NcCell Information
///
/// ## Size
///
/// Multi-column characters can only have a single style/color throughout.

7
rust/src/cells/reimplemented.rs
View File

@ -375,9 +375,10 @@ pub fn cell_load_char(plane: &mut NcPlane, cell: &mut NcCell, ch: NcEgc) /* -> i
// return cell_load(n, c, gcluster);
// }
/// Copies the UTF8-encoded [NcEgc] out of the cell, whether simple or complex.
/// Copies the UTF8-encoded [NcEgc] out of the [NcCell], whether simple or complex.
///
/// The result is not tied to the [NcPlane], and persists across erases and destruction.
/// The result is not tied to the [NcPlane],
/// and persists across erases and destruction.
///
/// *Method: NcCell.[strdup()][NcCell#method.strdup].*
#[inline]
@ -473,7 +474,7 @@ pub fn cell_prime(
/// Returns [NCRESULT_OK] on success, [NCRESULT_ERR] on error.
///
/// 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.
/// 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(

6
rust/src/plane/methods.rs
View File

@ -68,7 +68,7 @@ impl NcPlaneOptions {
}
}
/// # NcPlane constructors and destructors
/// # NcPlane constructors & destructors
impl NcPlane {
/// New NcPlane.
///
@ -1466,7 +1466,8 @@ impl NcPlane {
)]
}
///
/// NcPlane.[perimeter()][NcDirect#method.perimeter] with the double box-drawing characters.
///
/// *C style function: [ncplane_perimeter_double()][crate::ncplane_perimeter_double].*
#[inline]
@ -1481,6 +1482,7 @@ impl NcPlane {
)]
}
/// NcPlane.[perimeter()][NcDirect#method.perimeter] with the rounded box-drawing characters.
///
///
/// *C style function: [ncplane_perimeter_rounded()][crate::ncplane_perimeter_rounded].*

2
rust/src/plane/mod.rs
View File

@ -220,7 +220,7 @@ pub use reimplemented::*;
///
/// # Methods & Associated Functions
///
/// - [Constructors & Destructors](#ncplane-constructors-and-destructors)
/// - [Constructors & Destructors](#ncplane-constructors--destructors)
///
/// Methods:
/// - [`NcAlphaBits`](#ncplane-methods-ncalphabits)