std.units

std.units is a D implementation of Boost.Units library.

Authors:
Arlen Avakian

License:
Boost License 1.0

Source:
std/units.d

Acknowledgements:
Thanks to Matthias Christian Schabel, Steven Watanabe, and all the people who have contributed to Boost.units.

Synopsis:

   import std.units, std.complex, std.stdio;

   Quantity!(si.Energy) work(Quantity!(si.Force) F, Quantity!(si.Length) dx)
   {
       return F * dx;
   }

   void main()
   {
       Quantity!(si.Force)  F  = 2.0 * si.newton;
       Quantity!(si.Length) dx = 2.0 * si.meter;
       Quantity!(si.Energy) E  = work(F, dx);
       writefln("F  = %s\ndx = %s\nE  = %s\n", F, dx, E);

       alias Complex!double ComplexType;

       Quantity!(si.ElectricPotential, ComplexType) v = complex(12.5, 0) * si.volts;
       Quantity!(si.Current, ComplexType)           i = complex(3, 4) * si.amperes;
       Quantity!(si.Resistance, ComplexType)        z = complex(1.5, -2) * si.ohms;
       writefln("V   = %s\nI   = %s\nZ   = %s\nI*Z = %s\nI*Z == V? %s",
                v, i, z, i*z, i*z == v);
   }

   F  = 2 N
   dx = 2 m
   E  = 4 J


   V   = 12.5+0i V
   I   = 3+4i A
   Z   = 1.5-2i Ohm
   I*Z = 12.5+0i V
   I*Z == V? true
   

alias std.rational.Rational!(long).Rational QQ;

QQ be thy name.

template baseDimension(string name)

Defines a base dimension.

Examples:

  alias baseDimension!"length" lengthBaseDimension;
  static assert(lengthBaseDimension == "length_bd()");

template isBaseDimension(T)

Check to see if T is a BaseDimension.

template dimension(pairs...)

Given one or more pairs of base dimensions and exponents, this template creates a composite dimension, or simply put, a dimension. The resulting dimension is in the form of a reduced dimension. The exponents can be either of type integer or Rational.

Examples:

   alias dimension!(lengthBaseDimension, QQ(2)) areaDimension;
   alias dimension!(massBaseDimension,    1,
                    lengthBaseDimension,  2,
                    timeBaseDimension,   -2) energyDimension;

pure nothrow @safe Scale scale()(uint base, QQ exponent, string name, string symbol);
pure nothrow @safe Scale scale(G)(uint base, G exponent, string name, string symbol);
pure nothrow @safe Scale scale(E)(uint base, E exponent);

Helper function that returns a scale with the specified base and exponent. The name and the symbol are optional. Internally if a scale value matches one of the predefined prefixes, the DecimalPrefix and the BinaryPrefix, it will be used instead.

template isScale(T)

Check to see if T is a Scale.

enum DecimalPrefix;

Yocto

Zepto

Atto

Femto

Pico

Nano

Micro

Milli

Centi

Deci

Deka

Hecto

Kilo

Mega

Giga

Tera

Peta

Exa

Zetta

Yotta

enum BinaryPrefix;

Kibi

Mebi

Gibi

Tebi

Pebi

Exbi

template baseUnit(alias dimension, string name, string symbol) if (isDimension!(typeof(dimension)))

Defines a base unit.

Examples:

   alias baseUnit!(lengthDimension, "meter", "m") meterBaseUnit;

template scaledBaseUnit(alias bu, alias scale) if (isBaseUnit!(typeof(bu)) && (isScale!(typeof(scale)) || is(typeof(scale) == DecimalPrefix) || is(typeof(scale) == BinaryPrefix)))

Defines a base unit that is a multiple of base unit bu.

Examples:

   alias scaledBaseUnit!(cgs.gramBaseUnit, DecimalPrefix.Kilo) kilogramBaseUnit;

template scaledBaseUnit(alias bu, alias scale, string name, string symbol) if (isBaseUnit!(typeof(bu)) && (isScale!(typeof(scale)) || is(typeof(scale) == DecimalPrefix) || is(typeof(scale) == BinaryPrefix)))

Defines a base unit, named name and having the symbol symbol, that is a multiple of base unit bu.

Examples:

   alias baseUnit!(cgs.gramBaseUnit, scale(10, 3), "", "グラム") newKilogramBaseUnit;
   writeln(2.0 * UnitOf!(newKilogramBaseUnit)());

   2 kグラム
   

template baseUnitWithConversion(string name, string symbol, U, string factor) if (isUnit!(U) && isValidFactor!(factor))
template baseUnitWithConversion(string name, string symbol, alias bu, string factor) if (is(typeof(bu) == BaseUnit) && isValidFactor!(factor))

Defines a base unit and conversion to a dimensionally-consistent unit U or a base unit bu. factor is string representation of a numeric value, be it an integer, real, or rational. This does what BOOST_UNITS_DEFINE_BASE_UNIT_WITH_CONVERSIONS in BOOST.units does.

Examples:

   alias baseUnitWithConversion!("pint", "pt", si.volume, "QQ(946353, 2000000000)") pintBaseUnit;
   alias baseUnitWithConversion!("pound", "lb", cgs.gramBaseUnit, "453.592") poundBaseUnit;

template DefineBaseUnit(alias dimension, string name, string symbol)

Defines a base unit and conversions to other units or to other base units with the correct dimensions.

Examples:

   alias DefineBaseUnit!(lengthDimension, "ABC", "abc") Abc;

template WithConversionFactors(Pairs...)

with conversion factors Pairs, where each pair is either a unit and a factor or a base unit and a factor.

Examples:

       alias Abc.WithConversionFactors!(cgs.centimeterBaseUnit, "QQ(2,3)") AbcBaseUnit1;

template WithDefaultConversion(U) if (isUnit!(U))

with a default conversion U which is applied when no direct conversion is available. U is any unit with the same dimensions.

Examples:

       alias Abc.WithDefaultConversion!(si.Length) AbcBaseUnit2;

template WithConversions(U, Pairs...) if (isUnit!(U))

with a default conversion U and conversion factors Pairs.

Examples:

       alias Abc.WithConversions!(si.Length, cgs.centimeterBaseUnit, "QQ(2,3)") AbcBaseUnit3;

void defineUnitInfo(U)(string name, string symbol);

Use this to define a name and a symbol for derived unit U. Subsequent calls will override the previous definition.

Examples:

   writeln(2.0 * si.Energy());

   2 J
   

   defineUnitInfo!(si.Energy)("XYZ", "xyz");
   writeln(2.0 * si.Energy());

   2 xyz
   

struct Unit(alias dim, alias sys) if (isHomogeneousSystem!(typeof(sys)) || isHeterogeneousSystem!(typeof(sys)));

struct representing a model-dependent unit with no associated value.

alias typeof(sys) System;

Dimension dimension;

System system;

UnitInfo info;

bool hasDimensionlessSystem;

pure nothrow @safe Unit opUnary(string op)();

pure nothrow @safe Unit opBinary(string op)(Unit other);

nothrow auto opBinary(string op, U)(U other);

template power(alias r)

template root(alias r)

Quantity!(Unit, N) opBinary(string op, N)(N n);

auto opBinaryRight(string op, N)(N n);

const void toString(scope void delegate(const(char)[]) sink, FormatSpec!(char) fmtspec);

Converts the unit to a string representation.

Supported Formats:
'y' for symbol format; reduces unit names to known symbols for both base and derived units.

Examples:

           writefln("%y", si.Force() * si.Length());
           writefln("%y", si.Force() * si.Energy()); // unknown

           J
           kg^2 m^3 s^-4
           

'n' for name format; outputs full unit names for base and derived units.

Examples:

           writefln("%n", si.Force() * si.Length());

           joule
           

'r' for raw format; outputs only symbols for base units but not derived units.

Examples:

           writefln("%r", si.Force() * si.Length());

           kg m^2 s^-2
           

's' defaults to symbol format.

Examples:

           writeln(si.Force() * si.Length());

           J
           

template ScaledUnit(U, alias scale) if (isUnit!(U) && isHomogeneousSystem!(U.System))
template ScaledUnit(U, alias scale) if (isUnit!(U) && isHeterogeneousSystem!(U.System))

Defines a unit that is a multiple of unit U.

Examples:

   alias ScaledUnit!(si.Time, scale(10, -9)) Nanosecond;
   Quantity!(Nanosecond) t = 1.0 * si.seconds;
   writeln(t1);

   1e9 ns
   

template isUnit(T)

Check to see if T is a Unit.

template isDimensionlessUnit(U) if (isUnit!(U))

Check to see if U is a dimensionless unit.

template makeSystem(BU...)

Returns a homogeneous system that can represent any combination of the base units. There must be no way to represent any of the base units in terms of the others.

template UnitOf(alias bu) if (isBaseUnit!(typeof(bu)))

Returns the unit corresponding to base unit bu.

struct Quantity(U, Y = double) if ((isUnit!(U) || isAbsolute!(U)) && !isUnit!(Y) && !isAbsolute!(Y));

struct representing a quantity.

alias U UnitType;

alias Y ValueType;

pure nothrow @safe this()(ValueType val);

pure nothrow @safe this(Qu)(Qu source);

pure nothrow @safe this(Qu)(Qu source);

pure nothrow @safe Quantity opAssign(T : ValueType)(T val);

pure nothrow @safe Quantity opAssign(Qu)(Qu source);

pure nothrow @safe Quantity opOpAssign(string op)(Quantity source);

pure nothrow @safe this(T : ValueType)(Quantity!(U, T) source);

const pure nothrow @safe ValueType value();

pure nothrow ref @safe auto opOpAssign(string op)(ValueType source);

Quantity opDispatch(string fn)();

Used to apply a function to the value of this quantity.

const pure nothrow @safe Quantity opUnary(string op)();

const pure nothrow @safe Quantity opBinary(string op, N)(N x);

quantity * value and quantity / value

const pure nothrow @safe auto opBinaryRight(string op, N)(N val);

value * quantity and value / quantity

const pure nothrow @safe auto opBinary(string op, U)(U u);

quantity * unit and quantity / unit

const pure nothrow @safe auto opBinaryRight(string op, U)(U u);

unit * quantity and unit / quantity

const pure nothrow @safe Quantity opBinary(string op)(Quantity other);

quantityA + quantityA and quantityA - quantityA

const pure nothrow @safe auto opBinary(string op, Qu)(Qu other);

quantity * quantity and quantity / quantity

const pure nothrow @property @safe auto power(alias r)();

Raises the quantity as a whole to the power of r.

const pure nothrow @property @safe auto root(alias r)();

Returns the root value of the quantity as a whole.

template isQuantity(T)

Check to see if T is a Quantity.

template isDimensionlessQuantity(Q) if (isQuantity!(Q))

Check to see if Q is a dimensionless quantity.

struct Absolute(Y);

A wrapper to represent absolute units (points rather than vectors).

template isAbsolute(T)

Check to see if T is an Absolute.

Copyright (c) 2012, Arlen Avakian | Page generated by Ddoc.