The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CXC-Number-0.04
River stage zero No dependents
++
/ CXC::Number::Sequence::Linear

NAME

CXC::Number::Sequence::Linear - Numeric Sequence with Equal Spacing

VERSION

version 0.04

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 round-off 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 include 0:

 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=CXC-Number or by email to bug-cxc-number@rt.cpan.org.

When submitting a bug or request, please include a test-file or a patch to an existing test-file 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