Crate bxvl

Expand description

BXVL Library

bxvl is a rust library that allows variables to dynamically keep track of different unit measurements. As these variables are defined and used, they may be converted to other units, metrically scaled, arithmetically combined with others, build new units, and divided into their base units.

§Examples

Creating Values:

use bxvl::value::Value; // Unit type
use bxvl::value;        // Macro definition
use bxvl::units::{Metric, UnitTime::Second, UnitMass::Gram, UnitLength::Meter};

// Slowest
let v1:Value = match "22.3 kg*m/s^2".parse::<Value>() {
  Ok(v) => v,
  Err(e) => panic!("{}", e)
};

// Slow
let v2:Value = value!(22.3, "kg*m/s^2");

// Average
let v3:Value = match Value::new(22.3, "kg*m/s^2") {
  Ok(v) => v,
  Err(e) => panic!("{}", e)
};

// Fastest
let v4:Value = 22.3
  / Second(Metric::None)
  / Second(Metric::None)
  * Gram(Metric::Kilo)
  * Meter(Metric::None);

assert!((v1 == v2) == (v3 == v4));
assert!((v1 == v3) == (v2 == v4));
assert!((v1 == v4) == (v2 == v3));

Creating Values using other Values:

use bxvl::value::Value;
use bxvl::units::{Metric, UnitTime, UnitLength};

let time:Value = 4.0 * UnitTime::Second(Metric::None);
let dist:Value = 16.8 * UnitLength::Meter(Metric::None);

let speed:Value = dist/time;
assert!(speed.is_velocity());
assert_eq!(speed.to_string(), "4.2 m/s");

§Method Support

Values provide similar functionality to many functions that are available to other units such as i32, f32, f64 etc.

use bxvl::value::Value;
use bxvl::units::{Metric, UnitLength};

let m:Value = Value::new(f64::NAN, "feet").unwrap();
if m.is_nan() {
  println!("Our value is not a number!");
}

let a:Value = 1.4 * UnitLength::Meter(Metric::None);
let r:Value = a.sin();
assert!(r.is_radians());
assert!(r.val >= 0.985449);
assert!(r.val < 0.985450);

§Derived Units

Many of the SI units are derived from other base units. When using the values to conduct arithmetic operations, values can be explicitly asked to be ‘complex’ or ‘reduced’.

Making a complex value means combining different types into a new type.

use bxvl::value::Value;

let m:Value = Value::new(2.5, "kg").unwrap();
let acc:Value = Value::new(10.0, "m/s^2").unwrap();

let f1:Value = m*acc;
let f2:Value = (m*acc).complex();
assert!(f1.is_force() && f2.is_force());
assert!(f1.val == f2.val);
assert_eq!(f1.to_string(), "25 m*kg/s^2");
assert_eq!(f2.to_string(), "25 N");

Reducing a value means setting a value to its derived units.

use bxvl::value::Value;

let mut f:Value = Value::new(25.0, "N").unwrap();

assert!(f.is_force());
f.reduce("kg*m/s^2").unwrap();
assert!(f.is_force());
assert_eq!(f.to_string(), "25 m*kg/s^2");

This behavior is explicit and must be called by the user.

§Unit Checking

bxvl provides functions like .is_force() which will return true for both kg*m/s^2 and N. Function support includes all of the base unit types as well as extra unit combinations (See below).

Function	Measurement Types
`is_length()`	Length
`is_area()`	Length^2
`is_volume()`	Volume Length^3
`is_temperature()`	Temperature
`is_mass()`	Mass
`is_density()`	Mass/Volume Mass/Length^3
`is_time()`	Time
`is_substance()`	Substance
`is_angle()`	Angle
`is_solid_angle()`	Solid Angle
`is_information()`	Information
`is_velocity()`	Length/Time
`is_acceleration()`	Length/Time^2
`is_force()`	Force Mass*acceleration
`is_momentum()`	Mass*velocity
`is_frequency()`	Frequency 1/Time
`is_pressure()`	Pressure Force/area Mass/(Length*Time^2)
`is_energy()`	Energy LengthForce Electric PotentialElectric Charge PowerTime Massarea/Time^2
`is_power()`	Power Energy/Time Electrical PotentialElectric Current Massarea/Time^3
`is_electric_charge()`	Electric Charge Electric CurrentTime Electric CapacitanceElectric Potential
`is_electric_current()`	Electric Current
`is_electric_potential()`	Electric Potential Power/Electric Current Energy/Electric Charge
`is_capacitance()`	Electric Capacitance Electric Charge/Electric Potential Energy/Electric Charge
`is_resistance()`	Electric Resistance 1/Electric Conductance Electric Potential/Electric Current
`is_conductance()`	Electric Conductance 1/Electric Resistance Electric Current/Electric Potential
`is_magnetic_flux()`	Magnetic Flux Energy/Electric Current Magnetic Flux Density*area Electric Potential*Time
`is_magnetic_flux_density()`	Magnetic Flux Density Electric PotentialTime/area* Magnetic Flux/area Force/(Electric Current*Length)
`is_inductance()`	Electric Inductance Electric PotentialTime/Electric Current Electric ResistanceTime Magnetic Flux/Electric Current
`is_luminous_flux()`	Luminous Flux
`is_illuminance()`	Illuminance Luminous Flux/area
`is_luminous_intensity()`	Luminous Intensity
`is_radioactivity()`	Radioactivity
`is_absorbed_dose()`	Absorbed Dose
`is_equivalent_dose()`	Equivalent Dose
`is_catalytic_activity()`	Catalytic Activity Substance/Time
`is_sound()`	Sound
`is_jerk()`	Length/Time^3
`is_snap()`	Length/Time^4
`is_angular_velocity()`	Angle/Time
`is_angular_acceleration()`	Angle/Time
`is_frequency_drift()`	Frequency/Time
`is_flow()`	Volume/Time Length^3/Time
`is_angular_momentum()`	ForceLengthTime
`is_torque()`	Force*Length Energy/Angle
`is_energy_density()`	Energy/Volume Energy/Length^3

§Conversions

All Values within their given measurement type will be able to be converted to each other. Values with multiple types, in most cases, can be converted to their compatible types.

Example converting feet into meters:

use bxvl::value::Value;

let mut m:Value = Value::new(3.2, "feet").unwrap();

m.convert("m").unwrap();

There is also direct syntax for this feature:

use bxvl::value::Value;

let mut m:Value = Value::new(5.9, "km/hr").unwrap();

m >>= "m/s";

You can use other Values for conversion:

use bxvl::value::Value;

let m:Value = Value::new(1.2, "yards").unwrap();
let n:Value = Value::new(1.0, "m").unwrap();

let k:Value = (m >> n).unwrap();

The types can also be directly used: (The fastest conversion method)

use bxvl::value::Value;
use bxvl::units::{Metric, UnitLength, UnitTime};

let mut m:Value = Value::new(5.9, "kph").unwrap();

if m.is_velocity() {
  m >>= UnitLength::Meter(Metric::None);
  m >>= UnitTime::Second(Metric::None);
} else {
  panic!();
}

Temperature cannot be converted to another unit if it has other units (like mass) within the value.

Units cannot be converted between disparate types, although there are some exceptions.

Exceptions
Period	Time period (`1/s`)	Frequency (`Hz`)
Volume	Cubic length (`m^3`)	Specific volume (`ml`)

These exceptions are valid conversion so long as they are the only units within a Value. This is to avoid conversion scenarios where Values produce (or are created with) neutralizing units, e.g. mm^3/ml, which is ‘unitless’. Therefore, m/s cannot be converted to m*kHz and m^3/N cannot be converted to ml/N.

§Constants

Some constants are provided for ease of use:

Name	`f64` numeric Value	Units
Absolute Zero	`0.`	$K$
Avogadro’s Number	`6.022_140_76e23`	$mol^{-1}$
Faraday Constant	`96_485.332_123_310_01`	$C \over mol$
Atomic Mass Constant	`1.660_539_066_60e-27`	$kg$
Molar Gas Constant	`8.314_462_1`	$J \over K*mol$
Coulomb’s Constant	`8.987_551`	$mol^{-1}$
The Speed of Light	`299_792_458.0`	$m \over s$
Boltzmann Constant	`1.380_649e-23`	$J \over K$
Earth’s Average Gravitational Acceleration	`9.806_65`	$m \over s^2$
Newtonian Constant of Gravitation	`6.673_015e-11`	$m^3 \over kg*s^2$
Charge of an Electron	`1.602_176_634e-19`	$C$
Rydberg Constant	`10_973_731.568_539`	$m^{-1}$
Plank’s Constant	`6.626_070_15e-34`	$J \over Hz$
Vacuum Permittivity	`8.854_187_812_8e-12`	$F \over m$

use bxvl::{value::{Value, consts}, units::{UnitMass, Metric}};

let acc:Value = consts::EARTH_GRAVITY;
let m:Value = 100.0 * UnitMass::Gram(Metric::Kilo);

let f = (m * acc).complex();

assert_eq!(f.to_string(), "980.665 N");

§Unit Support

The project supports all base SI units as listed by the National Institute of Standards and Technology (NIST) and many units listed by the General Conference on Weights and Measures (CGPM). Some American Imperial Units are also supported.

§Lengths

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Meter	✓	`1.0 m`	`m`
Inch		`0.025_4 m`	`in`, `inch`[`es`]
Foot		`0.304_8 m`	`ft`, `feet` `foot`
Yard		`0.914_4 m`	`yd`[`s`], `yard`[`s`]
Mile		`1_609.344 m`	`mile`[`s`]
Astronomical Unit		`149_569_870_700.0 m`	`AU`
Parsec	✓	`(648_000.0/π)*149_569_870_700.0 m`	`pc`
Light Year	✓	`9_460_730_472_580_800.0 m`	`lyr`
Ångström		`0.000_000_000_1 m`	`Å`, `angstrom`[`s`]

§Time

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Second	✓	`1.0 s`	`s`
Minute		`60.0 s`	`min`, `minute`[`s`]
Hour		`3_600.0 s`	`h`[`r`], `hour`[`s`]
Day		`86_400.0 s`	`d`, `day`[`s`]

§Mass

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Gram	✓	`1.0 g`	`g`
Grain		`453.592_37/7_000.0 g`	`gr`, `grain`[`s`]
Ounce		`453.592_37/16.0 g`	`oz`, `ounce`[`s`]
Pound		`453.592_37 g`	`lb`[`s`], `pounds`

§Electric Current

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Ampere	✓	`1.0 A`	`A`

§Electric Charge

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Coulomb	✓	`1.0 C`	`C`

§Electric Potential

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Volt	✓	`1.0 V`	`V`

§Electric Conductance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Siemens	✓	`1.0 S`	`S`

§Electric Capacitance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Farad	✓	`1.0 F`	`F`, `farad`[`s`]

§Electric Resistance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Ohm	✓	`1.0 Ω`	`Ω` `O`

§Electric Inductance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Henry	✓	`1.0 H`	`H`

§Magnetic Flux

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Weber	✓	`1.0 Wb`	`Wb`

§Magnetic Flux Density

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Tesla	✓	`1.0 T`	`T`

§Thermal Temperature

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Celsius	✓	`c-273.15 K`	`c`, `°`[`Metric Prefix`]`c`, `°C`
Fahrenheit		`((f-32.0)/1.8)-273.15 K`	`f`, `°f`, `°F`
Kelvin	✓	`1.0 K`	`K`

§Substance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Mole	✓	`1.0 mol`	`mol`

§Luminous Intensity

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Candela	✓	`1.0 cd`	`cd`

§Luminous Flux

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Lumen	✓	`1.0 lm`	`lm`

§Illuminance

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Lux	✓	`1.0 lx`	`lx`

§Spatial Volume

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Liter	✓	`1.0 l`	`l`

§Pressure

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Pascal	✓	`1.0 Pa`	`Pa`
Bar	✓	`100_000.0 Pa`	`bar`
Torr		`101_325.0/760.0 Pa`	`torr`
mmHg		`133.322_387_415 Pa`	`mmHg`
cmHg		`1333.22_387_415 Pa`	`cmHg`
inHg		`3_386.388_666_6 Pa`	`inHg`
Atmospheres		`101_325.0 Pa`	`ATM`, `atm`
Pounds per square inch		`6894.757 Pa`	`PSI`, `psi`

§Geometric Angle

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Degree		`π/180.0 rad`	`°`, `degree`[`s`]
Radian	✓	`1.0 rad`	`rad`, `radian`[`s`]
Milliradian	✓	`1_000.0 rad`	`mil`[`s`], `MIL`
Minute of Angle		`π/10_800.0 rad`	`moa`, `MOA`

§Geometric Solid Angle

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Steradian	✓	`1.0 sr`	`sr`

§Frequency

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Hertz	✓	`1.0 Hz`	`Hz`

§Force

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Newton	✓	`1.0 N`	`N`
Pound Force		`4.448_221_615_260_5 N`	`lbfr`, `lbsfr`, `poundforce` `poundsforce`

§Energy

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Joule	✓	`1.0 J`	`J`
Calorie	✓	`4.184 J`	`cal`
Foot pound		`1.355_818 J`	`ftlb`[`s`], `footpound`[`s`]
Electron Volt	✓	`1.6021_766_34e-19 J`	`eV`

§Power

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Watt	✓	`1.0 W`	`W`
Horsepower		`745.699872 W`	`hp`

§Radioactivity

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Becquerel	✓	`1.0 Bq`	`Bq`
Curie		`37_000_000_000.0 Bq`	`Ci`

§Absorbed Dosage of Ionizing Radiation

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Gray	✓	`1.0 Gy`	`Gy`
Röntgen		`0.01 Gy`	`R`
Rad		`1.0/114.025 Gy`	`rads`, `Rads`

§Equivalent Dosage of Ionizing Radiation

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Sievert	✓	`1.0 Sv`	`Sv`
Rem		`0.01 Sv`	`rem`, `Rem`

§Catalytic Activity

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Katal	✓	`1.0 kat`	`kat`

§Sound Intensity

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Bel	✓	`1.0 B`	`B`

§Information

:warning: Metric scaling is in base 2

i.e. kb → 1024 bytes, not 1000 bytes

Unit	Metric Prefixing Support	Base Conversion Factor	Unit string
Bit	`Kilo` - `Quetta`	`8.0 bits == 1.0 byte`	`bits`
Byte	`Kilo` - `Quetta`	`1.0 bytes`	`b`, `byte`[`s`]

§Special Unit Keywords

Unit	Unit string	Equivalent
Miles per hour	`mph`	`miles/hr`
Kilometers per hour	`kph`	`km/hr`
kilocalorie	`Cal`	`kcal`

§Metric Prefix Identifiers

Metric name	Prefix string	Metric Scaling
Quetta	`Q`	$1e30$
Ronna	`R`	$1e27$
Yotta	`Y`	$1e24$
Zetta	`Z`	$1e21$
Exa	`E`	$1e18$
Peta	`P`	$1e15$
Tera	`T`	$1e12$
Giga	`G`	$1e9$
Mega	`M`	$1e6$
Kilo	`k`	$1e3$
Hecto	`h`	$1e2$
Deca	`da`	$1e1$
None		$1$
Deci	`d`	$1e-1$
Centi	`c`	$1e-2$
Milli	`m`	$1e-3$
Micro	`μ` `u`	$1e-6$
Nano	`n`	$1e-9$
Pico	`p`	$1e-12$
Femto	`f`	$1e-15$
Atto	`a`	$1e-18$
Zepto	`z`	$1e-21$
Yocto	`y`	$1e-24$
Ronto	`r`	$1e-27$
Quecto	`q`	$1e-30$

Note that some unit strings like eV could be indented to be Exa-Volts or Electron Volts. The library is case sensitive and will default to the ‘least complex’ unit that matches. So Electron Volts will be the parsed result. To get Exa-Volts, the user must properly specify EV or simply V for volts and then convert to the Exa metric scaler.

Modules§

consts: Various const definitions that are used throughout [bxvl]
errors: The module for [bxvl] specific error definitions
units: The main module for [Metric] and [Unit] types
value: The module used for [Value] implementations

Macros§

create_defs: The [create_defs] macro is used to define operations for primitive type operations with values.
value: Macro to create a new Value

Constants§

VERSION: The BXVL Library Version

Crate bxvl

Crate bxvl Copy item path

§Table of Contents

§Examples

§Method Support

§Derived Units

§Unit Checking

§Conversions

§Constants

§Unit Support

§Lengths

§Time

§Mass

§Electric Current

§Electric Charge

§Electric Potential

§Electric Conductance

§Electric Capacitance

§Electric Resistance

§Electric Inductance

§Magnetic Flux

§Magnetic Flux Density

§Thermal Temperature

§Substance

§Luminous Intensity

§Luminous Flux

§Illuminance

§Spatial Volume

§Pressure

§Geometric Angle

§Geometric Solid Angle

§Frequency

§Force

§Energy

§Power

§Radioactivity

§Absorbed Dosage of Ionizing Radiation

§Equivalent Dosage of Ionizing Radiation

§Catalytic Activity

§Sound Intensity

§Information

§Special Unit Keywords

§Metric Prefix Identifiers

Modules§

Macros§

Constants§

Crate bxvl