NAME
CXC::Number::Sequence::Linear  Numeric Sequence with Equal Spacing
VERSION
version 0.05
SYNOPSIS
use CXC::Number::Sequence::Linear;
$sequence = CXC::Number::Sequence::Linear>new( %options );
$values = $sequence>sequence;
DESCRIPTION
CXC::Number::Sequence::Linear constructs a finite sequence of increasing, equally spaced, numbers.
It subclasses CXC::Number::Sequence, so see documentation for that class for additional methods.
Sequence extrema may be specified or may be calculated from other parameters, such as spacing, the number of elements, or a sequence center, and the sequence may be aligned on a fiducial value,
Sequence extrema may be hard, indicating that the sequence must exactly cover the extrema, or soft, indicating that the sequence may cover a larger range. Usually the combination of parameters will uniquely determine whether an extremum is soft or hard, but in some cases soft bounds must be explicitly labelled as soft, requiring use of the soft_min
and soft_max
parameters.
A full description of the available parameters may be found in the description of the constructor "new".
Valid Parameter Combinations
Note: If the sequence extrema are equal to the range bounds, then the sequence exactly covers the range. Otherwise, the sequence will cover the range, but may extend beyond one or more of the extrema.
min
,max
,nelem
.
The sequence exactly covers the specified range.
min
,max
,spacing

If an integral multiple of
spacing
fits within the range, the sequence exactly covers it, otherwise the sequence is centered on the range. min
,nelem
,spacing
max
,nelem
,spacing

The number of elements is chosen to exactly covers the calculated range.
min
,soft_max
,spacing
soft_min
,max
,spacing

The hard extremum is as specified. The number of elements is chosen to cover the specified range.
center
,spacing
,nelem

The sequence is centered as specified and exactly covers the range.
center
,rangew
,nelem

The sequence is centered as specified and exactly covers the range.
center
,rangew
,spacing

The sequence is centered as specified and covers the range.
center
,soft_min
,soft_max
,nelem
center
,soft_min
,soft_max
,spacing

The sequence is centered on the specified center and covers the specified range.
min
,max
,spacing
,align
min
,max
,nelem
,align

The sequence covers the specified range and is aligned so that the specified alignment point is at the specified relative position between elements.
Methods
new
$sequence = CXC::Number::Sequence::Linear>new( %attr );
Construct a linear spaced sequence. The available attributes are those for the parent constructor in CXC::Number::Sequence, as well as the following:
force_extrema
Boolean
Sometimes the extrema of the sequence will not exactly match what was specified because of roundoff error. If this option is true, then sequences extrema will be set to the specified values. This may result in spacings which are slightly different in size (the exact spacings are available via the
spacing
method). min
soft_min

The minimum value that the sequence should cover. Use
soft_min
to disambiguate hard from soft limits as documented above. max
soft_max

The maximum value that the sequence should cover. Use
soft_max
to disambiguate hard from soft limits as documented above. center

The center of the sequence. If there are an odd number of elements, this will be the center element, otherwise it will be the average of the middle two.
rangew

The width of the range to be covered by the sequence.
nelem

The number of elements in the sequence
spacing

The distance between elements in the sequence.
align
= [ $P, $f ]
The sequence will be aligned such that the fiducial value
$P
is located at the fractional position$f
between elements.$P
need not be in the range of data covered by the sequence.For example, to align the sequence such that
0
falls exactly half way between two elements, even though the generated sequence doesn't include0
:use Data::Dump; use aliased 'CXC::Number::Sequence::Linear'; dd Linear>new( min => 5.1, max => 8, spacing => 1, align => [ 0, 0.5 ], )>elements;
results in
[4.5, 5.5, 6.5, 7.5, 8.5]
If an inconsistent set of parameters is passed, new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::interface
.
If an unknown parameter is passed, new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::unknown
.
If a parameter value is illegal (e.g., a negative spacing), or a combination of values is illegal ( e.g. min > max
, new
will throw an exception of class CXC::Number::Sequence::Failure::parameter::constraint
.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CXCNumber or by email to bugcxcnumber@rt.cpan.org.
When submitting a bug or request, please include a testfile or a patch to an existing testfile that illustrates the bug or desired feature.
SEE ALSO
Please see those modules/websites for more information related to this module.
AUTHOR
Diab Jerius <djerius@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2019 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007