added in docs

3 files changed, 48 insertions, 22 deletions

diff --git a/challenge-095/james-smith/perl/Stack.pm b/challenge-095/james-smith/perl/Stack.pm
index a508b88b75..ff908f0ae2 100644
--- a/challenge-095/james-smith/perl/Stack.pm
+++ b/challenge-095/james-smith/perl/Stack.pm
@@ -1,32 +1,34 @@
 package Stack;
 
-## The tree is stored in an array ref
-# The first element is the value of the node
-# The remainder of the array are child sub-trees
+## The stack is just stored as a blessed array.
 #
 # Methods:
-#  ->add_child( $child_tree )
-#  ->to_ll( $list )           -- convert tree into linked lit ( if list is
-#                                passed then they are added to the end of this list )
-#  ->flatten                  -- flatten list to array.
-#
+#  ->push( $value ) -- push value on top of stack (return stack itself)
+#  ->pop( $value )  -- take value off top of stack & return it
+#                      (if stack has no entries return undef/empty value)
+#  ->top( $value )  -- returns the value at the top of the stack
+#                      (if stack has no entries return undef/empty value)
+#  ->min( $value )  -- returns the smallest value in the stack
+#                      (if stack has no entries return undef/empty value)
+
 
 sub new {
   my $class = shift;
   my $self = [];
   bless $self, $class;
+  return $self;
 }
 
 sub push {
   my( $self,$val ) = @_;
-  push @{$self}, $val;
+  CORE::push @{$self}, $val; ## Make clear we are using the core push method
   return $self;
 }
 
 sub pop {
   my $self = shift;
   return unless @{$self};
-  return CORE::pop(@{$self});
+  return CORE::pop(@{$self}); ## Make clear we are using the core pop method
 }
 
 sub top {
diff --git a/challenge-095/james-smith/perl/ch-1.pl b/challenge-095/james-smith/perl/ch-1.pl
index c59d225a6a..921ddaec2b 100644
--- a/challenge-095/james-smith/perl/ch-1.pl
+++ b/challenge-095/james-smith/perl/ch-1.pl
@@ -6,26 +6,43 @@ use warnings;
 use feature qw(say);
 use Test::More;
 
-is( is_palindrome_rev(1221), 1 );
-is( is_palindrome_rev(-101), 0 );
-is( is_palindrome_rev(90),   0 );
+is( is_palindrome_rev(1221), 1 ); ## Even number of digits
+is( is_palindrome_rev(-101), 0 ); ## -ve number
+is( is_palindrome_rev(101),  1 ); ## Odd number of digits
+is( is_palindrome_rev(90),   0 ); ## Not-palindromic
 
 is( is_palindrome_array(1221), 1 );
 is( is_palindrome_array(-101), 0 );
+is( is_palindrome_array(101),  1 );
 is( is_palindrome_array(90),   0 );
 
 done_testing();
 
+## I will provide two solutions here...
+
+## (1) The first one just treating the two numbers as strings and
+##      using reverse
+
 sub is_palindrome_rev {
   return ( $_[0] eq reverse $_[0]) ? 1 : 0;
 }
 
+## (2) The second one just treating the two numbers as numbers and
+##     using the % operator to split them into digits.
+##     Notes:
+##      * Push is more optimal than unshift - so the digit list I get
+##        is in reverse order but that doesn't matter in this case
+##      * Obviously -ve numbers will fail so deal with this first
+##      * When the digits array has one element then we know the
+##        remaining digits form a palindrome {we can't use the
+##        shift/pop trick as it will compare digit with undef;
+
 sub is_palindrome_array {
   my $n = shift;
   return 0 if $n < 0;
   my @digits  = $n%10;
   push @digits, $n%10 while $n = int ($n/10);
-  while (@digits>1) {
+  while( @digits>1 ) {
     return 0 if shift @digits != pop @digits;
   }
   return 1;
diff --git a/challenge-095/james-smith/perl/ch-2.pl b/challenge-095/james-smith/perl/ch-2.pl
index 03b71a45d0..f953417ba7 100644
--- a/challenge-095/james-smith/perl/ch-2.pl
+++ b/challenge-095/james-smith/perl/ch-2.pl
@@ -8,14 +8,21 @@ use Test::More;
 use lib q(.);
 use Stack;
 
-my $stack = Stack->new;
-$stack->push(2);
-$stack->push(-1);
-$stack->push(0);
-$stack->pop;
-is( $stack->top , -1 );
-$stack->push(0);
-is( $stack->min, -1 );
+## Look at the Stack module for implementation
+
+#                        return value  stack after op
+my $stack = Stack->new;    # $stack    [          ]
+$stack->push(2);           # $stack    [ 2        ]
+$stack->push(-1);          # $stack    [ 2, -1    ]
+$stack->push(0);           # $stack    [ 2, -1, 0 ]
+$stack->pop;               # 0         [ 2, -1    ]
+is( $stack->top, -1 );     # -1        [ 2, -1    ]
+$stack->push(0);           # $stack    [ 2, -1, 0 ]
+is( $stack->min, -1 );     # -1        [ 2, -1, 0 ]
+$stack->pop;               # 0         [ 2, -1    ]
+$stack->pop;               # -1        [ 2        ]
+is( $stack->pop, 2 );      # 2         [          ]
+is( $stack->top, undef );  # undef     [          ]
 
 done_testing();