From 6b79c023bbb05f2461b16ab0c39951c119d439f5 Mon Sep 17 00:00:00 2001 From: "Christoph J. Scherr" Date: Fri, 6 Sep 2024 13:42:16 +0200 Subject: [PATCH] docs: improve api docs for all of format.rs --- src/format.rs | 115 +++++++++++++++++++++++++++++++++++++++++++++----- src/lib.rs | 9 +++- 2 files changed, 112 insertions(+), 12 deletions(-) diff --git a/src/format.rs b/src/format.rs index 797d442..febf231 100644 --- a/src/format.rs +++ b/src/format.rs @@ -44,7 +44,11 @@ use libpt::log::{debug, trace}; /// The number type [numf](crate) uses pub type NumberType = u128; -/// formats supported by numf +/// Describes a format for numbers +/// +/// [Format] can be used to convert unsigned integers into a textual or other representation. See +/// [Format::format_str] for more. It is also possible to parse the various represenations to +/// a rust integer, see [numf_parser_str] for that. #[derive(Copy, Clone, Debug, Hash, PartialEq, Eq, Default)] pub enum Format { Dec, @@ -54,7 +58,7 @@ pub enum Format { Octal, Base64, Base32, - /// Write raw data to stdout, not text + /// Write raw data, not text Raw, } @@ -64,11 +68,30 @@ impl Display for Format { } } -/// Describes what the formatter should do +/// Describes what the formatter should do exactly /// /// Use [Self::default] to get a basic variant or create a object yourself. /// /// This struct can be parsed with [clap] derive. +/// +/// # Example +/// +/// ``` +/// use numf::format::{Format, FormatOptions}; +/// let mut options = FormatOptions::default(); +/// +/// assert_eq!(Format::Bin.format_str(256, &options), "100000000"); +/// assert_eq!(Format::Hex.format_str(256, &options), "100"); +/// assert_eq!(Format::Base64.format_str(256, &options), "AQA="); +/// +/// options.set_prefix(true); +/// options.set_padding(true); +/// +/// assert_eq!(Format::Bin.format_str(256, &options), "0b0000000100000000"); +/// assert_eq!(Format::Hex.format_str(256, &options), "0x0100"); +/// assert_eq!(Format::Base64.format_str(256, &options), "0sAQA="); +/// +/// ``` #[derive(Parser, Debug, Clone, PartialEq, Eq, Hash)] #[clap(author, version, about, long_about = None)] #[command( @@ -276,11 +299,38 @@ impl Default for FormatOptions { } impl Format { + /// Get the perfix for that [Format] as [Vec]. + /// + /// # Example + /// + /// ``` + /// # use numf::format::Format; + /// assert_eq!(Format::Bin.prefix_str(), "0b"); + /// assert_eq!(Format::Dec.prefix_str(), "0d"); + /// assert_eq!(Format::Hex.prefix_str(), "0x"); + /// assert_eq!(Format::Octal.prefix_str(), "0o"); + /// assert_eq!(Format::Base64.prefix_str(), "0s"); + /// assert_eq!(Format::Base32.prefix_str(), "032s"); + /// assert_eq!(Format::Raw.prefix_str(), "\x00"); + /// ``` pub fn prefix_str(&self) -> String { String::from_utf8_lossy(&self.prefix()).to_string() } - /// Get the perfix for that [Format] + /// Get the perfix for that [Format] as [Vec]. + /// + /// # Example + /// + /// ``` + /// # use numf::format::Format; + /// assert_eq!(Format::Bin.prefix(), b"0b"); + /// assert_eq!(Format::Dec.prefix(), b"0d"); + /// assert_eq!(Format::Hex.prefix(), b"0x"); + /// assert_eq!(Format::Octal.prefix(), b"0o"); + /// assert_eq!(Format::Base64.prefix(), b"0s"); + /// assert_eq!(Format::Base32.prefix(), b"032s"); + /// assert_eq!(Format::Raw.prefix(), vec![0x00]); + /// ``` pub fn prefix(&self) -> Vec { match self { // apperently used nowhere, sometimes 0 is used as a prefix but I @@ -299,12 +349,60 @@ impl Format { Format::Base32 => b"032s".to_vec(), } } - /// format a number with a [Format] and [FormatOptions] to [String] + /// format a number with a [Format] and [FormatOptions] to a [String] + /// + /// If you need raw byte outputs, use [Format::format] instead. + /// + /// # Example + /// + /// ``` + /// use numf::format::{Format, FormatOptions}; + /// let mut options = FormatOptions::default(); + /// + /// assert_eq!(Format::Bin.format_str(256, &options), "100000000"); + /// assert_eq!(Format::Hex.format_str(256, &options), "100"); + /// assert_eq!(Format::Base64.format_str(256, &options), "AQA="); + /// + /// options.set_prefix(true); + /// options.set_padding(true); + /// + /// assert_eq!(Format::Bin.format_str(256, &options), "0b0000000100000000"); + /// assert_eq!(Format::Hex.format_str(256, &options), "0x0100"); + /// assert_eq!(Format::Base64.format_str(256, &options), "0sAQA="); + /// + /// ``` pub fn format_str(&self, num: NumberType, options: &FormatOptions) -> String { String::from_utf8_lossy(&self.format(num, options)).to_string() } - /// format a number with a [Format] and [FormatOptions] + /// format a number with a [Format] and [FormatOptions] to a byte vector [Vec] + /// + /// If you need [String] outputs, use [Format::format_str] instead. + /// + /// # Example + /// + /// ``` + /// use numf::format::{Format, FormatOptions}; + /// let mut options = FormatOptions::default(); + /// + /// assert_eq!(Format::Bin.format(256, &options), b"100000000"); + /// assert_eq!(Format::Hex.format(256, &options), b"100"); + /// assert_eq!(Format::Hex.format(256, &options), [49, 48, 48]); + /// assert_eq!(Format::Base64.format(256, &options), b"AQA="); + /// assert_eq!(Format::Raw.format(256, &options), [1, 0]); + /// + /// options.set_prefix(true); + /// options.set_padding(true); + /// + /// assert_eq!(Format::Bin.format(256, &options), b"0b0000000100000000"); + /// assert_eq!(Format::Hex.format(256, &options), b"0x0100"); + /// assert_eq!(Format::Hex.format(256, &options), [48, 120, 48, 49, 48, 48]); + /// assert_eq!(Format::Base64.format(256, &options), b"0sAQA="); + /// assert_eq!(Format::Raw.format(256, &options), [0, 1, 0]); + /// assert_eq!(Format::Raw.format(255, &options), [0, 255]); + /// assert_eq!(Format::Raw.format(32000, &options), [0, 125, 0]); + /// + /// ``` pub fn format(&self, num: NumberType, options: &FormatOptions) -> Vec { debug!("formatting mode: {self}"); let mut buf: Vec = Vec::new(); @@ -424,12 +522,7 @@ where /// /// # Example /// -/// This allows base-10 addresses to be passed normally, or values formatted with any of the -/// [Formats](format::Format) defined by this crate to be passed when prefixed with the respective -/// prefix. -/// /// ``` -/// use clap::Parser; /// use numf::format::numf_parser; /// /// let data = &[0x15, 0x92, 0xff]; diff --git a/src/lib.rs b/src/lib.rs index b120604..12757b7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,10 +1,17 @@ //! Format numbers //! //! This crate contains several utility functions for formatting numbers -//! into other systems, such as converting decimal numbers to hexadecimal. +//! into other systems, such as converting decimal numbers to hexadecimal +//! , and back. //! //! See [format::Format] for supported formats. //! //! Note that this crate is primarily intended to be used as a executable. +//! +//! Highlights: +//! * [format::numf_parser] +//! * [format::numf_parser_str] +//! * [format::Format::format] +//! * [format::Format::format_str] pub mod format;