#############
VariableCheck
#############


****
NAME
****


Kernel::System::VariableCheck - helper functions to check variables


***********
DESCRIPTION
***********


Provides several helper functions to check variables, e.g.
if a variable is a string, a hash ref etc. This is helpful for
input data validation, for example.

Call this module directly without instantiating:


.. code-block:: perl

     use Kernel::System::VariableCheck qw(:all);             # export all functions into the calling package
     use Kernel::System::VariableCheck qw(IsHashRefWitData); # export just one function
 
     if (IsHashRefWithData($HashRef)) {
         # ...
     }


The functions can be grouped as follows:

Variable type checks
====================



* `IsString()`_



* `IsStringWithData()`_



* `IsArrayRefWithData()`_



* `IsHashRefWithData()`_




Number checks
=============



* `IsNumber()`_



* `IsInteger()`_



* `IsPositiveInteger()`_




Special data format checks
==========================



* `IsIPv4Address()`_



* `IsIPv6Address()`_



* `IsMD5Sum()`_





****************
PUBLIC INTERFACE
****************


IsString()
==========


test supplied data to determine if it is a string - an empty string is valid

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsString(
         'abc', # data to be tested
     );



IsStringWithData()
==================


test supplied data to determine if it is a non zero-length string

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsStringWithData(
         'abc', # data to be tested
     );



IsArrayRefWithData()
====================


test supplied data to determine if it is an array reference and contains at least one key

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsArrayRefWithData(
         [ # data to be tested
             'key',
             # ...
         ],
     );



IsHashRefWithData()
===================


test supplied data to determine if it is a hash reference and contains at least one key/value pair

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsHashRefWithData(
         { # data to be tested
             'key' => 'value',
             # ...
         },
     );



IsNumber()
==========


test supplied data to determine if it is a number
(integer, floating point, possible exponent, positive or negative)

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsNumber(
         999, # data to be tested
     );



IsInteger()
===========


test supplied data to determine if it is an integer (only digits, positive or negative)

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsInteger(
         999, # data to be tested
     );



IsPositiveInteger()
===================


test supplied data to determine if it is a positive integer (only digits and positive)

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsPositiveInteger(
         999, # data to be tested
     );



IsIPv4Address()
===============


test supplied data to determine if it is a valid IPv4 address (syntax check only)

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsIPv4Address(
         '192.168.0.1', # data to be tested
     );



IsIPv6Address()
===============


test supplied data to determine if it is a valid IPv6 address (syntax check only)
shorthand notation and mixed IPv6/IPv4 notation allowed
# FIXME IPv6/IPv4 notation currently not supported

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsIPv6Address(
         '0000:1111:2222:3333:4444:5555:6666:7777', # data to be tested
     );



IsMD5Sum()
==========


test supplied data to determine if it is an \ ``MD5``\  sum (32 hex characters)

returns 1 if data matches criteria or undef otherwise


.. code-block:: perl

     my $Result = IsMD5Sum(
         '6f1ed002ab5595859014ebf0951522d9', # data to be tested
     );



DataIsDifferent()
=================


compares two data structures with each other. Returns 1 if
they are different, undef otherwise.

Data parameters need to be passed by reference and can be SCALAR,
ARRAY or HASH.


.. code-block:: perl

     my $DataIsDifferent = DataIsDifferent(
         Data1 => \$Data1,
         Data2 => \$Data2,
     );