The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Word2vec-Interface-0.037
River stage zero No dependents
4 ++
/ Word2vec::Bst

NAME

Word2vec::Bst - xmltow2v Basic Binary Search Tree Module

SYNOPSIS

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $rootNode = $bst->CreateBST( $sortedArrayRef, 0, $arySize, undef );
 $bst->SetRootNode( $rootNode );

 my $node1 = $bst->BSTExactSearch( $rootNode, "Coffee" );
 my $node2 = $bst->BSTContainsSearch( $rootNode, "Coffee" );

 print( "Exact Phrase Match Found - Search Word: \"Coffee\"\n" ) if defined( $node1 );
 print( "Exact Phrase: \"Coffee\" Not Found\n" ) if !defined( $node1 );
 print( "Phrase Containing Word: \"Coffee\" Found\n" ) if defined( $node2 );
 print( "Phrase Containing Word: \"Coffee\" Not Found\n" ) if !defined( $node2 );

 undef( @sortedArray );
 $bst->DESTROY();
 undef( $bst );

DESCRIPTION

Word2vec::Bst is a basic binary search tree module for use with Word2vec::Xmltow2v. This module expects a sorted array passed as a function parameter (array reference) to create a balanced binary search tree.

Main Functions

new

Description:

 Returns a new 'Word2vec::Bst' module object.

Input:

 None

Output:

  Word2vec::Bst object.

Example:

 use Word2vec::Bst;
 my $bst = Word2vec::Bst->new();

 print( "Word2vec::Bst object creation successful\n" ) if defined( $bst );
 print( "Word2vec::Bst object creation un-successful\n" ) if !defined( $bst );

 print( "Removing Tree From Memory\n" ) if defined( $bst );
 $bst->DESTROY() if defined( $bst );
 undef( $bst );

DESTROY

Description:

 Removes binary search tree from memory.

Input:

 None

Output:

 None

Example:

 See above example for "new" function.

 Note: Destroy function is also automatically called during global destruction when exiting the program.

CreateTree

Description:

 Creates binary search tree with required function parameters and sets member variable root node in 'Word2vec::Bst' object.

 Note: The array must be sorted before calling this method to create a balanced tree.

Input:

 $arrayReference -> Reference to an array containing sorted string data.
 $startIndex     -> Beginning index of sorted array which the function incorporates into the binary tree.
 $endIndex       -> Last index of the sorted array which the function incorporates into the binary tree.
 $parentNode     -> Parent node parameter of type 'Word2vec::Node'. Set to 'undef' during tree instantiation.

Output:

 $value          -> '0' if successful / '-1' if un-successful.

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree Creation Un-Successful\n" ) if $result == -1;

 $bst->DESTROY() if defined( $bst );
 undef( $bst );

CreateBST

Description:

 Creates binary search tree with required function parameters. Returns the root node.

 Note: The array must be sorted before calling this method to create a balanced tree.

Input:

 $arrayReference  -> Reference to an array containing sorted string data.
 $startIndex      -> Beginning index of sorted array which the function incorporates into the binary tree.
 $endIndex        -> Last index of the sorted array which the function incorporates into the binary tree.
 $parentNode      -> Parent node parameter of type 'Word2vec::Node'. Set to 'undef' during tree instantiation.

Output:

 Word2vec::Node -> Binary Search Tree root node or 'undef'.

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $rootNode = $bst->CreateBST( $sortedArrayRef, 0, $arySize, undef );
 $bst->SetRootNode( $rootNode );

 $bst->DESTROY() if defined( $bst );
 undef( $bst );

BSTContainsSearch

Description:

 Searches binary search tree nodes to see if 'node->data' contains passed string parameter,
 beginning with the passed node parameter and propagates down the tree until found.

Input:

 Word2vec::Node   -> Starting tree node to search. (ie. Begin at root node)
 string           -> Search word/phrase.

Output:

 Word2vec::Node -> Returns binary search tree node or 'undef' if not found.

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree - Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree - Creation Un-successful\n" ) if $result == -1;
 die "" if $result == -1;

 my $node = $bst->BSTContainsSearch( $rootNode, "Coffee" );

 print( "Phrase Containing Word: \"Coffee\" Found\n" ) if defined( $node );
 print( "Phrase Containing Word: \"Coffee\" Not Found\n" ) if !defined( $node );

 undef( @sortedArray );
 $bst->DESTROY();
 undef( $bst );

BSTExactSearch

Description:

 Searches binary search tree for passed string parameter, beginning with passed node and propagates
 down the tree until found.

Input:

 Word2vec::Node   -> Starting tree node to search. (ie. Begin at root node)
 string           -> Search word/phrase.

Output:

 Word2vec::Node -> Returns binary search tree node or 'undef' if not found.

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree - Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree - Creation Un-successful\n" ) if $result == -1;
 die "" if $result == -1;

 my $node = $bst->BSTExactSearch( $rootNode, "Money" );

 print( "Exact Phrase Match Found - Search Word: \"Money\"\n" ) if defined( $node );
 print( "Exact Phrase: \"Money\" Not Found\n" ) if !defined( $node );

 undef( @sortedArray );
 $bst->DESTROY();
 undef( $bst );

DeleteBSTNodes

Description:

 Recursive function that deletes all parameter node's left and right children that propagates downward. Called by
 DESTROY() function to remove tree from memory.

Input:

 Word2vec::Node -> Starting node of tree to remove from memory. (ie. root node)

Output:

 None

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree - Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree - Creation Un-successful\n" ) if $result == -1;
 die "" if $result == -1;

 print( "Destroying Binary Search Tree\n" );

 $bst->DESTROY();

 undef( @sortedArray );
 undef( $bst );

Accessor Functions

GetDebugLog

Description:

 Returns the _debugLog member variable set during Word2vec::Bst object initialization of new function.

Input:

 None

Output:

 $value -> 0 = False, 1 = True

Example:

 use Word2vec::Bst;

 my $bst = Word2vec::Bst->new();
 my $debugLog = $bst->GetDebugLog();

 print( "Debug Logging Enabled\n" ) if $debugLog == 1;
 print( "Debug Logging Disabled\n" ) if $debugLog == 0;

 undef( $bst );

GetWriteLog

Description:

 Returns the _writeLog member variable set during Word2vec::Bst object initialization of new function.

Input:

 None

Output:

 $value -> 0 = False, 1 = True

Example:

 use Word2vec::Bst;

 my $bst = Word2vec::Bst->new();
 my $writeLog = $bst->GetWriteLog();

 print( "Write Logging Enabled\n" ) if $writeLog == 1;
 print( "Write Logging Disabled\n" ) if $writeLog == 0;

 undef( $bst );

GetRootNode

Description:

 Returns binary search tree root node.

Input:

 None

Output:

 Word2vec::Node -> Binary Search Tree Root Node

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree - Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree - Creation Un-successful\n" ) if $result == -1;
 die "" if $result == -1;

 my $rootNode = $bst->GetRootNode();

 print( "BST Root Node Exists\n" ) if defined( $rootNode );
 print( "BST Root Node Does Not Exist\n" ) if !defined( $rootNode );

 print( "Root Node Contains Data: " . $rootNode->data . "\n" ) if defined( $rootNode ) && defined( $rootNode->data );

 print( "Destroying Binary Search Tree\n" );

 $bst->DESTROY();

 undef( @sortedArray );
 undef( $bst );

Mutator Functions

SetRootNode

Description:

 Sets binary search tree root node to passed node parameter.

Input:

 Word2vec::Node -> Binary Search Tree node which will be set to the root node of the tree.

Output:

 None

Example:

 use Word2vec::Bst;

 my @sortedArray = ( "Cookie", "Lungs", "Money", "Veterinarian", "Dog", "Urn", "Heart", "Coffee Grounds" );
 @sortedArray = sort( @sortedArray );

 my $sortedArrayRef = \@sortedArray;
 my $arySize = @sortedArray;

 my $bst = Word2vec::Bst->new();
 my $result = $bst->CreateTree( $sortedArrayRef, 0, $arySize, undef );

 print( "Binary Search Tree - Created Successfully\n" ) if $result == 0;
 print( "Binary Search Tree - Creation Un-successful\n" ) if $result == -1;
 die "" if $result == -1;

 my $rootNode = $bst->GetRootNode();

 print( "BST Root Node Exists\n" ) if defined( $rootNode );
 print( "BST Root Node Does Not Exist\n" ) if !defined( $rootNode );

 $bst->SetRootNode( $rootNode ) if defined( $rootNode );

 print( "Destroying Binary Search Tree\n" );

 $bst->DESTROY();

 undef( @sortedArray );
 undef( $bst );

Author

 Clint Cuffy, Virginia Commonwealth University

COPYRIGHT

Copyright (c) 2016

 Bridget T McInnes, Virginia Commonwealth University
 btmcinnes at vcu dot edu

 Clint Cuffy, Virginia Commonwealth University
 cuffyca at vcu dot edu

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to:

 The Free Software Foundation, Inc.,
 59 Temple Place - Suite 330,
 Boston, MA  02111-1307, USA.