#----------------------------------------------------------------------------
#this is subroutines of string process.
#usage:
#      in your perl file when you want use the following functions, insert
#      ther following string:
#                           require string_misc;
#note:
#     the string "require string_misc;" only be included once in a file.
#----------------------------------------------------------------------------

sub strToRegEx()
{
    my $refStr = shift;
    my ($length, $i, $char, $pos);

    return if (ref($refStr) ne "SCALAR");

    $length = length($$refStr);
    $i = 0;
    $pos = 0;

    while ($i++ < $length) {
        $char = substr($$refStr, $pos, 1);
        if ("\\" eq $char) {
            substr($$refStr, $pos, 1) = "\\\\";
        }
        elsif ("\/" eq $char) {
            substr($$refStr, $pos, 1) = "\\\/";
        }
        elsif ("\^" eq $char) {
            substr($$refStr, $pos, 1) = "\\\^";
        }
        elsif ("\$" eq $char) {
            substr($$refStr, $pos, 1) = "\\\$";
        }
        elsif ("\." eq $char) {
            substr($$refStr, $pos, 1) = "\\\.";
        }
        elsif ("\*" eq $char) {
            substr($$refStr, $pos, 1) = "\\\*";
        }
        elsif ("\?" eq $char) {
            substr($$refStr, $pos, 1) = "\\\?";
        }
        elsif ("\+" eq $char) {
            substr($$refStr, $pos, 1) = "\\\+";
        }
        elsif ("\(" eq $char) {
            substr($$refStr, $pos, 1) = "\\\(";
        }
        elsif ("\)" eq $char) {
            substr($$refStr, $pos, 1) = "\\\)";
        }
        elsif ("\[" eq $char) {
            substr($$refStr, $pos, 1) = "\\\[";
        }
        elsif ("\]" eq $char) {
            substr($$refStr, $pos, 1) = "\\\]";
        }
        elsif ("\{" eq $char) {
            substr($$refStr, $pos, 1) = "\\\{";
        }
        elsif ("\}" eq $char) {
            substr($$refStr, $pos, 1) = "\\\}";
        }
        ++$pos;
    }
}


# "abc" --> "abc -----------------------------------------------------"
#param0
#    [in]: source line to be padded (a reference scalar).
#param1
#    [in]: padding character.
#param2
#    [in]: pad position. 0-front, 1-middle, 2-rear.
#return
#    the whole padded line.
sub paddingLine
{
    my ($str, $c, $pos) = @_;

    return 0 if (ref($str) ne "SCALAR");

   if ($$str) {
        my $pad = 78 - length $$str;
        if (0 < $pad) {
            $pos = 2 if (!defined $pos);

            if (0 == $pos) {
                $$str = $c x $pad . $$str;
            }
            elsif (1 == $pos) {
                my $halfLength = $pad / 2;
                $$str = $c x $halfLength . $$str . $c x $halfLength;
                $$str .= $c if (78 > length $$str);
            }
            else {
                $$str .= $c x $pad;
            }
        }
    }
}

# "\"  --->  "/"
#
#param
#   - [in]: a referenced string.
sub convetSlash
{
    my $refStr = shift;
    $$refStr =~ s/\\/\//g;
}

# erase the white space characters tailing the string.
#
#param
#   - [in]: a referenced string.
sub pruneTailingSpace()
{
    my $lineStrRef = shift;

    if ($$lineStrRef =~ m:^(.*\S)\s+$:) {
        $$lineStrRef = "$1\n" if ($1);
    }
}

# convert the table character[\t] into four space characters.
# "\t" --> "- - - -"
#
#param
#   - [in]: a referenced string.
sub tabTo4Space()
{
    my $lineStrRef = shift;

    $$lineStrRef =~ s/\t/    /g;
}

# [\] --> [\\] or [$] --> [\$] or [*] --> [\*] or [']-->[\'] or ["] --> [\"]
sub escapeToRegualar()
{
    my ($line) = @_;
    my ($ret, $pos);

    return '' unless $line;

    $ret = '';
    while ($line =~ m/\\/g) {
        $pos = pos($line);
        $ret .= substr($line, 0, $pos - 1);
        $ret .= "\\\\";
        $line = substr($line, $pos);
    }

    $line = $ret . $line;

    $ret = '';
    while ($line =~ m/\*/g) {
        $pos = pos($line);
        $ret .= substr($line, 0, $pos - 1);
        $ret .= '\*';
        $line = substr($line, $pos);
    }

    $line = $ret . $line;

    $ret = '';
    while ($line =~ m/\$/g) {
        $pos = pos($line);
        $ret .= substr($line, 0, $pos - 1);
        $ret .= '\$';
        $line = substr($line, $pos);
    }

    $line = $ret . $line;

    $ret = '';
    while ($line =~ m/\'/g) {
        $pos = pos($line);
        $ret .= substr($line, 0, $pos - 1);
        $ret .= '\'';
        $line = substr($line, $pos);
    }

    $line = $ret . $line;

    $ret = '';
    while ($line =~ m/\"/g) {
        $pos = pos($line);
        $ret .= substr($line, 0, $pos - 1);
        $ret .= '\"';
        $line = substr($line, $pos);
    }

    $line = $ret . $line;

    return $line;
}

# insert string "addin" into a $line BEFORE every specified substring.
# param0
#    - [in|out]: a reference string $line. Mostly this $line string
#            would be changed.
# param1
#    - [in]: the substring in the $line before which a specified string
#            will be inserted into.
# param2
#    - [in]: string to be inserted.
sub insertBeforeSubStr()
{
    my ($line, $subStr, $addinStr) = @_;
    my ($escapeSubStr, $temp, $pos, $subStrLength);

    return 0 if (!$line or !$addinStr  or !subStr);

    if (ref($line) ne 'SCALAR') {
        warn "the first param should be a SCALAR reference\n";
        return 0;
    }

    $subStrLength = length($subStr);
    $escapeSubStr = &escapeToRegualar($subStr);
    $temp = '';
    while ($$line =~ m/$escapeSubStr/g) {
        $pos = pos($$line);
        $temp .= substr($$line, 0, $pos - $subStrLength);
        $temp .= $addinStr;
        $temp .= substr($$line, $pos - $subStrLength, $subStrLength);
        $$line = substr($$line, $pos);
    }

    $$line = $temp . $$line;

    return $$line;
}

# insert string "addin" into a $line AFTER every specified substring.
# param0
#    - [in|out]: a reference string $line. Mostly this $line string
#            would be changed.
# param1
#    - [in]: the substring in the $line after which a specified string
#            will be inserted into.
# param2
#    - [in]: string to be inserted.
sub insertAfterSubStr()
{
    my ($line, $subStr, $addinStr) = @_;
    my ($escapeSubStr, $temp, $pos, $subStrLength);

    return 0 if (!$line or !$addinStr  or !subStr);

    if (ref($line) ne 'SCALAR') {
        warn "the first param should be a SCALAR reference\n";
        return 0;
    }

    $subStrLength = length($subStr);
    $escapeSubStr = &escapeToRegualar($subStr);
    $temp = '';
    while ($$line =~ m/$escapeSubStr/g) {
        $pos = pos($$line);
        $temp .= substr($$line, 0, $pos);
        $temp .= $addinStr;
        $$line = substr($$line, $pos);
    }

    $$line = $temp . $$line;

    return $$line;
}

sub isStringQuoted()
{
    my ($line, $specStr) = @_;
    my ($foreSubStr, $rearSubStr, $openQuoted, $temp, $pos);

    #if no $line or no $specStr return 0.
    return 0 if (!$line || !$specStr);

    $temp = length($specStr);
    $specStr = &escapeToRegualar($specStr);

    #return 0 if $line contains no $specStr.
    if ($line =~ /$specStr/g) {
        #why use /g midifier? 'Cause to loacte the specStr with pos().
        $pos = pos($line);
        $foreSubStr = substr($line, 0, $pos - $temp);
    }
    return 0 if (!$foreSubStr);

    $openQuoted = 0;
    while ($foreSubStr =~ m:\":g) {
        $openQuoted = !$openQuoted;
    }

    if ($openQuoted) {
        $rearSubStr = substr($line, $pos);
        $temp = 0;
        $temp = pos($rearSubStr) if ($rearSubStr =~ m:\":g);