Skip to content

Commit 8918cdf

Browse files
asika32764asika32764
committed
more docs
1 parent f2745da commit 8918cdf

File tree

4 files changed

+191
-167
lines changed

4 files changed

+191
-167
lines changed

‎README.md‎

Lines changed: 49 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -4,37 +4,39 @@ BetterUnits is a modern and intuitive unit conversion tool that allows you to co
44
units of measurement. It supports a wide range of categories including length, weight, temperature, volume, and more.
55

66
<!-- TOC -->
7+
78
* [BetterUnits - PHP Measurement Converter](#betterunits---php-measurement-converter)
8-
* [Installation](#installation)
9-
* [Getting Started](#getting-started)
10-
* [How to Use This Package](#how-to-use-this-package)
11-
* [How to Create Measurement Object](#how-to-create-measurement-object)
12-
* [Rounding Mode [!important]](#rounding-mode-important)
13-
* [Create By Strings](#create-by-strings)
14-
* [Unit Conversion](#unit-conversion)
15-
* [Output Values](#output-values)
16-
* [convertTo() Method](#convertto-method)
17-
* [Precision Control](#precision-control)
18-
* [Units](#units)
19-
* [Formatting](#formatting)
20-
* [`format()`](#format)
21-
* [`humanize()`](#humanize)
22-
* [Default Formatting Handler](#default-formatting-handler)
23-
* [`serialize()`](#serialize)
24-
* [`serializeCallback()`](#serializecallback)
25-
* [Unit Management](#unit-management)
26-
* [Restrict Available Units](#restrict-available-units)
27-
* [Customizing or Adding Units](#customizing-or-adding-units)
28-
* [Changing Conversion Rates](#changing-conversion-rates)
29-
* [Other Unit Adjustments](#other-unit-adjustments)
30-
* [Get the Unit Closest to 1](#get-the-unit-closest-to-1)
31-
* [Modifying the Content of a Measurement](#modifying-the-content-of-a-measurement)
32-
* [Operations](#operations)
33-
* [Compound Measurement](#compound-measurement)
34-
* [Predefined Units](#predefined-units)
35-
* [Creating Your Own Measurement](#creating-your-own-measurement)
36-
* [Dynamic Measurement](#dynamic-measurement)
37-
* [Available Units And Documentations](#available-units-and-documentations)
9+
* [Installation](#installation)
10+
* [Getting Started](#getting-started)
11+
* [How to Use This Package](#how-to-use-this-package)
12+
* [How to Create Measurement Object](#how-to-create-measurement-object)
13+
* [Rounding Mode [!important]](#rounding-mode-important)
14+
* [Create By Strings](#create-by-strings)
15+
* [Unit Conversion](#unit-conversion)
16+
* [Output Values](#output-values)
17+
* [convertTo() Method](#convertto-method)
18+
* [Precision Control](#precision-control)
19+
* [Units](#units)
20+
* [Formatting](#formatting)
21+
* [`format()`](#format)
22+
* [`humanize()`](#humanize)
23+
* [Default Formatting Handler](#default-formatting-handler)
24+
* [`serialize()`](#serialize)
25+
* [`serializeCallback()`](#serializecallback)
26+
* [Unit Management](#unit-management)
27+
* [Restrict Available Units](#restrict-available-units)
28+
* [Customizing or Adding Units](#customizing-or-adding-units)
29+
* [Changing Conversion Rates](#changing-conversion-rates)
30+
* [Other Unit Adjustments](#other-unit-adjustments)
31+
* [Get the Unit Closest to 1](#get-the-unit-closest-to-1)
32+
* [Modifying the Content of a Measurement](#modifying-the-content-of-a-measurement)
33+
* [Operations](#operations)
34+
* [Compound Measurement](#compound-measurement)
35+
* [Predefined Units](#predefined-units)
36+
* [Creating Your Own Measurement](#creating-your-own-measurement)
37+
* [Dynamic Measurement](#dynamic-measurement)
38+
* [Available Units And Documentations](#available-units-and-documentations)
39+
3840
<!-- TOC -->
3941

4042
## Installation
@@ -878,7 +880,9 @@ $new = $measurement->plus(new Duration(2, 'minutes'), scale: 2, RoundingMode::HA
878880
$new = $measurement->minus(new Duration(2500, 'ms'), scale: 2, RoundingMode::HALF_UP); // Returns a new Duration with 117.5 seconds
879881
```
880882

881-
If you need to perform more complex calculations, you can directly access the `value` property, which is a `BigDecimal` object. You can use `BigDecimal` methods for calculations and then create a new Measurement object using the `with()` or `withValue()` methods. These methods also accept a `Closure` as a parameter, allowing for more flexible calculations.
883+
If you need to perform more complex calculations, you can directly access the `value` property, which is a `BigDecimal`
884+
object. You can use `BigDecimal` methods for calculations and then create a new Measurement object using the `with()` or
885+
`withValue()` methods. These methods also accept a `Closure` as a parameter, allowing for more flexible calculations.
882886

883887
```php
884888
// Returns a new Measurement with value / 2
@@ -894,9 +898,12 @@ $measurement = $measurement->with(
894898

895899
## Compound Measurement
896900

897-
Some Measurements require combining multiple units, referred to as `num` (numerator) and `deno` (denominator), representing the units in the numerator and denominator.
901+
Some Measurements require combining multiple units, referred to as `num` (numerator) and `deno` (denominator),
902+
representing the units in the numerator and denominator.
898903

899-
For example, Speed requires both distance and time, making it a Compound Measurement composed of `Length` (numerator) and `Duration` (denominator). When expressing the unit of Speed, it will be the unit of `Length` divided by the unit of `Duration`, such as `m/s` or `km/h`.
904+
For example, Speed requires both distance and time, making it a Compound Measurement composed of `Length` (numerator)
905+
and `Duration` (denominator). When expressing the unit of Speed, it will be the unit of `Length` divided by the unit of
906+
`Duration`, such as `m/s` or `km/h`.
900907

901908
```php
902909
$speed = Speed::from('100 km/h'); // 100 kilometers per hour
@@ -912,7 +919,8 @@ Each Compound Measurement has some predefined units, which are commonly used int
912919
- `mps` (m/s, meters per second)
913920
- `knots` (knots, nautical miles per hour)
914921

915-
These units can be directly used in the `from()` or `convertTo()` methods, making it convenient to create or convert Compound Measurements.
922+
These units can be directly used in the `from()` or `convertTo()` methods, making it convenient to create or convert
923+
Compound Measurements.
916924

917925
```php
918926
$speed = Speed::from('100 kph'); // 100 kilometers per hour
@@ -925,11 +933,12 @@ Here is a simple example. To create a custom Measurement, you need to extend the
925933
There are three required properties to implement:
926934
`$atomUnit` represents the smallest indivisible unit,
927935
`$defaultUnit` is the default unit,
928-
and `$unitExchanges` defines the conversion rates between units.
936+
and `$unitExchanges` defines the conversion rates between units.
929937

930938
Make sure to include at least one base unit with a rate of `1`, as some calculations may fail without it.
931939

932-
The `normalizeUnit()` method is optional. It is used to convert input unit strings into supported units and is called during string parsing or unit conversion.
940+
The `normalizeUnit()` method is optional. It is used to convert input unit strings into supported units and is called
941+
during string parsing or unit conversion.
933942

934943
```php
935944
class ScreenMeasurement extends AbstractBasicMeasurement
@@ -965,9 +974,11 @@ class ScreenMeasurement extends AbstractBasicMeasurement
965974

966975
### Dynamic Measurement
967976

968-
You can use `DynamicMeasurement` to create a dynamic Measurement that allows you to set units and exchange rates at runtime.
977+
You can use `DynamicMeasurement` to create a dynamic Measurement that allows you to set units and exchange rates at
978+
runtime.
969979

970-
Below is an example of a dynamic currency conversion Measurement. This is useful for e-commerce systems where exchange rates and currencies can be configured dynamically.
980+
Below is an example of a dynamic currency conversion Measurement. This is useful for e-commerce systems where exchange
981+
rates and currencies can be configured dynamically.
971982

972983
```php
973984
use Asika\BetterUnits\DynamicMeasurement;

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "asika/unit-converter",
2+
"name": "asika/better-units",
33
"description": "A modern PHP unit converter.",
44
"type": "library",
55
"require": {

‎docs/area.md‎

Lines changed: 37 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,57 @@
11
# Area Measurement
22

3-
Area 是一個用於計算面積的單位轉換工具，適合用於各種面積單位之間的轉換。
3+
Area is a unit conversion tool for calculating areas, suitable for various area unit conversions.
44

55
<!-- TOC -->
66
* [Area Measurement](#area-measurement)
7-
* [建立](#建立)
8-
* [可用單位](#可用單位)
9-
* [限縮單位](#限縮單位)
10-
* [轉換](#轉換)
11-
* [格式化](#格式化)
7+
* [Creation](#creation)
8+
* [Available Units](#available-units)
9+
* [Restrict Units](#restrict-units)
10+
* [Conversion](#conversion)
11+
* [Formatting](#formatting)
1212
<!-- TOC -->
1313

14-
## 建立
14+
## Creation
1515

16-
要建立一個 Area 實例，可以使用以下方法：
16+
To create an Area instance, you can use the following methods:
1717

1818
```php
1919
use Asika\BetterUnits\Area;
2020

21-
$area = new Area(100); // 100 平方公尺
22-
$area = new Area(2, Area::UNIT_SQUARE_KILOMETERS); // 2 平方公里
21+
$area = new Area(100); // 100 square meters
22+
$area = new Area(2, Area::UNIT_SQUARE_KILOMETERS); // 2 square kilometers
2323

2424
$area = Area::from(300, 'cm2');
2525
$area = Area::from('300 cm2');
2626
```
2727

28-
## 可用單位
28+
## Available Units
2929

3030
- Atom Unit: `fm2`
3131
- Default Unit: `m2`
3232
- Base Unit: `m2`
3333

34-
| 單位 | 常數 | 別名 | 比率（相對 m²） | 說明 |
35-
|-------|---------------------------|-----------------------------------------------|------------------|------|
36-
| `fm2` | `UNIT_SQUARE_FEMTOMETERS` | `fm^2`, `fm²`, `femtometers2`, `femtometers²` | `1e-30` | 平方飛米 |
37-
| `pm2` | `UNIT_SQUARE_PICOMETERS` | `pm^2`, `pm²`, `picometers2`, `picometers²` | `1e-24` | 平方皮米 |
38-
| `nm2` | `UNIT_SQUARE_NANOMETERS` | `nm^2`, `nm²`, `nanometers2`, `nanometers²` | `1e-18` | 平方奈米 |
39-
| `μm2` | `UNIT_SQUARE_MICROMETERS` | `μm^2`, `um²`, `micrometers2`, `micrometers²` | `1e-12` | 平方微米 |
40-
| `mm2` | `UNIT_SQUARE_MILLIMETERS` | `mm^2`, `mm²`, `millimeters2`, `millimeters²` | `1e-6` | 平方毫米 |
41-
| `cm2` | `UNIT_SQUARE_CENTIMETERS` | `cm^2`, `cm²`, `centimeters2`, `centimeters²` | `1e-4` | 平方公分 |
42-
| `dm2` | `UNIT_SQUARE_DECIMETERS` | `dm^2`, `dm²`, `decimeters2`, `decimeters²` | `0.01` | 平方分米 |
43-
| `m2` | `UNIT_SQUARE_METERS` | `m^2`, `m²`, `meters2`, `meters²` | `1` | 平方公尺 |
44-
| `km2` | `UNIT_SQUARE_KILOMETERS` | `km^2`, `km²`, `kilometers2`, `kilometers²` | `1e6` | 平方公里 |
45-
| `in2` | `UNIT_SQUARE_INCHES` | `in^2`, `in²`, `inches2`, `inches²` | `0.00064516` | 平方英吋 |
46-
| `ft2` | `UNIT_SQUARE_FEET` | `ft^2`, `ft²`, `feet2`, `feet²` | `0.09290304` | 平方英呎 |
47-
| `yd2` | `UNIT_SQUARE_YARDS` | `yd^2`, `yd²`, `yards2`, `yards²` | `0.83612736` | 平方碼 |
48-
| `mi2` | `UNIT_SQUARE_MILES` | `mi^2`, `mi²`, `miles2`, `miles²` | `2589988.110336` | 平方英里 |
49-
| `ac` | `UNIT_SQUARE_ACRES` | `ac`, `acre`, `acres` | `4046.8564224` | 英畝 |
50-
| `ha` | `UNIT_SQUARE_HECTARES` | `ha`, `hectare`, `hectares` | `10000` | 公頃 |
51-
52-
### 限縮單位
53-
54-
由於面積單位的多樣性，Area 類別提供了 `withOnlyCommonAreas()` 方法來限制可用的單位，僅保留常用的公制面積單位：
34+
| Code | Constant | Aliases | Factor | Chinese Name |
35+
|-------|---------------------------|-----------------------------------------------|------------------|-------------------|
36+
| `fm2` | `UNIT_SQUARE_FEMTOMETERS` | `fm^2`, `fm²`, `femtometers2`, `femtometers²` | `1e-30` | Square Femtometer |
37+
| `pm2` | `UNIT_SQUARE_PICOMETERS` | `pm^2`, `pm²`, `picometers2`, `picometers²` | `1e-24` | Square Picometer |
38+
| `nm2` | `UNIT_SQUARE_NANOMETERS` | `nm^2`, `nm²`, `nanometers2`, `nanometers²` | `1e-18` | Square Nanometer |
39+
| `μm2` | `UNIT_SQUARE_MICROMETERS` | `μm^2`, `um²`, `micrometers2`, `micrometers²` | `1e-12` | Square Micrometer |
40+
| `mm2` | `UNIT_SQUARE_MILLIMETERS` | `mm^2`, `mm²`, `millimeters2`, `millimeters²` | `1e-6` | Square Millimeter |
41+
| `cm2` | `UNIT_SQUARE_CENTIMETERS` | `cm^2`, `cm²`, `centimeters2`, `centimeters²` | `1e-4` | Square Centimeter |
42+
| `dm2` | `UNIT_SQUARE_DECIMETERS` | `dm^2`, `dm²`, `decimeters2`, `decimeters²` | `0.01` | Square Decimeter |
43+
| `m2` | `UNIT_SQUARE_METERS` | `m^2`, `m²`, `meters2`, `meters²` | `1` | Square Meter |
44+
| `km2` | `UNIT_SQUARE_KILOMETERS` | `km^2`, `km²`, `kilometers2`, `kilometers²` | `1e6` | Square Kilometer |
45+
| `in2` | `UNIT_SQUARE_INCHES` | `in^2`, `in²`, `inches2`, `inches²` | `0.00064516` | Square Inch |
46+
| `ft2` | `UNIT_SQUARE_FEET` | `ft^2`, `ft²`, `feet2`, `feet²` | `0.09290304` | Square Foot |
47+
| `yd2` | `UNIT_SQUARE_YARDS` | `yd^2`, `yd²`, `yards2`, `yards²` | `0.83612736` | Square Yard |
48+
| `mi2` | `UNIT_SQUARE_MILES` | `mi^2`, `mi²`, `miles2`, `miles²` | `2589988.110336` | Square Mile |
49+
| `ac` | `UNIT_SQUARE_ACRES` | `ac`, `acre`, `acres` | `4046.8564224` | Acre |
50+
| `ha` | `UNIT_SQUARE_HECTARES` | `ha`, `hectare`, `hectares` | `10000` | Hectare |
51+
52+
### Restrict Units
53+
54+
Because there are many area units, the Area class provides the `withOnlyCommonAreas()` method to limit available units, keeping only the most common metric area units:
5555

5656
```php
5757
$area = $ares->withOnlyCommonAreas();
@@ -61,17 +61,17 @@ $area = $ares->withOnlyCommonAreas();
6161
$area = $area->withAvailableUnits(Area::UNITS_GROUP_COMMON_AREAS);
6262
```
6363

64-
## 轉換
64+
## Conversion
6565

66-
可使用 `to()` 或 `toXxx()` 方法將 Area 轉換成其他單位的值：
66+
You can use the `to()` or `toXxx()` methods to convert Area to other unit values:
6767

6868
```php
6969
$area->toSquareMeters();
7070
$area->toSquareKilometers(scale: 4);
7171
$area->to('ft2');
7272
```
7373

74-
支援的函式
74+
Supported functions
7575

7676
- `toSquareFemtometers()`
7777
- `toSquarePicometers()`
@@ -89,15 +89,12 @@ $area->to('ft2');
8989
- `toSquareAcres()`
9090
- `toSquareHectares()`
9191

92-
## 格式化
92+
## Formatting
9393

94-
可以將面積數值格式化成人類可讀的方式：
94+
Area values can be formatted in a human-readable way:
9595

9696
```php
9797
$area = \Asika\BetterUnits\Area::from(401074580, 'm2')
9898
->withOnlyCommonAreas();
9999
echo $area->humanize(divider: ' and '); // 401km2 and 74580m2
100100
```
101-
102-
103-

0 commit comments

Comments
 (0)