[R] 重构BaseChart类，将BpmList、MetList、Sort、Shift等方法全都放到BaseChart类去，让BaseChart类承担更通用的功能；MaiChart类现在只提供ClockCount、IsDxChart、Statistics等特定于maimai的属性，同时根据maimai自己的规则override相关的父类属性/方法。

Author: Starrah

chart/BPMList.cs

@@ -10,18 +10,7 @@ public class BPMList : List<BPM>
     public BPMList() {}
     public BPMList(IEnumerable<BPM> bpms): base(bpms) {}
 
-    public Rational ToSecond(Rational barTime)
-    {
-        Utils.Assert(this[0].Time == 0, "BPM列表的开头必须为0时刻");
-        Rational accumulation = 0;
-        for (int i = 0; i < Count; i++)
-        {
-            var bpmRangeEnd = i < Count - 1 ? this[i + 1].Time : 999999;
-            accumulation += 240 / (Rational)this[i].Bpm * (Utils.Min(barTime, bpmRangeEnd) - this[i].Time);
-            if (barTime <= bpmRangeEnd) break;
-        }
-        return accumulation;
-    }
+    public Rational ToSecond(Rational barTime) => ConvertTime(0, barTime, null, 240);
 
     public int FindIndex(Rational time)
     {
@@ -51,6 +40,72 @@ private string DebuggerDisplay()
 
         return result;
     }
+    
+    /**
+     * 用于在不同格式的时间数值之间换算的函数。
+     * 把从startTime起、长为value的一段分数时间，从srcBpm下换算到dstBpm下。
+     *
+     * 首先指出一个重要原理：Seconds格式下以秒为单位的时间，在数值上实际等价于 240bpm下的不变小节时间。这就是为什么可以构造一个通用的转换函数的原理。
+     *
+     * <param name="value">要被转换的时间值</param>
+     * <param name="srcBpm">value原始值所基准的bpm。若为null，表示使用BPMList中动态的bpm(对应把Bar转换为其他类型的情况)</param>
+     * <param name="dstBpm">想要换算到的目标bpm。若为null，表示使用BPMList中动态的bpm(对应把其他类型转换为Bar的情况)</param>
+     */
+    internal Rational ConvertTime(Rational startTime, Rational value, decimal? srcBpm, decimal? dstBpm)
+    {
+        Rational? srcBpmR = srcBpm != null ? (Rational?)srcBpm : null;
+        Rational? dstBpmR = dstBpm != null ? (Rational?)dstBpm : null;
+        if (srcBpmR != null && dstBpmR != null)
+        {
+            // 静态的src和dst，直接算一下即可，无需遍历bpm表
+            return (value * (dstBpmR.Value / srcBpmR.Value)).CanonicalForm;
+        }
+        else
+        {
+            var rangeStart = startTime;
+            var bpmIndex = FindIndex(rangeStart);
+            Utils.Assert(bpmIndex >= 0, "startTime不应该在BPM表的范围之外！是否是BPM表没有以0时刻为开头造成的？");
+            Rational result = 0;
+            Rational remain = value;
+            while (remain > 0)
+            {
+                // 当前所处bpm区间的结束位置。如果当前已经是最后一个区间了，则结束位置写成一个很大的数就可以了，反正本轮remain一定会被清空
+                var bpmRangeEnd = bpmIndex < Count - 1 ? this[bpmIndex + 1].Time : 9999999;
+                // 本区间可以消耗掉remain的最大数量，以src的bpm为单位。
+                Rational curRangeCapacity = bpmRangeEnd - rangeStart;
+                
+                var srcBpmNow = srcBpmR; // 每次循环要复制一份srcBpm，不然直接改了srcBpm的话，再次循环时逻辑就不对了
+                var dstBpmNow = dstBpmR;
+                if (srcBpmNow == null)
+                { // 如果srcBpm传入的是None，说明应该使用当前的实时bpm作为srcBpm
+                    srcBpmNow = (Rational)this[bpmIndex].Bpm;
+                    // 此时capacity已经是以srcBpm为单位了，无需再转换
+                }
+                else if (dstBpmNow == null)
+                {
+                    dstBpmNow = (Rational)this[bpmIndex].Bpm;
+                    // 此时capacity是基于可变bpm即dstBpm的，需要换算到srcBpm上
+                    curRangeCapacity *= (srcBpmNow.Value / dstBpmNow.Value);
+                }
+
+                Rational toSubtract = curRangeCapacity < remain ? curRangeCapacity : remain; // 要从remain中减掉的量，应该是（剩余量，本bpm区间允许消耗量）的最小值
+                remain -= toSubtract;
+                result += toSubtract * (dstBpmNow!.Value / srcBpmNow.Value);
+                
+                bpmIndex += 1;
+                rangeStart = bpmRangeEnd;
+            }
+
+            return result.CanonicalForm;
+        }
+    }
 }
 
 public record BPM(Rational Time, decimal Bpm);
+
+/**
+ * 表示拍号的结构体。
+ * 遵循英文的表达习惯，Numerator是每小节几拍，Denominator是每几分音符为一拍。
+ * 注意MA2、C2S等格式中，MET的格式是Bar Tick Denominator Numerator，和常见顺序是反过来的。
+ */
+public record MET(Rational Time, int Numerator, int Denominator);

chart/BaseChart.cs

@@ -1,4 +1,7 @@
-namespace MuConvert.chart;
+using MuConvert.utils;
+using Rationals;
+
+namespace MuConvert.chart;
 
 public interface IBaseChart;
 
@@ -7,30 +10,102 @@ public interface IBaseChart;
  * 此类中提供了Notes列表，作为存储音符的核心列表；存储的音符类型是特定于谱面的（继承时传入泛型）
  * 此外，应当重写以下四个抽象的getter。
  */
-public abstract class BaseChart<TNote> : IBaseChart
+public abstract class BaseChart<TNote>: IBaseChart where TNote: BaseNote
 {
     /**
      * 所有音符构成的列表
      */
     public List<TNote> Notes = [];
 
+    /**
+     * 所有BPM构成的列表
+     */
+    public BPMList BpmList = [];
+    
+    /**
+     * 所有拍号声明构成的列表。
+     *
+     * 已知该内容，目前在游戏内暂无实质性的效果。maimai中无任何效果，chunnithm则会把这个作为显示小节和拍子参考线时候额依据、但也仅影响显示效果，对游戏本身无影响。
+     */
+    public List<MET> MetList = [];
+    
+    /**
+     * 根据BPMList中的声明，将小节时间转换为秒。
+     */
+    public Rational ToSecond(Rational barTime) => BpmList.ToSecond(barTime);
+    
     /**
      * 谱面开头的BPM
      */
-    public abstract decimal StartBpm { get; }
+    public virtual decimal StartBpm {
+        get
+        {
+            Utils.Assert(BpmList[0].Time == 0, "BPM列表的开头必须为0时刻");
+            return BpmList[0].Bpm;
+        }
+    }
 
     /**
-     * 获得谱面开始的时刻（即谱面中第一个音符的开始时刻）。单位为秒
+     * 获得谱面开始的时刻（即谱面中第一个音符的开始时刻）。单位为秒（注意单位与Note的Time不同！）
      */
-    public abstract decimal StartTime { get; }
+    public virtual decimal StartTime => (decimal)ToSecond(Notes.First().Time);
 
     /**
-     * 获得谱面结束的时刻（即谱面中最后一个音符的完成时刻）。单位为秒
+     * 获得谱面结束的时刻（即谱面中最后一个音符的完成时刻）。单位为秒（注意单位与Note的EndTime不同！）
+     */
+    public virtual decimal EndTime => (decimal)ToSecond(Notes.Max(x=>x.EndTime));
+    
+    /**
+     * 总音符数量（物量）。
+     *
+     * 注：具体实现很可能会需要重写此方法，因为对绝大多数的游戏，“物量”都不是简单的等于Note数量的加和的，很可能会和判定等有关
      */
-    public abstract decimal EndTime { get; }
+    public virtual int TotalNotes => Notes.Count;
+
+    // 内部使用，供子类重写，实现比只用Time更复杂的排序逻辑
+    protected virtual IEnumerable<TNote> SortNotes()
+    {
+        return Notes.OrderBy(n => n.Time); // 默认按照Time排序，子类可以重写此方法实现更复杂的排序逻辑
+    }
+    
+    public virtual void Sort()
+    {
+        // 分别把BpmList和Notes，依照Time做稳定排序。排序务必要稳定！
+        var sortedBpms = BpmList.OrderBy(b => b.Time).ToList(); // LINQ OrderBy 是稳定排序
+        BpmList.Clear();
+        BpmList.AddRange(sortedBpms);
+
+        MetList = MetList.OrderBy(x => x.Time).ToList();
+        Notes = SortNotes().ToList(); // LINQ OrderBy 是稳定排序
+    }
 
     /**
-     * 总音符数量（物量）
+     * 对整首歌曲，应用一个偏移量进行整体平移。
+     * <param name="offset">偏移量，正数表示歌曲整体向后，负数表示歌曲整体向前。</param>
+     * <param name="bpm">上述偏移量所对应的Bpm。若不传，默认使用歌曲开头的BPM（即chart.StartBpm）。</param>
      */
-    public abstract int TotalNotes { get; }
+    public virtual void Shift(Rational offset, decimal? bpm = null)
+    {
+        bpm ??= StartBpm;
+        
+        if (offset < 0)
+        { // 向前平移。此时存在的一种极端情况就是指定的区间跨过了多个BPM区间。
+            // 传入的bpm参数本质是一种写死的InvariantBar，因此要把它转为可变Bar，才是真正的要去应用的offset。
+            offset = -BpmList.ConvertTime(0, -offset, bpm, null);
+        }
+        else if (offset > 0)
+        { // 向后平移。需要把传入的offset的量换算到乐曲开头BPM下，才是真正的量。
+            offset = offset * (Rational)StartBpm / (Rational)bpm;
+        }
+
+        // 对BpmList和MetList的处理：需要确保首项为0
+        BpmList = new BPMList(BpmList.Select(x => x with { Time = x.Time + offset })
+            .Skip(BpmList.Count(x => x.Time <= 0) - 1) // 至多只保留一个非正项，其他的舍弃。直接Count-1这么写是没有问题的，因为Skip传入-1等价于传入0。
+            .Select((x, i) => i == 0 ? x with { Time = 0 } : x)); // 把第一项（唯一的可能非正项）强制设为0
+        MetList = MetList.Select(x => x with { Time = x.Time + offset }) // 同上
+            .Skip(MetList.Count(x => x.Time <= 0) - 1)
+            .Select((x, i) => i == 0 ? x with { Time = 0 } : x).ToList();
+        // Notes，直接丢弃所有负数项即可
+        Notes = Notes.Select(x => { x.Time += offset; return x; }).Where(x => x.Time >= 0).ToList();
+    }
 }

chart/BaseNote.cs

@@ -0,0 +1,18 @@
+using Rationals;
+
+namespace MuConvert.chart;
+
+public abstract class BaseNote
+{
+    /**
+     * 音符的开始时刻。以小节为单位（分数时间）
+     */
+    public virtual Rational Time { get; set => field = value.CanonicalForm; }
+
+    /**
+     * 音符的结束时刻。以小节为单位（分数时间）
+     *
+     * 默认实现中实现为等于开始时刻（瞬间音符，没有持续时间）。有持续时间的音符应当重写此属性。
+     */
+    public virtual Rational EndTime => Time;
+}

chart/mai/Duration.cs

@@ -45,7 +45,7 @@ public Rational Bar
                 case Type.Bar:
                     return _data;
                 case Type.InvariantBar:
-                    return ConvertTime(_data, (Rational)InvariantBpm, null);
+                    return ConvertTime(_data, InvariantBpm, null);
                 case Type.Seconds:
                     return ConvertTime(_data, 240, null); // seconds秒数可以等效为240bpm下的小节数
                 default:
@@ -68,9 +68,9 @@ public Rational InvariantBar
                 case Type.InvariantBar:
                     return _data;
                 case Type.Bar:
-                    return ConvertTime(_data, null, (Rational)InvariantBpm);
+                    return ConvertTime(_data, null, InvariantBpm);
                 case Type.Seconds:
-                    return ConvertTime(_data, 240, (Rational)InvariantBpm); // seconds秒数可以等效为240bpm下的小节数
+                    return ConvertTime(_data, 240, InvariantBpm); // seconds秒数可以等效为240bpm下的小节数
                 default:
                     throw new InvalidOperationException();
             }
@@ -93,7 +93,7 @@ public Rational Seconds
                 case Type.Bar:
                     return ConvertTime(_data, null, 240); // seconds秒数可以等效为240bpm下的小节数
                 case Type.InvariantBar:
-                    return ConvertTime(_data, (Rational)InvariantBpm, 240);
+                    return ConvertTime(_data, InvariantBpm, 240);
                 default:
                     throw new InvalidOperationException();
             }
@@ -105,69 +105,14 @@ public Rational Seconds
         }
     }
 
-    /**
-     * 用于在不同格式的时间数值之间转换的函数。
-     *
-     * 首先指出一个重要原理：Seconds格式下以秒为单位的时间，在数值上实际等价于 240bpm下的不变小节时间。这就是为什么可以构造一个通用的转换函数的原理。
-     *
-     * <param name="value">要被转换的时间值</param>
-     * <param name="srcBpm">指定value所对应的源bpm。若为None，表示使用BPMList中动态的bpm(对应把Bar转换为其他类型的情况)</param>
-     * <param name="dstBpm">转换的目标bpm。若为None，表示使用BPMList中动态的bpm(对应把其他类型转换为Bar的情况)</param>
-     */
-    private Rational ConvertTime(Rational value, Rational? srcBpm, Rational? dstBpm)
+    private Rational ConvertTime(Rational value, decimal? srcBpm, decimal? dstBpm)
     {
         var startTime = _note.Time;
         if (_note is Slide slide && slide.WaitTime != this)
         { // 如果我不是WaitTime，则我是Duration，则应加上等待时间
             startTime += slide.WaitTime.Bar;
         }
-        return ConvertTime(startTime, value, srcBpm, dstBpm, BpmList);
-    }
-    
-    internal static Rational ConvertTime(Rational startTime, Rational value, Rational? srcBpm, Rational? dstBpm, BPMList bpmList)
-    {
-        if (srcBpm != null && dstBpm != null)
-        {
-            // 静态的src和dst，直接算一下即可，无需遍历bpm表
-            return (value * (dstBpm.Value / srcBpm.Value)).CanonicalForm;
-        }
-        else
-        {
-            var rangeStart = startTime;
-            var bpmIndex = bpmList.FindIndex(rangeStart);
-            Rational result = 0;
-            Rational remain = value;
-            while (remain > 0)
-            {
-                // 当前所处bpm区间的结束位置。如果当前已经是最后一个区间了，则结束位置写成一个很大的数就可以了，反正本轮remain一定会被清空
-                var bpmRangeEnd = bpmIndex < bpmList.Count - 1 ? bpmList[bpmIndex + 1].Time : 9999999;
-                // 本区间可以消耗掉remain的最大数量，以src的bpm为单位。
-                Rational curRangeCapacity = bpmRangeEnd - rangeStart;
-                
-                var srcBpmNow = srcBpm; // 每次循环要复制一份srcBpm，不然直接改了srcBpm的话，再次循环时逻辑就不对了
-                var dstBpmNow = dstBpm;
-                if (srcBpmNow == null)
-                { // 如果srcBpm传入的是None，说明应该使用当前的实时bpm作为srcBpm
-                    srcBpmNow = (Rational)bpmList[bpmIndex].Bpm;
-                    // 此时capacity已经是以srcBpm为单位了，无需再转换
-                }
-                else if (dstBpmNow == null)
-                {
-                    dstBpmNow = (Rational)bpmList[bpmIndex].Bpm;
-                    // 此时capacity是基于可变bpm即dstBpm的，需要换算到srcBpm上
-                    curRangeCapacity *= (srcBpmNow.Value / dstBpmNow.Value);
-                }
-
-                Rational toSubtract = curRangeCapacity < remain ? curRangeCapacity : remain; // 要从remain中减掉的量，应该是（剩余量，本bpm区间允许消耗量）的最小值
-                remain -= toSubtract;
-                result += toSubtract * (dstBpmNow!.Value / srcBpmNow.Value);
-                
-                bpmIndex += 1;
-                rangeStart = bpmRangeEnd;
-            }
-
-            return result.CanonicalForm;
-        }
+        return BpmList.ConvertTime(startTime, value, srcBpm, dstBpm);
     }
 
     public static Duration operator +(Duration a, Duration b)