more docs

asika32764 · asika32764 · commit 655f569465b8 · 2025-06-30T22:14:32.000+08:00
diff --git a/docs/volume.md b/docs/volume.md
@@ -0,0 +1,106 @@
+# Volume Measurement
+
+Volume 是一個用於計算體積的單位轉換工具，適合用於各種體積單位之間的轉換。
+
+<!-- TOC -->
+* [Volume Measurement](#volume-measurement)
+  * [建立](#建立)
+  * [可用單位](#可用單位)
+    * [限縮單位](#限縮單位)
+  * [轉換](#轉換)
+  * [格式化](#格式化)
+<!-- TOC -->
+
+## 建立
+
+要建立一個 Volume 實例，可以使用以下方法：
+
+```php
+use Asika\UnitConverter\Volume;
+
+$volume = new Volume(100); // 100 立方公尺
+$volume = new Volume(2, Volume::UNIT_CUBIC_KILOMETERS); // 2 立方公里
+
+$volume = Volume::from(300, 'cm3');
+$volume = Volume::from('300 cm3');
+```
+
+## 可用單位
+
+- Atom Unit: `fm3`
+- Default Unit: `m3`
+- Base Unit: `m3`
+
+| 單位    | 常數                       | 別名                                            | 比率（相對 m³）           | 說明   |
+|-------|--------------------------|-----------------------------------------------|---------------------|------|
+| `fm3` | `UNIT_CUBIC_FEMTOMETERS` | `fm^3`, `fm³`, `femtometers3`, `femtometers³` | `1e-45`             | 立方飛米 |
+| `pm3` | `UNIT_CUBIC_PICOMETERS`  | `pm^3`, `pm³`, `picometers3`, `picometers³`   | `1e-36`             | 立方皮米 |
+| `nm3` | `UNIT_CUBIC_NANOMETERS`  | `nm^3`, `nm³`, `nanometers3`, `nanometers³`   | `1e-27`             | 立方奈米 |
+| `μm3` | `UNIT_CUBIC_MICROMETERS` | `μm^3`, `um³`, `micrometers3`, `micrometers³` | `1e-18`             | 立方微米 |
+| `mm3` | `UNIT_CUBIC_MILLIMETERS` | `mm^3`, `mm³`, `millimeters3`, `millimeters³` | `1e-9`              | 立方毫米 |
+| `cm3` | `UNIT_CUBIC_CENTIMETERS` | `cm^3`, `cm³`, `centimeters3`, `centimeters³` | `1e-6`              | 立方公分 |
+| `dm3` | `UNIT_CUBIC_DECIMETERS`  | `dm^3`, `dm³`, `decimeters3`, `decimeters³`   | `1e-3`              | 立方分米 |
+| `m3`  | `UNIT_CUBIC_METERS`      | `m^3`, `m³`, `meters3`, `meters³`             | `1`                 | 立方公尺 |
+| `km3` | `UNIT_CUBIC_KILOMETERS`  | `km^3`, `km³`, `kilometers3`, `kilometers³`   | `1e9`               | 立方公里 |
+| `in3` | `UNIT_CUBIC_INCHES`      | `in^3`, `in³`, `inches3`, `inches³`           | `0.000016387064`    | 立方英吋 |
+| `ft3` | `UNIT_CUBIC_FEET`        | `ft^3`, `ft³`, `feet3`, `feet³`               | `0.028316846592`    | 立方英呎 |
+| `yd3` | `UNIT_CUBIC_YARDS`       | `yd^3`, `yd³`, `yards3`, `yards³`             | `0.764554857984`    | 立方碼  |
+| `mi3` | `UNIT_CUBIC_MILES`       | `mi^3`, `mi³`, `miles3`, `miles³`             | `4168181825.440579` | 立方英里 |
+| `L`   | `UNIT_CUBIC_LITERS`      | `l`, `liters`, `liter`                        | `0.001`             | 公升   |
+| `gal` | `UNIT_CUBIC_GALLONS`     | `gal`, `gallons`, `gallon`                    | `0.003785411784`    | 加侖   |
+| `pt`  | `UNIT_CUBIC_PINTS`       | `pt`, `pints`, `pint`                         | `0.000473176473`    | 品脫   |
+| `qt`  | `UNIT_CUBIC_QUARTS`      | `qt`, `quarts`, `quart`                       | `0.000946352946`    | 夸脫   |
+
+### 限縮單位
+
+由於體積單位的多樣性，Volume 類別提供了 `withOnlyCommonVolumes()` 方法來限制可用的單位，僅保留常用的公制體積單位：
+
+```php
+$volume = $volume->withOnlyCommonVolumes();
+
+// OR
+
+$volume = $volume->withAvailableUnits(Volume::UNITS_GROUP_COMMON_VOLUMES);
+```
+
+## 轉換
+
+可使用 `to()` 或 `toXxx()` 方法將 Volume 轉換成其他單位的值：
+
+```php
+$volume->toCubicMeters();
+$volume->toCubicKilometers(scale: 4);
+$volume->to('ft3');
+```
+
+支援的函式
+
+- `toCubicFemtometers()`
+- `toCubicPicometers()`
+- `toCubicNanometers()`
+- `toCubicMicrometers()`
+- `toCubicMillimeters()`
+- `toCubicCentimeters()`
+- `toCubicDecimeters()`
+- `toCubicMeters()`
+- `toCubicKilometers()`
+- `toCubicInches()`
+- `toCubicFeet()`
+- `toCubicYards()`
+- `toCubicMiles()`
+- `toCubicLiters()`
+- `toCubicGallons()`
+- `toCubicPints()`
+- `toCubicQuarts()`
+
+## 格式化
+
+可以將體積數值格式化成人類可讀的方式：
+
+```php
+$volume = \Asika\UnitConverter\Volume::from(401074580, 'm3')
+    ->withOnlyCommonVolumes();
+echo $volume->humanize(divider: ' and '); // 401km3 and 74580m3
+```
+
+
diff --git a/docs/weight.md b/docs/weight.md
@@ -0,0 +1,116 @@
+# Weight Measurement
+
+Weight 是一個用於計算重量的單位轉換工具，適合用於各種重量單位之間的轉換。
+
+<!-- TOC -->
+* [Weight Measurement](#weight-measurement)
+  * [建立](#建立)
+  * [可用單位](#可用單位)
+    * [限縮單位](#限縮單位)
+  * [轉換](#轉換)
+  * [格式化](#格式化)
+<!-- TOC -->
+
+## 建立
+
+要建立一個 Weight 實例，可以使用以下方法：
+
+```php
+use Asika\UnitConverter\Weight;
+
+$weight = new Weight(100); // 100 公克
+$weight = new Weight(2, Weight::UNIT_KILOGRAMS); // 2 公斤
+
+$weight = Weight::from(300, 'mg');
+$weight = Weight::from('300 mg');
+```
+
+## 可用單位
+
+- Atom Unit: `fg`
+- Default Unit: `g`
+- Base Unit: `g`
+
+| 單位    | 常數                        | 別名                                        | 比率（相對 g）               | 說明       |
+|-------|---------------------------|-------------------------------------------|------------------------|----------|
+| `fg`  | `UNIT_FEMTOGRAMS`         | `femtogram`, `femtograms`                 | `1e-15`                | 飛克       |
+| `pg`  | `UNIT_PICOGRAMS`          | `picogram`, `picograms`                   | `1e-12`                | 皮克       |
+| `ng`  | `UNIT_NANOGRAMS`          | `nanogram`, `nanograms`                   | `1e-9`                 | 奈克       |
+| `μg`  | `UNIT_MICROGRAMS`         | `microgram`, `micrograms`, `mcg`          | `1e-6`                 | 微克       |
+| `mg`  | `UNIT_MILLIGRAMS`         | `milligram`, `milligrams`                 | `1e-3`                 | 毫克       |
+| `g`   | `UNIT_GRAMS`              | `gram`, `grams`                           | `1`                    | 公克       |
+| `dg`  | `UNIT_DECIGRAMS`          | `decigram`, `decigrams`                   | `0.1`                  | 分克       |
+| `cg`  | `UNIT_CENTIGRAMS`         | `centigram`, `centigrams`                 | `0.01`                 | 釐克       |
+| `kg`  | `UNIT_KILOGRAMS`          | `kilogram`, `kilograms`                   | `1000`                 | 公斤       |
+| `t`   | `UNIT_METRIC_TONS`        | `metric ton`, `metric tons`, `tonne`, `tonnes` | `1e6`             | 公噸       |
+| `oz`  | `UNIT_OUNCES`             | `ounce`, `ounces`                         | `28.349523125`         | 盎司       |
+| `lb`  | `UNIT_POUNDS`             | `pound`, `pounds`                         | `453.59237`            | 磅        |
+| `st`  | `UNIT_STONES`             | `stone`, `stones`                         | `6350.29318`           | 英石       |
+| `tn`  | `UNIT_TONS`               | `ton`, `tons`                             | `907184.74`            | 美噸       |
+| `ct`  | `UNIT_CARATS`             | `carat`, `carats`                         | `0.2`                  | 克拉       |
+| `N`   | `UNIT_NEWTONS`            | `newton`, `newtons`                       | `101.972`              | 牛頓 （可變動） |
+
+### 限縮單位
+
+由於重量單位的多樣性，Weight 類別提供了 `withOnlyCommonWeights()` 方法來限制可用的單位，僅保留常用的公制重量單位：
+
+```php
+$weight = $weight->withOnlyCommonWeights();
+
+// OR
+
+$weight = $weight->withAvailableUnits(Weight::UNITS_GROUP_COMMON_WEIGHTS);
+```
+
+## 轉換
+
+可使用 `to()` 或 `toXxx()` 方法將 Weight 轉換成其他單位的值：
+
+```php
+$weight->toGrams();
+$weight->toKilograms(scale: 4);
+$weight->to('lb');
+```
+
+支援的函式
+
+- `toFemtograms()`
+- `toPicograms()`
+- `toNanograms()`
+- `toMicrograms()`
+- `toMilligrams()`
+- `toGrams()`
+- `toDecigrams()`
+- `toCentigrams()`
+- `toKilograms()`
+- `toMetricTons()`
+- `toOunces()`
+- `toPounds()`
+- `toStones()`
+- `toTons()`
+- `toCarats()`
+- `toNewtons()`
+
+## 格式化
+
+可以將重量數值格式化成人類可讀的方式：
+
+```php
+$weight = \Asika\UnitConverter\Weight::from(12345, 'g')
+    ->withOnlyCommonWeights();
+echo $weight->humanize(divider: ' and '); // 12kg and 345g
+```
+
+## 重力加速度
+
+由於牛頓 (`N`) 的數值建立在重力加速度上，我們可以替 Weight 實例設定重力加速度的值：
+
+```php
+$weight = new \Asika\UnitConverter\Weight(100, 'N');
+
+echo $weight->format(unit: 'kg', scale: 4); // 0.0102kg
+
+$weight = $weight->withGravityAcceleration(1.62); // The gravity acceleration on the Moon
+
+echo $weight->format(unit: 'kg', scale: 4); // 0.0617kg
+```
diff --git a/src/Volume.php b/src/Volume.php
@@ -57,7 +57,7 @@ class Volume extends AbstractBasicMeasurement
         self::UNIT_CUBIC_KILOMETERS,
     ];
 
-    public string $atomUnit = self::UNIT_CUBIC_PICOMETERS;
+    public string $atomUnit = self::UNIT_CUBIC_FEMTOMETERS;
 
     public string $defaultUnit = self::UNIT_CUBIC_METERS;
 
diff --git a/src/Weight.php b/src/Weight.php
@@ -96,15 +96,17 @@ class Weight extends AbstractBasicMeasurement
         get {
             $units = $this->unitExchanges;
             $units[self::UNIT_NEWTONS] = BigDecimal::of(1)
-                ->dividedBy($this->gAcceleration, 3, RoundingMode::HALF_UP)
+                ->dividedBy($this->gravityAcceleration, 3, RoundingMode::HALF_UP)
                 ->toFloat();
 
             return $units;
         }
     }
 
     // Standard gravity in m/s²
-    public float $gAcceleration = 9.80665;
+    public protected(set) BigDecimal $gravityAcceleration {
+        get => $this->gravityAcceleration ??= BigDecimal::of(9.80665);
+    }
 
     protected function normalizeUnit(string $unit): string
     {
@@ -135,4 +137,11 @@ public function withOnlyCommonWeights(): static
     {
         return $this->withAvailableUnits(self::UNITS_GROUP_COMMON_WEIGHTS);
     }
+
+    public function withGravityAcceleration(BigDecimal|float|int|string $gAcceleration): Weight
+    {
+        $this->gravityAcceleration = BigDecimal::of($gAcceleration);
+
+        return $this;
+    }
 }
diff --git a/tests/test.php b/tests/test.php
@@ -6,6 +6,8 @@
 
 include __DIR__ . '/../vendor/autoload.php';
 
-$area = \Asika\UnitConverter\Area::from(401074580, 'm2')
-    ->withOnlyCommonAreas();
-echo $area->humanize(); // 401km2 74580m2
+$weight = new \Asika\UnitConverter\Weight(100, 'N');
+echo $weight->format(unit: 'kg', scale: 4);
+echo "\n";
+$weight = $weight->withGravityAcceleration(1.62); // The gravity acceleration on the Moon
+echo $weight->format(unit: 'kg', scale: 4);

Original file line number	Diff line number	Diff line change
`@@ -96,15 +96,17 @@ class Weight extends AbstractBasicMeasurement`
`96`	`96`	`get {`
`97`	`97`	`$units = $this->unitExchanges;`
`98`	`98`	`$units[self::UNIT_NEWTONS] = BigDecimal::of(1)`
`99`		`- ->dividedBy($this->gAcceleration, 3, RoundingMode::HALF_UP)`
	`99`	`+ ->dividedBy($this->gravityAcceleration, 3, RoundingMode::HALF_UP)`
`100`	`100`	`->toFloat();`
`101`	`101`
`102`	`102`	`return $units;`
`103`	`103`	`}`
`104`	`104`	`}`
`105`	`105`
`106`	`106`	`// Standard gravity in m/s²`
`107`		`- public float $gAcceleration = 9.80665;`
	`107`	`+ public protected(set) BigDecimal $gravityAcceleration {`
	`108`	`+ get => $this->gravityAcceleration ??= BigDecimal::of(9.80665);`
	`109`	`+ }`
`108`	`110`
`109`	`111`	`protected function normalizeUnit(string $unit): string`
`110`	`112`	`{`
`@@ -135,4 +137,11 @@ public function withOnlyCommonWeights(): static`
`135`	`137`	`{`
`136`	`138`	`return $this->withAvailableUnits(self::UNITS_GROUP_COMMON_WEIGHTS);`
`137`	`139`	`}`
	`140`	`+`
	`141`	`+ public function withGravityAcceleration(BigDecimal\|float\|int\|string $gAcceleration): Weight`
	`142`	`+ {`
	`143`	`+ $this->gravityAcceleration = BigDecimal::of($gAcceleration);`
	`144`	`+`
	`145`	`+ return $this;`
	`146`	`+ }`
`138`	`147`	`}`