.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Math::PlanePath::Staircase 3pm"
.TH Math::PlanePath::Staircase 3pm "2016-05-03" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Math::PlanePath::Staircase \-\- integer points in stair\-step diagonal stripes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use Math::PlanePath::Staircase;
\& my $path = Math::PlanePath::Staircase\->new;
\& my ($x, $y) = $path\->n_to_xy (123);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This path makes a staircase pattern down from the Y axis to the X,
.PP
.Vb 10
\&     8      29
\&             |
\&     7      30\-\-\-31
\&                  |
\&     6      16   32\-\-\-33
\&             |         |
\&     5      17\-\-\-18   34\-\-\-35
\&                  |         |
\&     4       7   19\-\-\-20   36\-\-\-37
\&             |         |         |
\&     3       8\-\-\- 9   21\-\-\-22   38\-\-\-39
\&                  |         |         |
\&     2       2   10\-\-\-11   23\-\-\-24   40...
\&             |         |         |
\&     1       3\-\-\- 4   12\-\-\-13   25\-\-\-26
\&                  |         |         |
\&    Y=0 \->   1    5\-\-\- 6   14\-\-\-15   27\-\-\-28
\&
\&             ^
\&            X=0   1    2    3    4    5    6
.Ve
.PP
The 1,6,15,28,etc along the X axis at the end of each
run are the hexagonal numbers k*(2*k\-1).  The diagonal 3,10,21,36,etc up
from X=0,Y=1 is the second hexagonal numbers k*(2*k+1), formed by extending
the hexagonal numbers to negative k.  The two together are the
triangular numbers k*(k+1)/2.
.IX Xref "Hexagonal numbers Triangular numbers"
.PP
Legendre's prime generating polynomial 2*k^2+29 bounces around for some low
values then makes a steep diagonal upwards from X=19,Y=1, at a slope 3 up
for 1 across, but only 2 of each 3 drawn.
.SS "N Start"
.IX Subsection "N Start"
The default is to number points starting N=1 as shown above.  An optional
\&\f(CW\*(C`n_start\*(C'\fR can give a different start, in the same pattern.  For example to
start at 0,
.PP
.Vb 1
\&    n_start => 0
\&
\&    28
\&    29 30
\&    15 31 32
\&    16 17 33 34
\&     6 18 19 35 36
\&     7  8 20 21 37 38
\&     1  9 10 22 23 ....
\&     2  3 11 12 24 25
\&     0  4  5 13 14 26 27
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
See \*(L"\s-1FUNCTIONS\*(R"\s0 in Math::PlanePath for behaviour common to all path classes.
.ie n .IP """$path = Math::PlanePath::Staircase\->new ()""" 4
.el .IP "\f(CW$path = Math::PlanePath::Staircase\->new ()\fR" 4
.IX Item "$path = Math::PlanePath::Staircase->new ()"
.PD 0
.ie n .IP """$path = Math::PlanePath::AztecDiamondRings\->new (n_start => $n)""" 4
.el .IP "\f(CW$path = Math::PlanePath::AztecDiamondRings\->new (n_start => $n)\fR" 4
.IX Item "$path = Math::PlanePath::AztecDiamondRings->new (n_start => $n)"
.PD
Create and return a new staircase path object.
.ie n .IP """$n = $path\->xy_to_n ($x,$y)""" 4
.el .IP "\f(CW$n = $path\->xy_to_n ($x,$y)\fR" 4
.IX Item "$n = $path->xy_to_n ($x,$y)"
Return the point number for coordinates \f(CW\*(C`$x,$y\*(C'\fR.  \f(CW$x\fR and \f(CW$y\fR are
rounded to the nearest integers, which has the effect of treating each point
\&\f(CW$n\fR as a square of side 1, so the quadrant x>=\-0.5, y>=\-0.5 is covered.
.ie n .IP """($n_lo, $n_hi) = $path\->rect_to_n_range ($x1,$y1, $x2,$y2)""" 4
.el .IP "\f(CW($n_lo, $n_hi) = $path\->rect_to_n_range ($x1,$y1, $x2,$y2)\fR" 4
.IX Item "($n_lo, $n_hi) = $path->rect_to_n_range ($x1,$y1, $x2,$y2)"
The returned range is exact, meaning \f(CW$n_lo\fR and \f(CW$n_hi\fR are the smallest
and biggest in the rectangle.
.SH "FORMULAS"
.IX Header "FORMULAS"
.SS "Rectangle to N Range"
.IX Subsection "Rectangle to N Range"
Within each row increasing X is increasing N, and in each column increasing
Y is increasing pairs of N.  Thus for \f(CW\*(C`rect_to_n_range()\*(C'\fR the lower left
corner vertical pair is the minimum N and the upper right vertical pair is
the maximum N.
.PP
A given X,Y is the larger of a vertical pair when ((X^Y)&1)==1.  If that
happens at the lower left corner then it's X,Y+1 which is the smaller N, as
long as Y+1 is in the rectangle.  Conversely at the top right if
((X^Y)&1)==0 then it's X,Y\-1 which is the bigger N, again as long as Y\-1 is
in the rectangle.
.SH "OEIS"
.IX Header "OEIS"
Entries in Sloane's Online Encyclopedia of Integer Sequences related to
this path include
.Sp
.RS 4
<http://oeis.org/A084849> (etc)
.RE
.PP
.Vb 2
\&    n_start=1 (the default)
\&      A084849    N on diagonal X=Y
\&
\&    n_start=0
\&      A014105    N on diagonal X=Y, second hexagonal numbers
\&
\&    n_start=2
\&      A128918    N on X axis, except initial 1,1
\&      A096376    N on diagonal X=Y
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Math::PlanePath,
Math::PlanePath::Diagonals,
Math::PlanePath::Corner,
Math::PlanePath::ToothpickSpiral
.SH "HOME PAGE"
.IX Header "HOME PAGE"
<http://user42.tuxfamily.org/math\-planepath/index.html>
.SH "LICENSE"
.IX Header "LICENSE"
Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016 Kevin Ryde
.PP
This file is part of Math-PlanePath.
.PP
Math-PlanePath is free software; you can redistribute it and/or modify it
under the terms of the \s-1GNU\s0 General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
version.
.PP
Math-PlanePath is distributed in the hope that it will be useful, but
\&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0
or \s-1FITNESS FOR A PARTICULAR PURPOSE. \s0 See the \s-1GNU\s0 General Public License for
more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
Math-PlanePath.  If not, see <http://www.gnu.org/licenses/>.