README

关于

这是一个用于表示和转换度量单位维度的PHP库。它受到Apple Foundation Framework中测量API的启发。

安装

可以通过Composer安装此包。

composer require nmarfurt/measurements

库类

单位

Unit是单位的抽象超类。每个Unit子类的实例都包含一个符号，可以用于创建Measurement对象的字符串表示。

维度

Dimension是Unit的抽象子类，表示单位家族或度量单位，可以转换为同一类型的不同单位。每个Dimension子类的实例都有一个转换器，用于使用baseUnit()方法提供的维度的基本单位来表示单位。

库为许多最常见类型的物理单位提供了具体的子类（见下文列表）。如果您需要表示自定义或派生单位的自定义单位类型，您可以子类化Dimension。如果您需要表示无量纲单位，可以直接子类化Unit。

单位转换器

UnitConverter描述了如何将单位转换为其维度的基单位，以及从基单位转换回单位。UnitConverterLinear是用于在单位之间使用线性方程进行转换的UnitConverter子类。如果需要，您可以定义自己的转换器。

测量

Measurement对象代表一个测量量，使用度量单位和值。Measurement类提供了一个程序接口，用于将测量转换为不同的单位，以及计算两个测量之间的和或差。

Measurement对象使用Unit对象和双值初始化。它们是不可变的，创建后不能更改。

库为与提供的单位相对应的测量提供了特定的子类（称为量）。

提供的单位和量

库为许多最常见类型的物理单位提供了具体的子类

使用方法

使用测量

您可以如下定义测量

use Measurements\Measurement;
use Measurements\Units\UnitLength;
use Measurements\Units\UnitDuration;

$length = new Measurement(4.48, UnitLength::meters());
echo $length; // = 4.48 m

$duration = new Measurement(1.5, UnitDuration::hours());
echo $duration; // = 1.5 hr

您可能希望通过使用提供的测量子类（即量）来强制执行测量的单位类型

use Measurements\Units\UnitLength;
use Measurements\Units\UnitDuration;
use Measurements\Quantities\Length;
use Measurements\Quantities\Duration;

$length = new Length(4.48, UnitLength::meters());
echo $length; // = 4.48 m

$duration = new Duration(1.5, UnitDuration::hours());
echo $duration; // = 1.5 hr

$invalid = new Length(4.48, UnitDuration::hours()); // Will throw a UnitException exception

量对象还提供了创建测量的表达性语法的好处。它们使用__callStatic()魔法方法通过解析派生维度来创建新实例。

use Measurements\Quantities\Length;
use Measurements\Quantities\Duration;

$length = Length::meters(4.48);
echo $length; // = 4.48 m

$duration = Duration::hours(1.5);
echo $duration; // = 1.5 hr

$invalid = Length::hours(4.48); // Will throw a BadMethodCallException exception

一些Measurement子类公开了方便的方法，可以轻松地从其他测量创建实例。

use Measurements\Quantities\Length;
use Measurements\Quantities\Duration;

$distance = Length::kilometers(18);
$time = Duration::hours(1);

$speed = Speed::fromLengthAndDuration($distance, $time);
echo $speed->toString(); // 5 m/s

转换测量

同一维度的Measurement对象可以从一个度量单位转换为另一个。

use Measurements\Measurement;
use Measurements\Units\UnitLength;

$meters = new Measurement(4.48, UnitLength::meters());

$centimeters = $meters->convertTo(UnitLength::centimeters());
echo $centimeters; // = 448 cm

作为量对象创建的测量也提供了转换它们的简短语法。它们使用__call()魔法方法来解析派生维度。

use Measurements\Quantities\Length;

$meters = Length::meters(4.48);

$centimeters = $meters->toCentimeters();
echo $centimeters; // = 448 cm

执行算术运算

Measurement对象支持不同的操作，包括add（+）、subtract（-）、multiply（*）和divide（/）。由于Measurement对象是不可变的，因此返回新的实例。

use Measurements\Measurement;
use Measurements\Units\UnitLength;

$first = new Measurement(4.48, UnitLength::meters());
$second = new Measurement(2.02, UnitLength::meters());

echo $first->add($second); // = 6.5 m

echo $first->subtract($second); // = 2.46 m

echo $first->multiplyBy($second); // = 9.0496 m

echo $first->divideBy($second); // = 2.2178217822 m

在操作具有不同单位的测量时，转换会自动应用。返回的测量值以基本单位定义。

use Measurements\Measurement;
use Measurements\Units\UnitLength;

$decimeters = new Measurement(44.8, UnitLength::decimeters());
$centimeters = new Measurement(202, UnitLength::centimeters());

echo $decimeters->add($centimeters); // = 6.5 m

echo $decimeters->subtract($centimeters); // = 2.46 m

echo $decimeters->multiplyBy($centimeters); // = 9.0496 m

echo $decimeters->divideBy($centimeters); // = 2.2178217822 m

还可以使用值对测量值进行算术运算。

use Measurements\Measurement;
use Measurements\Units\UnitLength;

$centimeters = new Measurement(42, UnitLength::centimeters());

echo $centimeters->addValue(8); // = 50 cm

echo $centimeters->subtractValue(12); // = 30 cm

echo $centimeters->multiplyByValue(2); // = 84 cm

echo $centimeters->divideByValue(2); // = 21 cm

使用自定义单位

除了提供的单位外，您还可以定义自定义单位。自定义单位可以从现有类型的符号和转换器初始化，或者作为现有类型的类方法实现，以便更方便地使用。您还可以定义自己的 Dimension 子类来表示全新的单位维度。

使用指定符号和定义初始化自定义单位

定义自定义单位最简单的方法是创建现有 Dimension 子类的实例。

例如，让我们定义一个跳作为自定义的非标准长度单位（1跳 = 1.82米）。您可以创建 UnitLength 的新实例，如下所示

$jump = new UnitLength("jump", new UnitConverterLinear(1.82));

扩展现有维度子类

或者，您可以扩展现有的 Dimension 子类来定义新的单位。

例如，让我们将我们的新跳单位定义为自定义子类

class UnitJump extends UnitLength {

	public static function jumps()
	{
		return new static("jump", new UnitConverterLinear(1.82));
	}

}

创建自定义维度子类

您可以创建 Dimension 的新子类来描述新的单位维度。

例如，让我们定义数字数据单位。在计算机和电信领域，信息单位是某些标准数据存储系统或通信信道的容量，用于衡量其他系统和信道的容量。字节或其倍数是常用的单位，用于指定计算机文件的大小和存储单元的容量。

您可以实现一个 UnitDigitalData 类，如下定义数字信息的单位

class UnitDigitalData extends Dimension {

	public static function baseUnit()
	{
		return static::bytes();
	}
	
	public static function bytes()
	{
		return new UnitDigitalData("B", new UnitConverterLinear(1.0));
	}

	public static function kilobytes()
	{
		return new UnitDigitalData("kB", new UnitConverterLinear(1000));
	}
	
	public static function megabytes()
	{
		return new UnitDigitalData("MB", new UnitConverterLinear(1000000));
	}

	public static function kibibytes()
	{
		return new UnitDigitalData("KiB", new UnitConverterLinear(1024));
	}

	public static function mebibytes()
	{
		return new UnitDigitalData("MiB", new UnitConverterLinear(1048576));
	}
	
	// ...

}

生成API文档

phpdoc -d ./src/ -t ./doc/generated --template="xml"
phpdocmd ./doc/generated/structure.xml doc/

许可证

此库是开源软件，许可协议为 MIT许可证。

marfurt / measurements

维护者

详细信息