1.0.0.

Implement Spline::add.

.github/workflows/ci.yaml

@@ -0,0 +1,39 @@
+name: CI
+on: [push]
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Build
+        run: cargo build --verbose
+      - name: Test
+        run: cargo test --verbose
+
+  build-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Build
+        run: cargo build --verbose
+      - name: Test
+        run: cargo test --verbose
+
+  build-macosx:
+    runs-on: macosx-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Build
+        run: cargo build --verbose
+      - name: Test
+        run: cargo test --verbose
+
+  check-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Install cargo-sync-readme
+        run: cargo install --force cargo-sync-readme
+      - name: Check
+        run: cargo sync-readme -c

.travis.yml

@@ -1,23 +0,0 @@
-language: rust
-
-rust:
-  - stable
-  - beta
-  - nightly
-
-os:
-  - linux
-  - osx
-
-script:
-  - rustc --version
-  - cargo --version
-  - echo "Testing default crate configuration"
-  - cargo build --verbose
-  - cargo test --verbose
-  - cd examples && cargo check --verbose
-  - echo "Testing feature serialization"
-  - cargo build --verbose --features serialization
-  - cargo test --verbose --features serialization
-  - echo "Building without std"
-  - cargo build --verbose --no-default-features

CHANGELOG.md

@@ -1,43 +1,65 @@
-## 0.2.3
+# 1.0
+
+> Sun Sep 22th 2019
+
+## Major changes
+
+- Make `Spline::clamped_sample` failible via `Option` instead of panicking.
+- Add support for polymorphic sampling type.
+
+## Minor changes
+
+- Add the `std` feature (and hence support for `no_std`).
+- Add `impl-nalgebra` feature.
+- Add `impl-cgmath` feature.
+- Add support for adding keys to splines.
+- Add support for removing keys from splines.
+
+## Patch changes
+
+- Migrate to Rust 2018.
+- Documentation typo fixes.
+
+# 0.2.3
 
 > Sat 13th October 2018
 
-  - Add the `"impl-nalgebra"` feature gate. It gives access to some implementors for the `nalgebra`
-    crate.
-  - Enhance the documentation.
+- Add the `"impl-nalgebra"` feature gate. It gives access to some implementors for the `nalgebra`
+  crate.
+- Enhance the documentation.
 
-## 0.2.2
+# 0.2.2
 
 > Sun 30th September 2018
 
-  - Bump version numbers (`splines-0.2`) in examples.
-  - Fix several typos in the documentation.
+- Bump version numbers (`splines-0.2`) in examples.
+- Fix several typos in the documentation.
 
-## 0.2.1
+# 0.2.1
 
 > Thu 20th September 2018
 
-  - Enhance the features documentation.
+- Enhance the features documentation.
 
 # 0.2
 
 > Thu 6th September 2018
 
-  - Add the `"std"` feature gate, that can be used to compile with the standard library.
-  - Add the `"impl-cgmath"` feature gate in order to make optional, if wanted, the `cgmath`
-    dependency.
-  - Enhance the documentation.
+- Add the `"std"` feature gate, that can be used to compile with the standard library.
+- Add the `"impl-cgmath"` feature gate in order to make optional, if wanted, the `cgmath`
+  dependency.
+- Enhance the documentation.
 
-## 0.1.1
+# 0.1.1
 
 > Wed 8th August 2018
 
-  - Add a feature gate, `"serialization"`, that can be used to automatically derive `Serialize` and
-    `Deserialize` from the [serde](https://crates.io/crates/serde) crate.
-  - Enhance the documentation.
+- Add a feature gate, `"serialization"`, that can be used to automatically derive `Serialize` and
+  `Deserialize` from the [serde](https://crates.io/crates/serde) crate.
+- Enhance the documentation.
 
 # 0.1
 
 > Sunday 5th August 2018
 
-  - Initial revision.
+- Initial revision.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "splines"
-version = "1.0.0-rc.2"
+version = "1.0.0"
 license = "BSD-3-Clause"
 authors = ["Dimitri Sabadie <dimitri.sabadie@gmail.com>"]
 description = "Spline interpolation made easy"
@@ -33,3 +33,6 @@ nalgebra = { version = ">=0.14, <0.19", optional = true }
 num-traits = { version = "0.2", optional = true }
 serde =  { version = "1", optional = true }
 serde_derive = { version = "1", optional = true }
+
+[package.metadata.docs.rs]
+all-features = true

README.md

@@ -13,9 +13,9 @@ switch to a cubic Hermite interpolator for the next section.
 
 Most of the crate consists of three types:
 
-- [`Key`], which represents the control points by which the spline must pass.
-- [`Interpolation`], the type of possible interpolation for each segment.
-- [`Spline`], a spline from which you can *sample* points by interpolation.
+  - [`Key`], which represents the control points by which the spline must pass.
+  - [`Interpolation`], the type of possible interpolation for each segment.
+  - [`Spline`], a spline from which you can *sample* points by interpolation.
 
 When adding control points, you add new sections. Two control points define a section – i.e.
 it’s not possible to define a spline without at least two control points. Every time you add a
@@ -40,17 +40,13 @@ key. We use the default one because we don’t care.
 # Interpolate values
 
 The whole purpose of splines is to interpolate discrete values to yield continuous ones. This is
-usually done with the `Spline::sample` method. This method expects the interpolation parameter
+usually done with the [`Spline::sample`] method. This method expects the sampling parameter
 (often, this will be the time of your simulation) as argument and will yield an interpolated
 value.
 
-If you try to sample in out-of-bounds interpolation parameter, you’ll get no value.
+If you try to sample in out-of-bounds sampling parameter, you’ll get no value.
 
 ```
-# use splines::{Interpolation, Key, Spline};
-# let start = Key::new(0., 0., Interpolation::Linear);
-# let end = Key::new(1., 10., Interpolation::Linear);
-# let spline = Spline::from_vec(vec![start, end]);
 assert_eq!(spline.sample(0.), Some(0.));
 assert_eq!(spline.clamped_sample(1.), Some(10.));
 assert_eq!(spline.sample(1.1), None);
@@ -61,14 +57,17 @@ important for simulations / animations. Feel free to use the `Spline::clamped_in
 that purpose.
 
 ```
-# use splines::{Interpolation, Key, Spline};
-# let start = Key::new(0., 0., Interpolation::Linear);
-# let end = Key::new(1., 10., Interpolation::Linear);
-# let spline = Spline::from_vec(vec![start, end]);
 assert_eq!(spline.clamped_sample(-0.9), Some(0.)); // clamped to the first key
 assert_eq!(spline.clamped_sample(1.1), Some(10.)); // clamped to the last key
 ```
 
+# Polymorphic sampling types
+
+[`Spline`] curves are parametered both by the carried value (being interpolated) but also the
+sampling type. It’s very typical to use `f32` or `f64` but really, you can in theory use any
+kind of type; that type must, however, implement a contract defined by a set of traits to
+implement. See [the documentation of this module](crate::interpolate) for further details.
+
 # Features and customization
 
 This crate was written with features baked in and hidden behind feature-gates. The idea is that
@@ -84,20 +83,20 @@ not. It’s especially important to see how it copes with the documentation.
 
 So here’s a list of currently supported features and how to enable them:
 
-- **Serialization / deserialization.**
-+ This feature implements both the `Serialize` and `Deserialize` traits from `serde` for all
-types exported by this crate.
-+ Enable with the `"serialization"` feature.
-- **[cgmath](https://crates.io/crates/cgmath) implementors.**
-+ Adds some useful implementations of `Interpolate` for some cgmath types.
-+ Enable with the `"impl-cgmath"` feature.
-- **[nalgebra](https://crates.io/crates/nalgebra) implementors.**
-+ Adds some useful implementations of `Interpolate` for some nalgebra types.
-+ Enable with the `"impl-nalgebra"` feature.
-- **Standard library / no standard library.**
-+ It’s possible to compile against the standard library or go on your own without it.
-+ Compiling with the standard library is enabled by default.
-+ Use `default-features = []` in your `Cargo.toml` to disable.
-+ Enable explicitly with the `"std"` feature.
+  - **Serialization / deserialization.**
+    + This feature implements both the `Serialize` and `Deserialize` traits from `serde` for all
+      types exported by this crate.
+    + Enable with the `"serialization"` feature.
+  - **[cgmath](https://crates.io/crates/cgmath) implementors.**
+    + Adds some useful implementations of `Interpolate` for some cgmath types.
+    + Enable with the `"impl-cgmath"` feature.
+  - **[nalgebra](https://crates.io/crates/nalgebra) implementors.**
+    + Adds some useful implementations of `Interpolate` for some nalgebra types.
+    + Enable with the `"impl-nalgebra"` feature.
+  - **Standard library / no standard library.**
+    + It’s possible to compile against the standard library or go on your own without it.
+    + Compiling with the standard library is enabled by default.
+    + Use `default-features = []` in your `Cargo.toml` to disable.
+    + Enable explicitly with the `"std"` feature.
 
 <!-- cargo-sync-readme end -->

src/interpolation.rs

@@ -5,7 +5,7 @@
 /// Available kind of interpolations.
 ///
 /// Feel free to visit each variant for more documentation.
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
 pub enum Interpolation<T> {

src/key.rs

@@ -17,7 +17,7 @@ use crate::interpolation::Interpolation;
 /// key and the next one – if existing. Have a look at [`Interpolation`] for further details.
 ///
 /// [`Interpolation`]: crate::interpolation::Interpolation
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
 pub struct Key<T, V> {

src/nalgebra.rs

@@ -1,9 +1,5 @@
 use alga::general::{ClosedAdd, ClosedDiv, ClosedMul, ClosedSub};
-use nalgebra::{
-  DefaultAllocator, DimName, Point, Scalar, Vector, Vector1, Vector2, Vector3, Vector4, Vector5,
-  Vector6
-};
-use nalgebra::allocator::Allocator;
+use nalgebra::{Scalar, Vector, Vector1, Vector2, Vector3, Vector4, Vector5, Vector6};
 use num_traits as nt;
 use std::ops::Mul;
 
@@ -12,7 +8,7 @@ use crate::interpolate::{Interpolate, Linear, Additive, One, cubic_hermite_def};
 macro_rules! impl_interpolate_vector {
   ($($t:tt)*) => {
     // implement Linear
-    impl<T> Linear<T> for $($t)*<T> where T: Scalar + ClosedMul + ClosedDiv {
+    impl<T> Linear<T> for $($t)*<T> where T: Scalar + ClosedAdd + ClosedSub + ClosedMul + ClosedDiv {
       #[inline(always)]
       fn outer_mul(self, t: T) -> Self {
         self * t
@@ -54,19 +50,3 @@ impl_interpolate_vector!(Vector3);
 impl_interpolate_vector!(Vector4);
 impl_interpolate_vector!(Vector5);
 impl_interpolate_vector!(Vector6);
-
-impl<T, D> Linear<T> for Point<T, D>
-where D: DimName,
-      DefaultAllocator: Allocator<T, D>,
-      <DefaultAllocator as Allocator<T, D>>::Buffer: Copy,
-      T: Scalar + ClosedDiv + ClosedMul {
-  #[inline(always)]
-  fn outer_mul(self, t: T) -> Self {
-    self * t
-  }
-
-  #[inline(always)]
-  fn outer_div(self, t: T) -> Self {
-    self / t
-  }
-}

src/spline.rs

@@ -28,12 +28,17 @@ use crate::key::Key;
 pub struct Spline<T, V>(pub(crate) Vec<Key<T, V>>);
 
 impl<T, V> Spline<T, V> {
+  /// Internal sort to ensure invariant of sorting keys is valid.
+  fn internal_sort(&mut self) where T: PartialOrd {
+    self.0.sort_by(|k0, k1| k0.t.partial_cmp(&k1.t).unwrap_or(Ordering::Less));
+  }
+
   /// Create a new spline out of keys. The keys don’t have to be sorted even though it’s recommended
   /// to provide ascending sorted ones (for performance purposes).
-  pub fn from_vec(mut keys: Vec<Key<T, V>>) -> Self where T: PartialOrd {
-    keys.sort_by(|k0, k1| k0.t.partial_cmp(&k1.t).unwrap_or(Ordering::Less));
-
-    Spline(keys)
+  pub fn from_vec(keys: Vec<Key<T, V>>) -> Self where T: PartialOrd {
+    let mut spline = Spline(keys);
+    spline.internal_sort();
+    spline
   }
 
   /// Create a new spline by consuming an `Iterater<Item = Key<T>>`. They keys don’t have to be
@@ -42,7 +47,7 @@ impl<T, V> Spline<T, V> {
   /// # Note on iterators
   ///
   /// It’s valid to use any iterator that implements `Iterator<Item = Key<T>>`. However, you should
-  /// use [`Spline::from_vec`] if you are passing a [`Vec`]. This will remove dynamic allocations.
+  /// use [`Spline::from_vec`] if you are passing a [`Vec`].
   pub fn from_iter<I>(iter: I) -> Self where I: Iterator<Item = Key<T, V>>, T: PartialOrd {
     Self::from_vec(iter.collect())
   }
@@ -52,6 +57,18 @@ impl<T, V> Spline<T, V> {
     &self.0
   }
 
+  /// Number of keys.
+  #[inline(always)]
+  pub fn len(&self) -> usize {
+    self.0.len()
+  }
+
+  /// Check whether the spline has no key.
+  #[inline(always)]
+  pub fn is_empty(&self) -> bool {
+    self.0.is_empty()
+  }
+
   /// Sample a spline at a given time.
   ///
   /// The current implementation, based on immutability, cannot perform in constant time. This means
@@ -146,6 +163,21 @@ impl<T, V> Spline<T, V> {
       }
     })
   }
+
+  /// Add a key into the spline.
+  pub fn add(&mut self, key: Key<T, V>) where T: PartialOrd {
+    self.0.push(key);
+    self.internal_sort();
+  }
+
+  /// Remove a key from the spline.
+  pub fn remove(&mut self, index: usize) -> Option<Key<T, V>> {
+    if index >= self.0.len() {
+      None
+    } else {
+      Some(self.0.remove(index))
+    }
+  }
 }
 
 // Normalize a time ([0;1]) given two control points.

tests/mod.rs

@@ -172,3 +172,51 @@ fn nalgebra_vector_interpolation() {
   assert_eq!(Interpolate::lerp(start, end, 1.0), end);
   assert_eq!(Interpolate::lerp(start, end, 0.5), mid);
 }
+
+#[test]
+fn add_key_empty() {
+  let mut spline: Spline<f32, f32> = Spline::from_vec(vec![]);
+  spline.add(Key::new(0., 0., Interpolation::Linear));
+
+  assert_eq!(spline.keys(), &[Key::new(0., 0., Interpolation::Linear)]);
+}
+
+#[test]
+fn add_key() {
+  let start = Key::new(0., 0., Interpolation::Step(0.5));
+  let k1 = Key::new(1., 5., Interpolation::Linear);
+  let k2 = Key::new(2., 0., Interpolation::Step(0.1));
+  let k3 = Key::new(3., 1., Interpolation::Linear);
+  let k4 = Key::new(10., 2., Interpolation::Linear);
+  let end = Key::new(11., 4., Interpolation::default());
+  let new = Key::new(2.4, 40., Interpolation::Linear);
+  let mut spline = Spline::from_vec(vec![start, k1, k2.clone(), k3, k4, end]);
+
+  assert_eq!(spline.keys(), &[start, k1, k2, k3, k4, end]);
+  spline.add(new);
+  assert_eq!(spline.keys(), &[start, k1, k2, new, k3, k4, end]);
+}
+
+#[test]
+fn remove_element_empty() {
+  let mut spline: Spline<f32, f32> = Spline::from_vec(vec![]);
+  let removed = spline.remove(0);
+
+  assert_eq!(removed, None);
+  assert!(spline.is_empty());
+}
+
+#[test]
+fn remove_element() {
+  let start = Key::new(0., 0., Interpolation::Step(0.5));
+  let k1 = Key::new(1., 5., Interpolation::Linear);
+  let k2 = Key::new(2., 0., Interpolation::Step(0.1));
+  let k3 = Key::new(3., 1., Interpolation::Linear);
+  let k4 = Key::new(10., 2., Interpolation::Linear);
+  let end = Key::new(11., 4., Interpolation::default());
+  let mut spline = Spline::from_vec(vec![start, k1, k2.clone(), k3, k4, end]);
+  let removed = spline.remove(2);
+
+  assert_eq!(removed, Some(k2));
+  assert_eq!(spline.len(), 5);
+}