Implement quantity-aware plotting

Author: kojix2

spec/reference_spec.cr

@@ -319,10 +319,12 @@ describe "Julia reference output compatibility" do
 
     it "matches lineplot/units_pos_vel" do
       t = (0..100).map(&.to_f64)
-      pos = t.map { |val| 0.5 * val * val }
-      vel = t
+      pos_values = t.map { |val| 0.5 * val * val }
+      vel_values = t
+      pos = UnicodePlot.quantity(pos_values, "m")
+      vel = UnicodePlot.quantity(vel_values, "m s⁻¹")
       p = UnicodePlot.lineplot(pos, vel, xlabel: "position (m)", ylabel: "speed (m s⁻¹)")
-      UnicodePlot.lineplot!(p, [pos.min, pos.max], [vel.max, vel.max], color: :red)
+      UnicodePlot.lineplot!(p, [pos_values.min, pos_values.max], [vel_values.max, vel_values.max], color: :red)
       test_ref("lineplot/units_pos_vel.txt", p)
     end
 
@@ -516,12 +518,10 @@ describe "Julia reference output compatibility" do
     end
 
     it "matches scatterplot/units_temp" do
-      p = UnicodePlot.scatterplot(
-        [22.0, 23.0, 24.0],
-        marker: :circle,
-        ylabel: "°C",
-      )
-      UnicodePlot.scatterplot!(p, [23.5, 22.5, 23.0], marker: :cross, color: :red)
+      y1 = UnicodePlot.quantity([22.0, 23.0, 24.0], "°C")
+      p = UnicodePlot.scatterplot(y1, marker: :circle)
+      y2 = UnicodePlot.quantity([23.5, 22.5, 23.0], "°C")
+      UnicodePlot.scatterplot!(p, y2, marker: :cross, color: :red)
       test_ref("scatterplot/units_temp.txt", p)
     end
   end

spec/unicode_plot_spec.cr

@@ -129,6 +129,22 @@ describe UnicodePlot do
       p = UnicodePlot.lineplot([Float64::MAX, 0.5], [0.5, 0.5])
       p.to_s.should be_a(String)
     end
+
+    it "auto-applies unit labels from quantity arrays" do
+      x = UnicodePlot.quantity([0.0, 1.0, 2.0], "m")
+      y = UnicodePlot.quantity([0.0, 1.0, 4.0], "m s⁻¹")
+      p = UnicodePlot.lineplot(x, y)
+      p.xlabel.should eq("m")
+      p.ylabel.should eq("m s⁻¹")
+    end
+
+    it "raises on mixed units within one axis" do
+      x = [UnicodePlot.quantity(0.0, "m"), UnicodePlot.quantity(1.0, "cm")]
+      y = [0.0, 1.0]
+      expect_raises(ArgumentError, /mixed units/) do
+        UnicodePlot.lineplot(x, y)
+      end
+    end
   end
 
   describe "scatterplot" do
@@ -186,6 +202,12 @@ describe UnicodePlot do
       UnicodePlot.scatterplot!(p, [4, 5, 6])
       p.series.should eq(prev_series + 1)
     end
+
+    it "auto-applies y label from quantity y-only input" do
+      y = UnicodePlot.quantity([22.0, 23.0, 24.0], "°C")
+      p = UnicodePlot.scatterplot(y)
+      p.ylabel.should eq("°C")
+    end
   end
 
   describe "barplot" do

src/unicode_plot/common.cr

@@ -1,4 +1,13 @@
 module UnicodePlot
+  struct Quantity
+    getter value : Float64
+    getter unit : String
+
+    def initialize(value : Number, @unit : String)
+      @value = value.to_f64
+    end
+  end
+
   BLANK         = 0x0020_u32
   BLANK_BRAILLE = 0x2800_u32
   FULL_BRAILLE  = 0x28ff_u32
@@ -176,6 +185,45 @@ module UnicodePlot
     marker[0]
   end
 
+  def quantity(value : Number, unit : String) : Quantity
+    Quantity.new(value, unit)
+  end
+
+  def quantity(values : Array(T), unit : String) : Array(Quantity) forall T
+    {% unless T <= Number %}
+      {% raise "quantity(values, unit) requires numeric array elements" %}
+    {% end %}
+    values.map { |v| Quantity.new(v.to_f64, unit) }
+  end
+
+  def unit_label(label : String, unit : String?) : String
+    stripped = label.rstrip
+    return stripped unless unit
+    unit_suffix = "(#{unit})"
+    return stripped if stripped.ends_with?(unit_suffix)
+    stripped.empty? ? unit : "#{stripped} (#{unit})"
+  end
+
+  def number_unit(values : Array(Quantity)) : {Array(Float64), String?}
+    return {[] of Float64, nil} if values.empty?
+    unit = values.first.unit
+    nums = Array(Float64).new(values.size)
+    values.each do |quantity|
+      unless quantity.unit == unit
+        raise ArgumentError.new("mixed units are not supported in one axis: #{unit} and #{quantity.unit}")
+      end
+      nums << quantity.value
+    end
+    {nums, unit}
+  end
+
+  def number_unit(values : Array(T)) : {Array(Float64), String?} forall T
+    {% unless T <= Number %}
+      {% raise "number_unit requires numeric array elements" %}
+    {% end %}
+    {to_plot_f64(values), nil}
+  end
+
   private def to_plot_f64(values : Array(T)) : Array(Float64) forall T
     {% unless T <= Number %}
       {% raise "to_plot_f64 requires numeric array elements" %}