1. 项目概述Fraction是一个面向 Arduino 平台的轻量级 C 库专为嵌入式系统中精确表示和运算有理数即形如 $ a/b $ 的分数而设计。其核心目标并非替代浮点运算而是解决一类典型嵌入式场景中的显示精度、用户可读性与数学语义一致性问题例如将 ADC 采样值如 0.333333以1/3形式直观呈现在旋钮调节界面中显示7/8而非0.875000或在 PID 控制器参数配置中以整数比形式固化比例系数规避浮点舍入累积误差。该库明确声明为“实验性”Experimental这一标签具有深刻的工程含义——它不追求 IEEE 754 级别的数值完备性而是在资源受限的 MCU如 ATmega328P、ESP32-S2上以确定性、低内存开销和可预测行为为首要约束构建一套足够好Good Enough的分数抽象。其设计哲学是当float f 0.1; Serial.print(f);输出0.10实际存储为0.10000000149011612引发用户困惑时Fraction fr(0.1); Serial.print(fr.toString());输出(1/10)才是真正符合人类直觉的表达。1.1 核心设计约束与权衡所有嵌入式库的设计都源于对硬件边界的敬畏。Fraction的关键约束直接映射到其 API 行为与适用边界约束项具体规格工程影响典型规避策略分子Numerator范围int32_t-2,147,483,648 ~ 2,147,483,647支持大整数比如2147483647/1但无法表示超大分母下的微小增量使用setDenominator()将分母固定为 1000将0.00123映射为(1/1000)而非(123/100000)分母Denominator上限1至99994 位十进制乘除法算法可避免 64 位中间计算显著节省 RAM 与 Flash但π ≈ 355/113在 v0.2.0 中失效v0.3.0 引入连分数算法后355/113可被精确重构证明约束可通过算法优化部分突破浮点转换精度非一一映射存在绝对误差fractionize(0.333333)可能返回(1/3)或(3333/10000)取决于算法对关键常量如π,e提供预定义宏FRAC_PI 355/113绕过运行时转换这些约束不是缺陷而是工程师在sizeof(Fraction) 8 bytes仅含int32_t nom, den与fractionize()运行时开销之间做出的主动选择。理解此权衡是安全使用该库的前提。2. 核心功能与 API 详解2.1 构造函数从多种源头创建 FractionFraction提供了覆盖常见数据源的构造函数全部标记为explicit以防止隐式类型转换引发的意外行为如if (fr 0.5)编译失败强制开发者显式调用Fraction(0.5)。这种设计在嵌入式系统中至关重要——隐式转换可能在条件判断中引入难以调试的精度陷阱。#include fraction.h // 1. 默认构造零值 (0/1) Fraction zero; // 等价于 Fraction(0, 1) // 2. 整数比构造最精确的初始化方式 Fraction half(1, 2); // (1/2) Fraction third(1, 3); // (1/3) Fraction neg_quarter(-1, 4); // (-1/4) // 3. 浮点数构造触发 fractionize() 算法 Fraction from_float Fraction(0.333333F); // 可能为 (1/3) 或 (3333/10000) Fraction from_double Fraction(3.1415926535); // v0.3.0 下高概率为 (355/113) // 4. 整数构造自动设分母为 1 Fraction int_to_frac Fraction(42); // (42/1) Fraction uint8_val Fraction((uint8_t)255); // (255/1) // 5. 拷贝构造深拷贝无共享状态 Fraction copy Fraction(half);关键工程细节Fraction(int32_t p)等整数构造函数内部执行p/1无任何精度损失浮点构造函数是唯一可能引入不确定性的入口其行为完全由fractionize()算法版本决定v0.1.x 简单枚举 vs v0.3.0 连分数所有构造函数均保证分母为正数Fraction(-1, -2)自动归一化为(1/2)Fraction(1, -2)归一化为(-1/2)这是数学规范性的底层保障。2.2 数学运算符符合直觉的重载实现Fraction重载了全部基础算术运算符,-,*,/,,-,*,/及一元负号-。其实现严格遵循有理数代数规则且全程在int32_t范围内完成避免浮点介入$$ \frac{a}{b} \frac{c}{d} \frac{ad bc}{bd}, \quad \frac{a}{b} \times \frac{c}{d} \frac{ac}{bd} $$Fraction a(1, 2); // 1/2 Fraction b(1, 3); // 1/3 Fraction sum a b; // (1*3 2*1)/(2*3) 5/6 Fraction product a * b; // (1*1)/(2*3) 1/6 Fraction neg_a -a; // (-1)/2 // 复合赋值原地修改减少临时对象 Fraction c(2, 5); c a; // c c a (2/5) (1/2) 9/10底层实现逻辑以operator为例计算新分母new_den den * f.den计算新分子new_nom nom * f.den den * f.nom调用reduce()函数见 2.4 节对(new_nom, new_den)进行约分返回新Fraction(new_nom, new_den)。此过程确保无溢出保护若nom * f.den超出int32_t范围结果未定义符合嵌入式“快速失败”原则自动约分6/8永远不会作为中间态存在reduce()在每一步运算后立即生效。2.3 比较运算符自然序的脆弱性与应对Fraction实现了全部六种比较运算符,!,,,,。其比较逻辑基于交叉相乘$$ \frac{a}{b} \frac{c}{d} \iff a \cdot d c \cdot b \quad (\text{当 } b0, d0) $$Fraction x(1, 3); // ~0.333333 Fraction y(3333, 10000); // 0.3333 Serial.println(x y); // true: 1*1000010000 3333*39999? 错实际 10000 9999 → false此处揭示了文档中“自然序断裂”的本质浮点数0.333333与0.3333在 IEEE 754 中是两个不同比特模式fractionize(0.333333)可能返回(1/3)而fractionize(0.3333)返回(3333/10000)但(1/3) (3333/10000)等价于1*10000 3333*3→10000 9999结果为false与原始浮点比较0.333333 0.3333false一致真正的风险在于fractionize()算法的非单调性若f g但fractionize(f)产生的分母远小于fractionize(g)交叉相乘可能因整数截断产生错误序。工程实践建议在需要严格保序的场景如二分查找优先使用mediant()或middle()见 2.6 节对用户输入的浮点值先用setDenominator(f, 1000)统一分母再比较nom值获得确定性序。2.4 约分与规范化reduce()的核心作用Fraction的所有运算最终都依赖reduce()函数进行约分其核心是计算分子分母的最大公约数GCD。库采用欧几里得算法的迭代实现兼顾效率与代码尺寸// 简化版 reduce() 逻辑实际代码更健壮 int32_t gcd(int32_t a, int32_t b) { a abs(a); b abs(b); while (b ! 0) { int32_t temp b; b a % b; a temp; } return a; } void Fraction::reduce() { int32_t g gcd(nom, den); nom / g; den / g; if (den 0) { // 保证分母恒为正 nom -nom; den -den; } }关键特性gcd()对负数取绝对值确保Fraction(-4, -6)归一化为(2/3)reduce()在每次构造、运算后自动调用用户无需手动管理GCD 计算本身不涉及浮点100% 确定性。2.5 类型转换与字符串化面向人机交互的接口嵌入式系统中数据最终需呈现给用户或与其他模块交换。Fraction提供了三类关键转换接口接口原型用途注意事项数值转换int32_t toInt32()float toFloat()double toDouble()获取整数部分或等效浮点值toInt32()向零截断-7/4 → -1非四舍五入toFloat()可能损失精度角度转换float toAngle()将分数视为弧度值返回atan2(nom, den)的度数-180°~180°适用于旋钮位置映射、电机角度控制等场景字符串化String toString()生成(n/d)格式字符串v0.2.0 移除Printable接口后必须显式调用Serial.print(fr.toString())Fraction sensor_ratio(123, 456); Serial.print(Raw: ); Serial.println(sensor_ratio.toString()); // (123/456) Serial.print(As float: ); Serial.println(sensor_ratio.toFloat(), 6); // 0.269737 Serial.print(Integer part: ); Serial.println(sensor_ratio.toInt32()); // 0 Serial.print(Angle: ); Serial.println(sensor_ratio.toAngle()); // atan2(123,456) ≈ 15.0°工程优化点toString()内部使用String类对 RAM 敏感项目如 ATmega328P应避免在中断中调用若仅需打印分子直接Serial.print(fr.nominator())比toString()节省数百字节 Flash。2.6 特殊工具函数面向算法的实用接口Fraction提供了两个为特定算法场景设计的静态函数体现了其超越简单计算器的工程价值mediant(const Fraction a, const Fraction b)计算中项Mediant定义为 $\frac{a_{nom} b_{nom}}{a_{den} b_{den}}$。其数学性质是若 $a b$则必有 $a \text{mediant}(a,b) b$且分母最小。这使其成为分数二分搜索的理想选择比middle()更快且保证序。middle(const Fraction a, const Fraction b)计算数学中点即 $(ab)/2$。结果更“居中”但分母可能更大。// 二分查找 [1/2, 3/4] 区间内最接近 0.618 的分数 Fraction low(1, 2); // 0.5 Fraction high(3, 4); // 0.75 Fraction guess Fraction::mediant(low, high); // (13)/(24) 4/6 2/3 ≈ 0.666 // 若 guess target则 high guess否则 low guess // 下一轮 mediant(low, guess) (12)/(23) 3/5 0.6此外setDenominator(const Fraction f, uint16_t new_den)允许将任意分数强制映射到指定分母如1000用于标准化显示或 DAC 控制Fraction adc_val Fraction(0.618F); Fraction scaled Fraction::setDenominator(adc_val, 1000); // (618/1000) Serial.print(scaled.toString()); // (618/1000) —— 直观显示 61.8%3. 关键算法深度解析fractionize()的演进fractionize()是Fraction库的“心脏”其质量直接决定整个库的实用性。文档明确指出其是“一个漂亮的编程问题”我们来剖析其两个主要版本。3.1 v0.1.x 简单枚举算法Minimalistic该算法采用暴力枚举思想对分母d从1到MAX_DENOM9999遍历对每个d计算最接近的分子n round(f * d)然后评估误差|f - n/d|保留误差最小的(n,d)对。// 伪代码简化版 Fraction fractionize_simple(float f) { int32_t best_n 0, best_d 1; float min_error fabs(f); for (int32_t d 1; d MAX_DENOM; d) { int32_t n (int32_t)roundf(f * d); // 四舍五入 float error fabs(f - (float)n / (float)d); if (error min_error) { min_error error; best_n n; best_d d; } } return Fraction(best_n, best_d); }优点逻辑简单易于验证严格保序因d单调递增n也近似单调。缺点时间复杂度 $O(D)$D9999在 16MHz AVR 上耗时约 10ms精度受限于枚举范围π的最佳近似仅为3126/995误差 0.00002。3.2 v0.3.0 连分数算法Simple Continued Fraction该算法由 Edgar Bonet 贡献基于数学中连分数理论。任何实数 $x$ 可表示为 $$ x a_0 \cfrac{1}{a_1 \cfrac{1}{a_2 \cfrac{1}{a_3 \cdots}}} $$ 其收敛子Convergents$\frac{p_k}{q_k}$ 是 $x$ 的最佳有理逼近。算法通过迭代提取 $a_i$ 并更新收敛子直到分母超限或精度满足要求。// 核心迭代步骤概念性 Fraction fractionize_cf(double x) { double r x; int32_t p0 0, p1 1; // p_{-1}0, p_01 int32_t q0 1, q1 0; // q_{-1}1, q_00 while (true) { int32_t a (int32_t)floor(r); // 更新收敛子: p_k a*p_{k-1} p_{k-2} int32_t p2 a * p1 p0; int32_t q2 a * q1 q0; if (q2 MAX_DENOM) break; // 分母超限返回上一个 // 更新下一轮 p0 p1; p1 p2; q0 q1; q1 q2; r 1.0 / (r - a); } return Fraction(p1, q1); }优势时间复杂度 $O(\log D)$速度提升百倍精度最优fractionize_cf(3.1415926535)精确返回(355/113)误差仅 $2.67 \times 10^{-7}$天然支持任意精度逼近只要分母允许。工程启示此演进证明在嵌入式领域算法优化往往比硬件升级更能突破性能瓶颈。一个数学洞察连分数即可将毫秒级操作压缩至微秒级。4. 实际应用案例与工程实践4.1 案例一传感器校准值的用户友好显示假设某温湿度传感器输出0.666666直接打印为0.666666对用户无意义。使用Fraction可将其映射为2/3暗示“三分之二满量程”。// 在 loop() 中 float raw_humidity readHumiditySensor(); // e.g., 0.666666 Fraction hum_frac Fraction(raw_humidity); Serial.print(Humidity: ); Serial.print(hum_frac.toString()); // (2/3) Serial.print( (); Serial.print(hum_frac.toFloat() * 100, 1); // 66.7 Serial.println(%));增强实践结合isProper()判断是否为真分数绝对值 1对超出量程的异常值如1.5特殊标记if (!hum_frac.isProper()) { Serial.print([OVER] ); }4.2 案例二步进电机微步控制的精确比例设定步进电机驱动器常需设置微步细分如 1/16, 1/32。用户通过旋钮输入0.0625系统需将其识别为1/16并配置寄存器。// 旋钮 ADC 值映射到 0.0~1.0 float knob_pos map(analogRead(A0), 0, 1023, 0, 10000) / 10000.0F; Fraction step_frac Fraction::setDenominator(Fraction(knob_pos), 1000); // 固定分母 1000 int32_t target_steps step_frac.nominator(); // 0~1000 // 查表匹配标准微步1000-1/1, 500-1/2, 250-1/4, 125-1/8, 62-1/16... uint8_t microstep_setting getMicrostepFromNumerator(target_steps);4.3 案例三PID 参数的符号化存储将 PID 的Kp参数以分数形式存储避免浮点 EEPROM 写入的精度漂移// 定义常用 Kp 值为分数常量 #define KP_SLOW Fraction(1, 10) // 0.1 #define KP_MEDIUM Fraction(1, 2) // 0.5 #define KP_FAST Fraction(3, 2) // 1.5 // 从 EEPROM 读取时直接恢复为 Fraction uint16_t eeprom_kp_nom, eeprom_kp_den; EEPROM.get(KP_ADDR, eeprom_kp_nom); EEPROM.get(KP_ADDR2, eeprom_kp_den); Fraction kp_from_eeprom(eeprom_kp_nom, eeprom_kp_den); // 写入时先约分再存储 kp_from_eeprom.reduce(); EEPROM.put(KP_ADDR, kp_from_eeprom.nominator()); EEPROM.put(KP_ADDR2, kp_from_eeprom.denominator());5. 使用注意事项与故障排查5.1 内存与性能关键点对象大小sizeof(Fraction) 8 bytes两个int32_t数组分配高效栈使用fractionize()在 v0.3.0 中使用少量栈空间约 20 字节无动态内存分配Flash 开销完整库约 1.2KB对 32KB Flash 的 MCU 可接受。5.2 常见陷阱与解决方案问题现象根本原因解决方案Fraction(0.1) Fraction(1,10)返回false0.1的二进制浮点表示不精确fractionize()未找到(1/10)使用整数构造Fraction(1,10)或setDenominator(Fraction(0.1), 10)Serial.print(fr)编译失败v0.2.0 移除了Printable接口改为Serial.print(fr.toString())fractionize(1e-6)返回(0/1)极小值下n round(f*d)恒为 0对极小值单独处理if (fabs(f) 1e-5) return Fraction(1, 1000000);除零风险文档提及INF/NAN未定义在构造前检查den ! 0或封装安全工厂函数5.3 未来扩展方向基于文档规划错误反馈fractionize()返回struct { Fraction fr; float error; }使调用者可评估精度大数支持实验性扩展分母至32767需验证int32_t乘法溢出边界常量库内置FRAC_PI,FRAC_E,FRAC_GOLDEN_RATIO消除运行时转换开销单位支持Fraction与printHelpers库集成支持toString(°C)等带单位格式化。在一块 ATmega328P 的 PCB 上当Fraction将第 1000 个传感器读数以(3/4)形式稳定显示在 OLED 屏幕上而同事的浮点方案仍在为0.749999和0.750001的显示抖动调试时——你已体会到所谓“实验性”不过是把数学的严谨亲手焊进了每一行嵌入式代码里。