From 78ace0ea15faf01b185b895e9f10472441f889bf Mon Sep 17 00:00:00 2001 From: SamuelNoesslboeck Date: Sat, 24 Feb 2024 18:06:30 +0100 Subject: [PATCH] Version 0.1.1 --- Cargo.lock | 2 +- Cargo.toml | 10 +++++++--- README.md | 18 +++++++++++------- src/lib.rs | 39 ++++++++++++++++++++++++++++++--------- 4 files changed, 49 insertions(+), 20 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 201c1c0..dce29b9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -53,7 +53,7 @@ dependencies = [ [[package]] name = "syunit" -version = "0.1.0" +version = "0.1.1" dependencies = [ "serde", ] diff --git a/Cargo.toml b/Cargo.toml index 59c064b..ea1e73c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,13 +1,17 @@ [package] name = "syunit" -version = "0.1.0" +version = "0.1.1" edition = "2021" authors = [ "Samuel Nösslböck " ] -description = "A small library that contains some basic units to help structuring kinematics and robotic programming in rust." +description = "A small library that contains some basic units to help structuring kinematics and robotic programming in rust" repository = "https://github.com/SamuelNoesslboeck/syunit" readme = "README.md" license-file = "LICENSE" keywords = [ "robotics", "kinematics", "unit-system", "math" ] [dependencies] -serde = { version = "1.0.196", features = [ "derive" ] } +serde = { version = "1.0.196", features = [ "derive" ], optional = true } + +[features] +default = [ "serde" ] +serde = [ "dep:serde" ] \ No newline at end of file diff --git a/README.md b/README.md index c8eaea1..6c85d9e 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# syunit +## syunit A small library that contains some basic units to help structuring kinematics and robotic programming in rust. The library uses rusts *tuple structs* to create a zero-overhead and compile-time checking of correct unit, variable and function usage. -## Quick introduction +### Quick introduction In many functions for kinematics and robotics, it sometimes becomes unclear which type of unit is desired to be used, especially when it comes to distances. @@ -42,7 +42,7 @@ fn move_to_distance(dist : Gamma, speed : Velocity) { Each unit is represented by a 32bit float enclosed into a *tuple struct*. Why these units are helpful not only for documentation is explained in the flowing chapters: -### Creation and conversion +#### Creation and conversion As rust always prefers implicit syntax, so does this library. The unit types cannot be converted back to a `f32` without calling `into()`. @@ -78,7 +78,7 @@ requires_velocity(gamma); // | ``` -### Naming +#### Naming As the units are all named after their purpose, the context of functions, their parameters and other variables becomes clear easier. However the library does *not* differentiate between linear and rotary movement in terms of naming. @@ -88,7 +88,7 @@ However there are three units for distances with different names: - `Phi`: Represents an absolute distance in the machines "perspective", often refered to as *mathematical angle/distance* in a lot of documentations. This angle is for example used to describe the rotation of a robot joint, where the `Gamma` angle has an offset compared to the `Phi` angle. - `Delta`: Represents a relative distance -### Operations and automatic type evaluation +#### Operations and automatic type evaluation Especially with distances, a lot of operations between them are restricted, as they would fail to make any sense. For example a `Gamma` distance cannot be added with either a `Phi` or another `Gamma` distance, as it does not make any sense to add two absolute distances. However a `Delta` distance can be added to a `Gamma` or `Phi` distance to extend/shorten said `Gamma` or `Phi` distance. @@ -124,10 +124,14 @@ assert_eq!(Velocity(3.0) / Time(2.0), Acceleration(1.5)); assert_eq!(Velocity(3.0) * Time(3.0), Delta(9.0)); ``` -### Physical background +#### Physical background Each unit of course represents a physical unit, in almost all cases their standardized values. Only difference is distance, it is represented by *millimeters*. Meaning velocity becomes *millimeters per second*, acceleration becomes *millimeters per second squared* ... -## Issues and improvements +### `serde` implementation + +All the units implement `serde::Serialize` and `serde::Deserialize` if the "serde" feature is enabled, which is the case by default. + +### Issues and improvements Please feel free to create issues on the [github repo](https://github.com/SamuelNoesslboeck/syunit) or contact me directly. \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index bb99cb1..02ff367 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,11 +1,13 @@ #![crate_name = "syunit"] #![doc = include_str!("../README.md")] #![no_std] +#![deny(missing_docs)] // Units use core::ops::{Add, AddAssign, Div, Sub, SubAssign}; use core::time::Duration; +#[cfg(feature = "serde")] use serde::{Serialize, Deserialize}; // Helper import for local macro definitions @@ -13,11 +15,13 @@ use crate as syunit; /// General marker trait for all units pub trait Unit : Into { + /// Creates a new value of this unit using a `f32` value fn new(v : f32) -> Self where Self : Sized; } +/// Helper macro that implements everything needed to do +,-,+=,-= operations with the unit itself #[macro_export] macro_rules! additive_unit { ( $unit:ident ) => { @@ -55,6 +59,7 @@ macro_rules! additive_unit { }; } +/// Implements the basics for a unit #[macro_export] macro_rules! basic_unit { ( $a:ident ) => { @@ -98,6 +103,12 @@ macro_rules! basic_unit { Self(self.0.powi(pow)) } + /// Returns the unit raised to the given power `pow` + #[inline(always)] + pub fn powf(self, pow : f32) -> Self { + Self(self.0.powf(pow)) + } + /// Returns the sin of this units value #[inline(always)] pub fn sin(self) -> f32 { @@ -249,6 +260,7 @@ macro_rules! basic_unit { }; } +/// Implements everything required to form a "derive over time like"-connection between the given units #[macro_export] macro_rules! derive_units { ( $dist:ident, $vel:ident, $time:ident ) => { @@ -302,7 +314,8 @@ macro_rules! derive_units { /// // Comparisions /// assert!(Time(1.0) > Time(-1.0)); /// ``` -#[derive(Clone, Copy, Default, Serialize, Deserialize, PartialEq, PartialOrd)] +#[derive(Clone, Copy, Default, PartialEq, PartialOrd)] +#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub struct Time(pub f32); basic_unit!(Time); additive_unit!(Time); @@ -345,7 +358,8 @@ impl Div