#!/usr/bin/perl

use strict;

#main is the only call executed in the body of the script, everyhing
#else is done in the main subroutine or in other subroutines
main();  



sub main {  #

    #Sum 2 numbers
    my $valueA = "3";
    my $valueB = "2";

    my $sum_of_both_vals = _sum_2_numbers($valueA,$valueB);
    print "\n====================\nThe sum of $valueA and $valueB is.... $sum_of_both_vals\n====================\n\n";

    my $numC = "0.3334";
    my $numD = "-2";
    my $sum_other_nums = _sum_2_numbers($numC,$numD);
    print "\n====================\n \'$numC + $numD equals\': $sum_other_nums\n====================\n\n\n";
    
    #Example of summing non-numbers...
    my $stringA = "Hello";
    my $stringB = "World";
    my $sum_of_strings = _sum_2_numbers($stringA,$stringB);
    print "\n====================\nWhat if we pass 2 strings to the sum subroutine? \'$stringA + $stringB\' equals \'$sum_of_strings\'\nPerl Does Not Always Behave As You'd expect!  Check Your Inputs and Outputs!\n\n====================\n\n\n";


    #Functions can accept any type of variable, and any number of variables.
    #Similarly, they can return multiple variables

    print "\n====================\nFinally, this is an example of a subroutine which accepts TWO scalars as inputs and returns two scalars as outputs.\n\n";
    my $string = "thisISaTESTstring";
    my $char_number = '4';
    
    print "   Get character at position $char_number in the string: $string\n";

    #Note-  the short hand usage of 'my' by grouping variables in () you can 
    #assign them in a batch.  The subroutine returns 2 scalars which will be 
    #assigned to these 2 variables.
    my ($q_char,$error_string) = _get_specified_char($string,"$char_number");

    #this is an if/else block, we'll discuss this next!
    if ($error_string) {
	#The error string was set, so something went wrong... print error string.
	die("ERROR: $error_string");
    } else {
	
	print "  The char at position $char_number of \'$string\' is : $q_char\n====================\n";
    }
 
}


###
#Subroutine to sum 2 numbers and return the result
##
sub _sum_2_numbers {
    my ($numA,$numB) = @_;  #the special variable @_ holds the values being passed to each method.  You can access this array like any other array.  Here I am pulling out the 2 passed in values.

    #sum the two numbers... 
    #note! no error checking is done to make sure these are two numbers!
    my $sum = $numA + $numB;

    #return is a sepcial function that sends any values it is passed back
    #to the point it was called.  These values can be captured and used in the
    #calling block.
    return($sum)
}


##
#This is a method to return the specified character from a string, or an error!
##
sub _get_specified_char {
    my($string,$char_num) = @_; #$arr is a reference to an array!

    my $length = length($string);
    print "\tThe length of \'$string\' is $length\n";

    #initialize the error string variable and the character to return variable
    my $error_msg = "";
    my $char = "";

    #we use an if/else block to make sure the string is at least as long as the
    #requested character number.. otherwise we return an error.
    if ($length < $char_num) {
	$error_msg = "Array is only $length... can't get element number $char_num from this array\n\n";
    } else {
	
	#substring takes a string, a start position, and a length from
	#that position.  it returns the string defined by start and length

	$char = substr($string,$char_num,1);

	#note! the index of substr starts at zero!  the first char is postion 0

  }

    #we return the character and error message. One will always be null
    return($char,$error_msg);
}