view mayachemtools/docs/modules/man3/Path.3 @ 0:73ae111cf86f draft

Uploaded

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PATH 1"
.TH PATH 1 "2015-03-29" "perl v5.14.2" "MayaChemTools"
.\" 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"
Path \- Path class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Graph::Path;
.PP
use Graph::Path qw(:all);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPath\fR class provides the following methods:
.PP
new, AddVertex, AddVertices, Copy, GetCommonVertices, GetEdges, GetEndVertex,
GetLength, GetStartVertex, GetTerminalVertices, GetVertex, GetVertices, IsCycle,
IsIndependentCyclicPath, IsIndependentPath, IsPath, Join, JoinAtVertex, PopVertex,
PushVertex, PushVertices, Reverse, ShiftVertex, StringifyPath, UnshiftVertex,
UnshiftVertices
.PP
Path is a sequential list of vertices with an edge between two successive vertices. The path
becomes a cycle when start vertex and end vertex are the same.
.PP
The following operators are overloaded:
.PP
.Vb 1
\&    "" == eq
.Ve
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 2
\&    $NewPath = new Path();
\&    $NewPath = new Path(@VertexIDs);
.Ve
.Sp
Using specified \fIVertexIDs\fR, \fBnew\fR method creates a new \fBPath\fR object and returns
newly created \fBPath\fR object.
.IP "\fBAddVertex\fR" 4
.IX Item "AddVertex"
.Vb 1
\&    $Path\->AddVertex($VertexID);
.Ve
.Sp
Adds \fIVertexID\fR to \fIPath\fR and returns \fIPath\fR.
.IP "\fBAddVertices\fR" 4
.IX Item "AddVertices"
.Vb 1
\&    $Path\->AddVertices(@VertexIDs);
.Ve
.Sp
Adds vertices using \fIVertexIDs\fR to \fIPath\fR and returns \fIGraph\fR.
.IP "\fBCopy\fR" 4
.IX Item "Copy"
.Vb 1
\&    $Return = $Path\->Copy();
.Ve
.Sp
Copies \fIPath\fR and its associated data using \fBStorable::dclone\fR and returns a new
\&\fBPath\fR object.
.IP "\fBGetCommonVertices\fR" 4
.IX Item "GetCommonVertices"
.Vb 2
\&    @CommonVertices = $Path\->GetCommonVertices($OtherPath);
\&    $NumOfCommonVertices = $Path\->GetCommonVertices($OtherPath);
.Ve
.Sp
Returns an array containing common vertex IDs between two paths. In scalar context, number
of common vertices is returned.
.IP "\fBGetEdges\fR" 4
.IX Item "GetEdges"
.Vb 2
\&    @EdgesVertexIDs = $Path\->GetEdges();
\&    $NumOfEdges = $Path\->GetEdges();
.Ve
.Sp
Returns an array containg successive paris of vertex IDs corresponding to all edges in \fIPath\fR.
In scalar context, the number of edges is returned.
.IP "\fBGetEndVertex\fR" 4
.IX Item "GetEndVertex"
.Vb 1
\&    $VertexID = $Path\->GetEndVertex();
.Ve
.Sp
Returns \fBVertexID\fR of end vertex in \fIPath\fR.
.IP "\fBGetLength\fR" 4
.IX Item "GetLength"
.Vb 1
\&    $Length = $Path\->GetLength();
.Ve
.Sp
Returns \fBLength\fR of \fIPath\fR corresponding to number of vertices in \fIPath\fR.
.IP "\fBGetStartVertex\fR" 4
.IX Item "GetStartVertex"
.Vb 1
\&    $VertexID = $Path\->GetStartVertex();
.Ve
.Sp
Returns \fBVertexID\fR of start vertex in \fIPath\fR.
.IP "\fBGetTerminalVertices\fR" 4
.IX Item "GetTerminalVertices"
.Vb 1
\&    ($StartVertexID, $EndVertexID) = $Path\->GetTerminalVertices();
.Ve
.Sp
Returns vertex IDs of start and end vertices in \fIPath\fR.
.IP "\fBGetVertex\fR" 4
.IX Item "GetVertex"
.Vb 1
\&    $VertexID = $Path\->GetVertex($Index);
.Ve
.Sp
Returns specific vertex \s-1ID\s0 from \fIPath\fR corresponding to \fIIndex\fR with indicies starting from 0.
.IP "\fBGetVertices\fR" 4
.IX Item "GetVertices"
.Vb 2
\&    @Vertices = $Path\->GetVertices();
\&    $NumOfVertices = $Path\->GetVertices();
.Ve
.Sp
Returns an array containing all vertex IDs in \fIPath\fR. In scalar context, number of vertices
is returned.
.IP "\fBIsCycle\fR" 4
.IX Item "IsCycle"
.Vb 1
\&    $Status = $Path\->IsCycle();
.Ve
.Sp
Returns 1 or 0 based on whether \fIPath\fR is a \fBCyclicPath\fR which has the same start and
end vertex IDs.
.IP "\fBIsIndependentCyclicPath\fR" 4
.IX Item "IsIndependentCyclicPath"
.Vb 1
\&    $Status = $Path\->IsIndependentCyclicPath();
.Ve
.Sp
Returns 1 or 0 based on whether \fIPath\fR is an independent \fBCyclicPath\fR. For a \fIPath\fR to be
an independent cyclic path, it must be a cyclic path and have unique vertices.
.IP "\fBIsIndependentPath\fR" 4
.IX Item "IsIndependentPath"
.Vb 1
\&    $Status = $Path\->IsIndependentPath();
.Ve
.Sp
Returns 1 or 0 based on whether \fIPath\fR is an independent \fBPath\fR. For a \fIPath\fR to be
an independent path, it must have unique vertices.
.IP "\fBIsPath\fR" 4
.IX Item "IsPath"
.Vb 1
\&    $Status = Graph::Path::IsPath();
.Ve
.Sp
Returns 1 or 0 based on whether \fIObject\fR is a \fBPath\fR object
.IP "\fBJoin\fR" 4
.IX Item "Join"
.Vb 2
\&    $NewPath = $Path\->Join($OtherPath);
\&    $NewPath = $Path\->Join(@VertexIDs);
.Ve
.Sp
Joins existing \fIPath\fR with a new path specified as a \fIOtherPath\fR object or an array of \fIVertexIDs\fR
and returns \fINewPath\fR.
.Sp
In order to successfully join two paths, terminal vertices must have a common vertex. Based on the
common terminal vertex found, additional path vertices are added to the current \fIPath\fR in one of
the following four ways:
.Sp
.Vb 2
\&    . EndVertex = NewStartVertex: New path at end of current path with
\&      same vertices order
\&
\&    . EndVertex = NewEndVertex: New path at end of current path with
\&      reversed vertices order
\&
\&    . StartVertex = NewEndVertex: New path at front of current path
\&      with same vertices order
\&
\&    . StartVertex = NewStartVertex: New path at front of current path
\&      with reversed vertices order
.Ve
.IP "\fBJoinAtVertex\fR" 4
.IX Item "JoinAtVertex"
.Vb 1
\&    $NewPath = $Path\->JoinAtVertex($OtherPath, $CenterVertexID);
.Ve
.Sp
Joins existing \fIPath\fR with \fIOtherPath\fR at a specified \fICeterVertexID\fR and returns a \fINewPath\fR.
.IP "\fBPopVertex\fR" 4
.IX Item "PopVertex"
.Vb 1
\&    $Path\->PopVertex();
.Ve
.Sp
Removes end vertex from \fIPath\fR and returns \fIPath\fR.
.IP "\fBPushVertex\fR" 4
.IX Item "PushVertex"
.Vb 1
\&    $Path\->PushVertex($VertexID);
.Ve
.Sp
Adds \fIVertexID\fR to \fIPath\fR after end vertex and returns \fIPath\fR.
.IP "\fBPushVertices\fR" 4
.IX Item "PushVertices"
.Vb 1
\&    $Path\->PushVertices(@VertexIDs);
.Ve
.Sp
Adds \fIVertexIDs\fR to \fIPath\fR after end vertex and returns \fIPath\fR.
.IP "\fBReverse\fR" 4
.IX Item "Reverse"
.Vb 1
\&    $Path\->Reverse();
.Ve
.Sp
Reverses order of vertices in \fIPath\fR and returns \fIPath\fR.
.IP "\fBShiftVertex\fR" 4
.IX Item "ShiftVertex"
.Vb 1
\&    $Path\->ShiftVertex();
.Ve
.Sp
Removes start vertex from \fIPath\fR and returns \fIPath\fR.
.IP "\fBStringifyPath\fR" 4
.IX Item "StringifyPath"
.Vb 1
\&    $String = $Path\->StringifyPath();
.Ve
.Sp
Returns a string containing information about \fIPath\fR object.
.IP "\fBUnshiftVertex\fR" 4
.IX Item "UnshiftVertex"
.Vb 1
\&    $Path\->UnshiftVertex($VertexID);
.Ve
.Sp
Adds \fIVertexID\fR to \fIPath\fR before start vertex and returns \fIPath\fR.
.IP "\fBUnshiftVertices\fR" 4
.IX Item "UnshiftVertices"
.Vb 1
\&    $Path\->UnshiftVertices(@VertexIDs);
.Ve
.Sp
Adds \fIVertexIDs\fR to \fIPath\fR before start vertex and returns \fIPath\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Manish Sud <[e-mail]>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
PathGraph.pm, PathsTraversal.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2015 Manish Sud. All rights reserved.
.PP
This file is part of MayaChemTools.
.PP
MayaChemTools is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option)
any later version.