NAME

Physics::Unit::Scalar

SYNOPSIS

# Distances
$d = new Physics::Unit::Distance('98 mi');
print $d->ToString, "\n";             # prints 157715.712 meter
$d->add('10 km');
print $d->ToString, "\n";  # prints 167715.712 meter
print $d->value, ' ', $d->default_unit->name, "\n";   # same thing

# Convert
print $d->ToString('mile'), "\n";        # prints 104.213... mile
print $d->convert('mile'), " miles\n";   # same thing (except 'miles')

$d2 = new Physics::Unit::Distance('2000');   # no unit given, use the default
print $d2->ToString, "\n";                   # prints 2000 meter

# Times
$t = Physics::Unit::Time->new('36 hours');
print $t->ToString, "\n";              # prints 129600 second

# Speed = Distance / Time
$s = $d->div($t);            # $s is a Physics::Unit::Speed object
print $s->ToString, "\n";    # prints 1.2941... mps

# Automatic typing
$s = new Physics::Unit::Scalar('kg m s');   # Unrecognized type
print ref $s, "\n";          # $s is a Physics::Unit::Scalar
$f = $s->div('3000 s^3');
print ref $f, "\n";          # $f is a Physics::Unit::Force

DESCRIPTION

This package encapsulates information about physical quantities. Each instance of a class that derives from Physics::Unit::Scalar holds the value of some type of measurable quantity. When you use this module, several new classes are immediately available. See the UnitsByType page for a list of types included with the unit library.

You will probably only need to use the classes that derive from Physics::Unit::Scalar, such as Physics::Unit::Distance, Physics::Unit::Speed, etc. You can also define your own derived classes, based on types of physical quantities.

This module relies heavily on Physics::Unit. Each Scalar object references a Unit object that defines the dimensionality of the Scalar. The dimensionality also identifies (usually) the type of physical quantity that is stored, and the derived class of the object.

For example, the class Physics::Unit::Distance uses the Physics::Unit object named 'meter' to define the scale of its object instances. The type of the 'meter' object is 'Distance'.

Defining classes that correspond to physical quantity types allows us to overload the arithmetic methods to produce derived classes of the correct type automatically. For example:

$d = new Physics::Unit::Distance('98 mi');
$t = new Physics::Unit::Time('36 years');
# $s will be of type Physics::Unit::Speed.
$s = $d->div($t);

When a new object is created, this package attempts to determine its subclass based on its dimensionality. Thus, when you multiply two Distances together, the result is an Area object. This behavior can be selectively overridden when necessary. For example, both energy and torque have the same dimensions, Force * Distance. Therefore, it remains the programmer's responsibility, in this case, to assign the correct subclass to Scalars that have this dimensionality.

See also the Physics::Unit::Scalar::Implementation page for more details.

EXPORT OPTIONS

By default, this module exports nothing. You can request all of the functions to be exported as follows:

use Physics::Unit::Scalar ':ALL';

Or, you can just get specific ones. For example:

use Physics::Unit::Scalar qw( ScalarFactory GetScalar );

FUNCTIONS

ScalarFactory($type)

Creates a new object of one of the subtypes of Scalar, from an expression. The syntax of the expression is the same as the unit expression used by the Physics::Unit module.

The class of the resultant object matches the type of the unit created. If the type is not recognized or ambiguous, then the class of the resultant object will be Physics::Unit::Scalar.

GetScalar($arg)

This convenience function takes an object reference or an expression, and returns a Physics::Unit::Scalar object. If $arg is an object reference, it is simply returned.

METHODS

CLASS->new([$value])

$s->new()

Package or object method. This makes a new user defined Scalar (or derived class) object. For example:

# This creates an object of a derived class
$d = new Physics::Unit::Distance('3 miles');

# This does the same thing; the type is figured out automatically
# $d will be a Physics::Unit::Distance
$d = new Physics::Unit::Scalar('3 miles');

# Use the default unit for the subtype (for Distance, it's meters):
$d = new Physics::Unit::Distance(10);

# This defaults to one meter:
$d = new Physics::Unit::Distance;

# Copy constructor:
$d2 = $d->new;

If the type cannot be identified by the dimensionality of the unit, then a Physics::Unit::Scalar object is returned.

$s->ToString([$unit])

Returns a string representation of the scalar, either in the default units or the unit specified.

$s->default_unit()

Get the default unit object which is used when printing out the given Scalar.

$s->convert($unit)

Returns the numerical value of this scalar expressed in the given Unit.

$s->value([$newValue])

Get or set the value.

$s->add($v)

Add another Scalar to the provided one.

$s->neg($v)

Take the negative of the Scalar

$s->subtract($v)

Subtract another Scalar from this one.

$s->times($v)

This returns a new object which is the product of $self and the argument. Neither the original object nor the argument is changed.

[FIXME: see Github issue #22. These methods should all work the same way. Either all change the value of the existing object, or all return a new object.]

$s->recip($v)

Returns a new Scalar object which is the reciprocal of the object. The original object is unchanged.

$s->divide($v)

This returns a new Scalar object which is a quotient. Neither the original object nor the argument is changed.

AUTHOR

Chris Maloney <voldrani@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2002-2003 by Chris Maloney

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.