tonal-tools 8.3.2 → 8.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edaeefa4c9e85628de77bdc793e7bf185c66b7f77449201180972798bc8c03e4
-  data.tar.gz: c084919a42c7d53a030b208dfcadb3b6b3435a2da23393736ca7aa8a697a0866
+  metadata.gz: e4abf5cbb165cd0add4c91cc6d4394219076e7ab5bc02ac52288f6d3f6c278e1
+  data.tar.gz: 405af2ddb5dcbf483c3dca44a1ba6307d283f0d85b28d20b65c916178963b7d6
 SHA512:
-  metadata.gz: 391772bbd5096b18ced768e099f093b5d477a022cd6540a858129abddd5479d00a36e717c81a72af5c5251f71ff5de8ebe7bd6265e168993c58e00f44038562c
-  data.tar.gz: 1d90f075280b353130e0df41f21b8993b614fa82c22dd9513ba135641895b86efc570face1f389427837ee5bfb6ffcbfa0619bcfe819b731b59a6f66e1e3f67b
+  metadata.gz: c516d5914d93c9f563cf0b9b71d2d15c89f408c159010899ea9552d82d176d193c62cd7463ed44c6e287c67efc9091979e5ca7aa4ed3b37d0453e9bebd02690c
+  data.tar.gz: 72ea362063ea441c121200cc0ec6b9aa6e789047f9090218a3b7d1dbe156c8f0614e88b67911ecbfbc635d7919671f32f41c0f87ea1f66938eb26bd55090e006

data/lib/tonal/attributions.rb

@@ -1,4 +1,4 @@
 module Tonal
   TOOLS_PRODUCER = "mTonal"
-  TOOLS_VERSION = "8.3.2"
+  TOOLS_VERSION = "8.3.3"
 end

data/lib/tonal/extensions.rb

@@ -145,10 +145,13 @@ class Numeric
   # @return [Float] the cents difference between self and its step in the given modulo
   # @example
   #   (3/2r).efficiency(12) => -1.96
-  # @param modulo
-  # @param reduced
+  # @example
+  #   (3/2r).efficiency(12, is_step_efficiency: true) => 1.96
+  # @param modulo against which the difference of self is compared
+  # @param reduced if true, self is reduced to the octave before calculating efficiency
+  # @param is_step_efficiency if true, calculates the efficiency of the step instead of the ratio (self). If the step efficiency is X cents, then the ratio efficiency is -X cents.
   #
-  def efficiency(modulo, reduced: false) = ratio(reduced:).efficiency(modulo)
+  def efficiency(modulo, reduced: false, is_step_efficiency: false) = ratio(reduced:).efficiency(modulo, is_step_efficiency:)
 
   # @return [Tonal::Interval] beween self (upper) and ratio (lower)
   # @example

data/lib/tonal/ratio.rb

@@ -5,6 +5,7 @@ class Tonal::Ratio
   def_delegators :@approximation, :neighborhood
 
   PRECISION = 2
+  DEFAULT_EQUAVE = 2/1r
 
   attr_reader :antecedent, :consequent, :equave, :reduced_antecedent, :reduced_consequent
 
@@ -16,7 +17,7 @@ class Tonal::Ratio
   # @param antecedent [Numeric, Tonal::Ratio]
   # @param consequent [Numeric, Tonal::Ratio]
   #
-  def initialize(antecedent, consequent=nil, label: nil, equave: 2/1r)
+  def initialize(antecedent, consequent=nil, label: nil, equave: DEFAULT_EQUAVE)
     raise ArgumentError, "Antecedent must be Numeric" unless antecedent.kind_of?(Numeric)
     raise ArgumentError, "Consequent must be Numeric or nil" unless (consequent.kind_of?(Numeric) || consequent.nil?)
 
@@ -79,8 +80,8 @@ class Tonal::Ratio
   # @param step the step number in the equal division of the equave
   # @param equave the interval of equivalence, default 2/1
   #
-  def self.ed(step, modulo, equave: 2/1r)
-    self.new(2**(step.to_f/modulo), equave: equave)
+  def self.ed(step, modulo, equave: DEFAULT_EQUAVE)
+    self.new(2**(step.to_f/modulo), equave:)
   end
 
   # @return [Boolean] if pair of ratios are within the given cents limit
@@ -213,7 +214,7 @@ class Tonal::Ratio
   #   Tonal::Ratio.new(48,14).equave_reduce(3) => 8/7
   # @param equave Numeric
   #
-  def equave_reduce(equave=2/1r)
+  def equave_reduce(equave=DEFAULT_EQUAVE)
     self.class.new(*_equave_reduce(equave))
   end
   alias :reduce :equave_reduce
@@ -224,7 +225,7 @@ class Tonal::Ratio
   #   Tonal::Ratio.new(48,14).equave_reduce!(3) => 8/7
   # @param equave Numeric
   #
-  def equave_reduce!(equave=2/1r)
+  def equave_reduce!(equave=DEFAULT_EQUAVE)
     @antecedent, @consequent = _equave_reduce(equave)
     self
   end
@@ -430,10 +431,10 @@ class Tonal::Ratio
   #   Tonal::ReducedRatio.new(3,2).efficiency(12) => -1.96
   # @param modulo against which the difference of self is compared
   #
-  def efficiency(modulo)
-    # We want the efficiency from the ratio (self).
+  def efficiency(modulo, is_step_efficiency: false)
+    # For single ratios, we normally want the efficiency from the ratio (self).
     # If the step efficiency is X cents, then the ratio efficiency is -X cents.
-    step(modulo).efficiency * -1.0
+    step(modulo).efficiency * (is_step_efficiency ? 1.0 : -1.0)
   end
 
   # @return [Array] the results of ratio dividing and multiplying self
@@ -459,12 +460,13 @@ class Tonal::Ratio
 
   # @return [Tonal::Cents] cent difference between self and other ratio
   # @example
-  #   Tonal::ReducedRatio.new(3,2).cent_diff(4/3r) => 203.92
+  #   Tonal::ReducedRatio.new(3,2).cents_difference_with(4/3r) => 203.92
   # @param other_ratio [Tonal::ReducedRatio, Numeric] from which self's cents is measured
   #
-  def cent_diff(other_ratio)
-    cents - other_ratio.ratio.cents
+  def cents_difference_with(other_ratio)
+    to_cents - other_ratio.ratio.to_cents
   end
+  alias :cent_diff :cents_difference_with
 
   # @return [Integer] the least common multiple with self's denominator and the given number's denominator
   # @example
@@ -649,7 +651,7 @@ class Tonal::Ratio
   end
 
   private
-  def _initialize(antecedent, consequent=nil, label: nil, equave: 2/1r)
+  def _initialize(antecedent, consequent=nil, label: nil, equave: DEFAULT_EQUAVE)
     if consequent
       @antecedent = antecedent.abs
       @consequent = consequent.abs
@@ -668,7 +670,7 @@ class Tonal::Ratio
     raise ArgumentError, "Arguments must be greater than zero" if args.any?{|i| i < 0 }
   end
 
-  def _equave_reduce(equave=2/1r)
+  def _equave_reduce(equave=DEFAULT_EQUAVE)
     case to_r
     when Float::INFINITY
       ante, cons = antecedent, 0

data/lib/tonal/step.rb

@@ -85,6 +85,7 @@ class Tonal::Scale
       # We want the efficiency from the step (self).
       ratio_to_cents - step_to_cents
     end
+    alias :cents_difference :efficiency
 
     def +(rhs)
       self.class.new(step: (rhs % modulo), modulo: modulo)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tonal-tools
 version: !ruby/object:Gem::Version
-  version: 8.3.2
+  version: 8.3.3
 platform: ruby
 authors:
 - Jose Hales-Garcia
 bindir: bin
 cert_chain: []
-date: 2026-02-15 00:00:00.000000000 Z
+date: 2026-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -192,7 +192,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '3.1'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Tonal tools
 test_files: []