view mayachemtools/docs/modules/man3/PseudoHeap.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 "PSEUDOHEAP 1"
.TH PSEUDOHEAP 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"
PseudoHeap
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use PseudoHeap;
.PP
use PseudoHeap qw(:all);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBPseudoHeap\fR class provides the following methods:
.PP
new, AddKeyValuePair, AddKeyValuePairs, DeleteKey, DeleteKeys, DeleteMaxKey,
DeleteMinKey, GetCurrentSize, GetKeyType, GetKeyValues, GetKeys, GetMaxKey,
GetMaxSize, GetMinKey, GetSortedKeys, GetType, SetKeyType, SetMaxSize, SetType,
StringifyPseudoHeap
.PP
PseudoHeap is designed to support tracking of a specific number of largest or smallest key/value
pairs with numeric or alphanumeric keys along with corresponding scalar or reference values.
.PP
Although PseudoHeap is conceptually similar to a heap, it lacks number of key properties of a traditional
heap data structure: no concept of root, parent and child nodes; no ordering of keys in any particular
order; no specific location greatest or smallest key.
.PP
The keys are simply stored in a hash with each key pointing to an array containing specified values.
The min/max keys are updated during addition and deletion of key/value pairs; these can be retrieved
by accessing corresponding hash.
.PP
Addition and deletion of key/value is also straightforward using hashes. However, min/max keys
need to be identified which is done using Perl sort function on the keys.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
.IP "\fBnew\fR" 4
.IX Item "new"
.Vb 1
\&    $NewPseudoHeap = new PseudoHeap(%NamesAndValues);
.Ve
.Sp
Using specified parameters \fINamesAndValues\fR names and values hash, \fBnew\fR method creates
a new object and returns a reference to a newly created \fBNewPseudoHeap\fR object. By default,
the following property names are initialized:
.Sp
.Vb 3
\&    Type = undef;
\&    KeyType = undef;
\&    MaxSize = 10;
.Ve
.Sp
Examples:
.Sp
.Vb 3
\&    $NewPseudoHeap = new PseudoHeap(
\&                               \*(AqType\*(Aq => \*(AqKeepTopN\*(Aq,
\&                               \*(AqKeyType\*(Aq => \*(AqNumeric\*(Aq);
\&
\&    $NewPseudoHeap = new PseudoHeap(
\&                               \*(AqType\*(Aq => \*(AqKeepTopN\*(Aq,
\&                               \*(AqKeyType\*(Aq => \*(AqAlphaNumeric\*(Aq,
\&                               \*(AqMaxSize\*(Aq => \*(Aq20\*(Aq);
\&
\&    $NewPseudoHeap = new PseudoHeap(
\&                               \*(AqType\*(Aq => \*(AqKeepBottomN\*(Aq,
\&                               \*(AqKeyType\*(Aq => \*(AqAlphaNumeric\*(Aq,
\&                               \*(AqMaxSize\*(Aq => \*(Aq20\*(Aq);
.Ve
.IP "\fBAddKeyValuePair\fR" 4
.IX Item "AddKeyValuePair"
.Vb 1
\&    $PseudoHeap\->AddKeyValuePair($Key, $Value);
.Ve
.Sp
Add specified \fIKey\fR and \fIValue\fR pair to pseudo heap using a new or an existing
key and returns \fBPseudoHeap\fR.
.IP "\fBAddKeyValuePairs\fR" 4
.IX Item "AddKeyValuePairs"
.Vb 1
\&    $PseudoHeap\->AddKeyValuePairs(@KeyValuePairs);
.Ve
.Sp
Adds multiple key and value pairs specified in array \fIKeyValuePairs\fR to pseudo heap
using a new or existing keys and returns \fBPseudoHeap\fR.
.IP "\fBDeleteKey\fR" 4
.IX Item "DeleteKey"
.Vb 1
\&    $PseudoHeap\->DeleteKey($Key);
.Ve
.Sp
Deletes a specified \fIKey\fR from pseudo heap and returns \fBPseudoHeap\fR.
.IP "\fBDeleteKeys\fR" 4
.IX Item "DeleteKeys"
.Vb 1
\&    $PseudoHeap\->DeleteKeys(@Keys);
.Ve
.Sp
Deletes a specified \fIKeys\fR from pseudo heap and returns \fBPseudoHeap\fR.
.IP "\fBDeleteMaxKey\fR" 4
.IX Item "DeleteMaxKey"
.Vb 1
\&    $PseudoHeap\->DeleteMaxKey();
.Ve
.Sp
Deletes a \fIMaxKey\fR along with its associated values from pseudo heap and returns
\&\fBPseudoHeap\fR.
.IP "\fBDeleteMinKey\fR" 4
.IX Item "DeleteMinKey"
.Vb 1
\&    $PseudoHeap\->DeleteMinKey();
.Ve
.Sp
Deletes a \fIMinKey\fR along with its associated values from pseudo heap and returns
\&\fBPseudoHeap\fR.
.IP "\fBGetCurrentSize\fR" 4
.IX Item "GetCurrentSize"
.Vb 1
\&    $Size = $PseudoHeap\->GetCurrentSize();
.Ve
.Sp
Returns current \fISize\fR of pseudo heap corresponding to number to keys in heap.
.IP "\fBGetKeyType\fR" 4
.IX Item "GetKeyType"
.Vb 1
\&    $KeyType = $PseudoHeap\->GetKeyType();
.Ve
.Sp
Returns \fIKeyType\fR of pseudo heap. Possible \fBKeyType\fR values: \fINumeric or Alphanumeric\fR.
.IP "\fBGetKeyValues\fR" 4
.IX Item "GetKeyValues"
.Vb 2
\&    @Values = $PseudoHeap\->GetKeyValues($Key);
\&    $NumOfValues = $PseudoHeap\->GetKeyValues($Key);
.Ve
.Sp
Returns an array containing \fBValues\fR associated with a specified \fIKey\fR in pseudo heap. In
scalar context, it returns number of values associated with a key.
.IP "\fBGetKeys\fR" 4
.IX Item "GetKeys"
.Vb 2
\&    @Keys = $PseudoHeap\->GetKeys();
\&    $NumOfKeys = $PseudoHeap\->GetKeys();
.Ve
.Sp
Returns an array containing all \fBKeys\fR in pseudo heap. In scalar context, it returns total
number of keys.
.IP "\fBGetMaxKey\fR" 4
.IX Item "GetMaxKey"
.Vb 1
\&    $MaxKey = $PseudoHeap\->GetMaxKey();
.Ve
.Sp
Returns \fIMaxKey\fR present in pseudo heap.
.IP "\fBGetMaxSize\fR" 4
.IX Item "GetMaxSize"
.Vb 1
\&    $MaxSize = $PseudoHeap\->GetMaxSize();
.Ve
.Sp
Returns \fIMaxSize\fR of pseudo heap.
.IP "\fBGetMinKey\fR" 4
.IX Item "GetMinKey"
.Vb 1
\&    $MinKey = $PseudoHeap\->GetMinKey();
.Ve
.Sp
Returns \fIMinKey\fR present in pseudo heap.
.IP "\fBGetSortedKeys\fR" 4
.IX Item "GetSortedKeys"
.Vb 2
\&    @Keys = $PseudoHeap\->GetSortedKeys();
\&    $NumOfKeys = $PseudoHeap\->GetSortedKeys();
.Ve
.Sp
Returns an array containing all sorted \fBKeys\fR in pseudo heap. In scalar context, it retruns
total number of keys.
.Sp
Keys are sorted based on values of \fBType\fR and \fBKeyType\fR for pseudo heap:
.Sp
.Vb 5
\&    Type          KeyType       SortOrder   SortOperator
\&    KeepTopN      Numeric       Descending  <=>
\&    KeepTopN      Alphanumeric  Descending  cmp
\&    KeepBottomN   Numeric       Ascending    <=>
\&    KeepBottomN   Alphanumeric  Ascending   cmp
.Ve
.IP "\fBGetType\fR" 4
.IX Item "GetType"
.Vb 1
\&    $Type = $PseudoHeap\->GetType();
.Ve
.Sp
Returns \fIType\fR of pseudo heap.
.IP "\fBSetKeyType\fR" 4
.IX Item "SetKeyType"
.Vb 1
\&    $PseudoHeap\->SetKeyType($KeyType);
.Ve
.Sp
Sets \fIKeyType\fR of pseudo heap and returns \fBPseudoHeap\fR.
.IP "\fBSetMaxSize\fR" 4
.IX Item "SetMaxSize"
.Vb 1
\&    $PseudoHeap\->SetMaxSize($MaxSize);
.Ve
.Sp
Sets \fIMaxSize\fR of pseudo heap and returns \fBPseudoHeap\fR.
.IP "\fBSetType\fR" 4
.IX Item "SetType"
.Vb 1
\&    $PseudoHeap\->SetType($Type);
.Ve
.Sp
Sets \fIType\fR of pseudo heap and returns \fBPseudoHeap\fR.
.IP "\fBStringifyPseudoHeap\fR" 4
.IX Item "StringifyPseudoHeap"
.Vb 1
\&    $PseudoHeapString = $PseudoHeap\->StringifyPseudoHeap();
.Ve
.Sp
Returns a string containing information about \fIPseudoHeap\fR object
.SH "AUTHOR"
.IX Header "AUTHOR"
Manish Sud <[e-mail]>
.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.