base-traits

base traits, for Rust

Introduction

This crate defines general-purpose traits that:

• seem obvious and yet are missing from the standard library (e.g. IsEmpty, Len); or
• provide a basis to introduce specific functionality to allow for other crates to interoperate;

Table of Contents

• Introduction
• Installation
• Components
  • Enumerations
  • Features
  • Functions
  • Macros
  • Structures
  • Traits
• Examples
• Project Information
  • Where to get help
  • Contribution guidelines
  • Dependencies
    • Efferent (fan-out)
      • Runtime Dependencies
      • Build Dependencies
      • Development Dependencies
    • Afferent (fan-in)
  • Related projects
  • License

Installation

Reference in Cargo.toml in the usual way:

base-traits = { version = "0" }

Components

Enumerations

None defined at this time.

Features

The following crate features are defined:

Functions

None defined at this time.

Macros

None defined at this time.

Structures

None defined at this time.

Traits

The following traits are defined:

• AsF64 - provides (non-mutating) instance method #as_f64() : f64;
• AsI128 - provides (non-mutating) instance method #as_i128() : i128;
• AsI32 - provides (non-mutating) instance method #as_i32() : i32;
• AsI64 - provides (non-mutating) instance method #as_i64() : i64;
• AsISize - provides (non-mutating) instance method #as_isize() : isize;
• AsStr - provides (non-mutating) instance method #as_str() : &str;
• AsU128 - provides (non-mutating) instance method #as_u128() : u128;
• AsU32 - provides (non-mutating) instance method #as_u32() : u32;
• AsU64 - provides (non-mutating) instance method #as_u64() : u64;
• AsUSize - provides (non-mutating) instance method #as_usize() : usize;
• Infinity - provides method ::infinity() : Self;
• Integer - provides no methods;
• IsEmpty - provides (non-mutating) instance method #is_empty() : bool;
• IsInfinity - provides (non-mutating) instance method #is_infinity() : bool;
• IsNAN - provides (non-mutating) instance method #is_nan() : bool;
• IsZero - provides (non-mutating) instance method #is_zero() : bool;
• Len - provides (non-mutating) instance method #len() : usize;
• Numeric - provides no methods;
• Real - provides no methods;
• Signed - provides no methods;
• ToF64 - provides (non-mutating) instance method #to_f64() : f64;
• AsU32 - provides (non-mutating) instance method #as_u32() : u32;
• AsU64 - provides (non-mutating) instance method #as_u64() : u64;
• AsU128 - provides (non-mutating) instance method #as_u128() : u128;
• ToISize - provides (non-mutating) instance method #to_isize() : isize;
• ToUSize - provides (non-mutating) instance method #to_usize() : usize;
• Unsigned - provides no methods;
• Zero - provides class method ::zero() : Self;

Examples

The purpose of all traits provided in this package is to enhance generic programming.

For example, you may be working on a subsystem that needs to abstract numbers into strong types, but you also need to build algorithms that can work generically on such types as well as on basic types. You might, therefore, implement ToF64 on your Price type and then go ahead and build your generic algorithm(s) around ToF64, as in:

use base_traits::ToF64;

/// Trivial implementation of a price type using exact types (integers)
#[derive(Debug)]
struct Price {
    dollars : u32,
    cents : u8,
}

impl ToF64 for Price {
    fn to_f64(&self) -> f64 {
        self.dollars as f64 + (self.cents as f64 / 100.0)
    }
}


/// Trivial implementation for calculation of mean and std-deviation
fn calc_mean_and_stddev<'a, F, I>(
    i : I
) -> Option<(
    f64, // mean
    f64, // stddev
)>
where
    F : ToF64 + 'a,
    I : Iterator<Item = &'a F>,
{
    let values = i.map(|v| v.to_f64()).collect::<Vec::<_>>();

    if values.is_empty() {
        None
    } else {
        let n = values.len() as f64;
        let sum : f64 = values.iter().sum();
        let mean = sum / n;
        let ss : f64 = values.iter().map(|v| (v - mean)).map(|v| v*v).sum();
        let var = ss / n;
        let stddev = var.sqrt();

        Some((mean, stddev))
    }
}


fn main() {
    {
        let raw_values = vec![
            // insert list
            10.0,
            10.1,
            10.2,
            10.3,
        ];

        let (raw_mean, raw_stddev) = calc_mean_and_stddev(raw_values.iter()).unwrap();

        println!("for {raw_values:?}, mean={raw_mean}, std-dev={raw_stddev}");
    }

    {
        let prices = vec![
            // insert list
            Price { dollars: 10, cents : 0 },
            Price { dollars: 10, cents : 1 },
            Price { dollars: 10, cents : 2 },
            Price { dollars: 10, cents : 3 },
        ];

        let (price_mean, price_stddev) = calc_mean_and_stddev(prices.iter()).unwrap();

        println!("for {prices:?}, mean={price_mean}, std-dev={price_stddev}");
    }
}

Project Information

Where to get help

GitHub Page

Contribution guidelines

Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/base-traits.

Dependencies

Efferent (fan-out)

Libraries upon which base-traits depends:

Runtime Dependencies

There are no runtime dependencies (aka "normal dependencies") on other crates.

Build Dependencies

Libraries used only when building base-traits (not required by downstream consumers):

• bt-rs — rustc::compiler_version() in build.rs to detect Rust 1.79+ and set the rustc_1_79_or_newer cfg for use of CStr#count_bytes();

Development Dependencies

There are no development dependencies on other crates.

Afferent (fan-in)

Projects that depend on base-traits:

• collect-rs;
• Diagnosticism.Rust;
• shwild.Rust;
• test_help-rs;
• to-be.Rust;

Related projects

License

base-traits is released under the 3-clause BSD license. See LICENSE for details.