NAME

Liz::Calc - Elizabeth Mattijsen's general calculation subroutines


SYNOPSIS

 use Liz::Calc


RandomList

Return the list specified as parameters in a random order. Or randomize a list of which the reference is passed in place. Can be called as a method. Based on the Fisher Yates shuffle (Perl Cookbook).

Input Parameters

 1..N list to be permutated

or:

 1    reference to list to be permutated in place
Output Parameters

 1..N permutated list

or:

 (none) if reference to list was passed
Example

 @list = Liz::Calc::RandomList( 1..5 );


RandomString

Return a random string with the specified root and length. Can be called as a method.

Input Parameters

 1 root of the random string
   (default: none)
 2 length of random part of the string
   (default: 7 characters)
Output Parameters

 1 random string


Encrypt

This function takes a string and a key and transforms it into a mime-encoded string which contain the encrypted version of the string. The encryption method used a a form of a self modifying one time pad with a random seed. Please note that this is not a very strong encryption method, if you require information to be stored very secure, a stronger method such as PGP or IDEA is recommended.

Can be called either as a method or as a subroutine. Use subroutine/method Decrypt to decrypt a string.

Input Parameters

  1 string to be encrypted
  2 key 
Output Parameters

  1 the mime-encoded encrypted string
Example

  $plain = "Ik ben een string";
  print "Original : $plain\n";
  $cipher = Liz::Calc::Encrypt($plain,"Ronald");
  print "Encrypted: $cipher\n";
  $newplain = Liz::Calc::Decrypt($cipher,"Ronald");
  print "Decrypted: $newplain\n\n";
Example

  print "\nTime encryption 10000 times of 'Ik ben een string'\n";
  timethis(10000,'Liz::Calc::Encrypt("Ik ben een string","Ronald")');


Decrypt

This function takes a mime-encoded string and a key. If no key is provided the function will return without doing anything. It converts the string into the original string again.

Can be called either as a method or as a subroutine. Use subroutine/method Encrypt to encrypt a string.

Input Parameters

  1 string to be decrypted
  2 key
Output Parameters

  1 the decrypted string
Example

  $plain = "Ik ben een string";
  print "Original : $plain\n";
  $cipher = Liz::Calc::Encrypt($plain,"Ronald");
  print "Encrypted: $cipher\n";
  $newplain = Liz::Calc::Decrypt($cipher,"Ronald");
  print "Decrypted: $newplain\n\n";
Example

  print "\nTime decryption 10000 times of 'Ik ben een string'\n";
  timethis(10000,'Liz::Calc::Decrypt("1e04105f5258592d22021f727a7133673e54","Ronald")');


Hash

Return a hash key for the specified string. Can also be called as a method.

Input Parameters

 1 string for which to create a hash
Output Parameters

 1 4-byte integer hash code
Example

 $string = 'This is a string';
 $hash = Liz::Calc::Hash( $string );
 print "The hash of '$string' is '$hash'\n";


Intel

Return a flag indicating whether we're running on an Intel-based byte ordering architecture. Can also be called as a method.

Output Parameters

 1 flag: true if on Intel architecture (low-high)
Example

 print "This is on an Intel machine\n" if Intel();


ISO2Country

Convert an ISO code to a country name.

Input Parameters

 1 ISO code
Output Parameters

 1 Country name
Example

 $country = Liz::Calc::ISO2Country( 'nl' );


Hex2RGB

Convert a six-character hexadecimal colour code into a list of three values, for red, green and blue respectively. It performs the opposite function to RGB2Hex.

Input Parameters

 1 6-character hexadecimal code
Output Parameters

 1 amount of red (0..255)
 2 amount of green (0..255)
 3 amount of blue (0..255)


List2Hash

Convert the values of an array to a hash table in which the value of the array element is the key and the ordinal number in the array is the value.

Input Parameters

 1..N first element of array
Output Parameters

 1 hash-table or reference to hash table
Note

This routine currently starts by setting the first hash-table value to 1. It should probably be set to 0 or be settable in some other manner.


ListsAll2List

Change two or more lists into a list in which every element occurs in all of the original lists.

Input Parameters

 1..N references to lists of which to return elements that occur in all
Output Parameters

 1..N list with elements that occur in all lists
Example

 @ID = Liz::Calc::ListsAll2List( \@ID1,\@ID2 );


ListsAny2List

Change two or more lists into a list in which every element occurs in any of the original lists. Each element in the resulting list will only occur once.

Input Parameters

 1..N references to lists of which to return elements that occur in any
Output Parameters

 1..N list with elements that occur in at least one of the lists
Example

 @ID = Liz::Calc::ListsAny2List( \@ID1,\@ID2 );


ListsNot2List

Change two lists into a list in which every element does not occur in both original lists.

Input Parameters

 1    reference to first list
 2    reference to second list
 3    flag: only return elements that are in the first list
Output Parameters

 1..N list with elements that do not occur in both lists
Example

 @ID = Liz::Calc::ListsNot2List( \@ID1,\@ID2 );


ListsSame

Return a flag whether the lists specified are the same or not. Optionally allows checking whether all elements occur in the same order or not.

Input Parameters

 1 reference to first list
 2 reference to second list
 3 flag: allow elements to be out of order
Output Parameters

 1 flag: 1 = same, 0 = not
Example

 $same = Liz::Calc::ListsSame( [1,2,3],[4,5,6] );


NOverM

Return a list of references to lists that consist of N-tuplets out of the list of M-tuplets specified. So, suppose you have a list (1,2,3,4) (M=4) and you would like to get all possible triplets (N=3), then this routine would return the following:

 ([1,2,3],[1,2,4],[1,3,4],[2,3,4]) = NOverM( 3,[1,2,3,4] );

So, all possible unique combinations of 1, 2, 3 and 4 are returned as references to lists.

Input Parameters

 1    N - the size of N-tuplets
 2    reference to list out of which to select (M elements) 
Output Parameters

 1..X the N-tuplets that are combinations out of the original list
Example

 foreach( Liz::Calc::NOverM( 3,[1,2,3,4] ) ) {
   print join(',',@{$_})."\n";
 }


Packets

Return an approximate number of TCP/IP-packets that the specified number of bytes, will cause. This is mainly used for debugging output only. Can be called both as a method and as a subroutine.

Input Parameters

 1 number of bytes
Output Parameters

 1 number of TCP/IP packets
Example

 $packets = Liz::Packets( length($string) );
 $r->print( $string );
 warn "This caused at least $packets TCP/IP packets\n";
Note

Calculation is based on maximum number of data bytes in a TCP/IP packet being 1460.


RGB2Hex

Convert a list for three values, for red, green and blue respectively, into a six-character hexadecimal colour code. It performs the opposite function to Hex2RGB.

Input Parameters

 1 amount of red (0..255)
 2 amount of green (0..255)
 3 amount of blue (0..255)
Output Parameters

 1 6-character hexadecimal code


URLEncode

Encode a string so that it can be used as part of a GET operation. Opposite action to URLDecode.

Input Parameters

 1 string to be URLEncoded
Output Parameters

 1 URLEncoded string


URLDecode

Decode a string so that was part of a GET operation. Opposite action to URLEncode.

Input Parameters

 1 URLEncoded string to be URLDecoded
Output Parameters

 1 normal string


HTMLEncode

Encode a string so that all extended ASCII characters are HTML entity encoded. Opposite action to HTMLDecode.

Input Parameters

 1 string to be HTMLEncoded
Output Parameters

 1 HTMLEncoded string


HTMLDecode

Decode a string so that all HTML entity encoded characters are changed to extended ASCII characters. Opposite action to HTMLEncode.

Input Parameters

 1 string to be HTMLDecoded
Output Parameters

 1 HTMLDecoded string


GET

Obtain the HTML of another URL and return this as a long string from which regular expressions can be used to obtain certain types of information. Can either be called as an inherited method, or directly as a subroutine.

Input Parameters

 1 URL of which to obtain the HTML
Output Parameters

 1 HTML found at the URL, or undef if error
Examples

 $homepage = $self->GET( 'www.xxLINK.nl' );

 use Liz::Calc;
 $cnn = GET( 'http://cnn.com' );


HEAD

Check if a given URL exists and return a list of meta-information of the URL.

Input Parameters

 1    URL to check up on
 2    (internal flag: perform GET instead of HEAD)
Output Parameters

 1..N meta-information of the URL
Examples

 if( $self->HEAD( 'www.xxLINK.nl' ) ) {
   print "xxLINK is alive!\n"
 }
 print "CNN is dead\n" unless Liz::Calc::HEAD( 'http://cnn.com' );


Host2IP

Moved to the Liz.pm module. Please use Liz::Host2IP instead.


IP2Host

Moved to the Liz.pm module. Please use Liz::IP2Host instead.


SizeImage

Adapt the width and the height of an image to be within the specified boundaries, while attempting to preserve the same width:height ratio.

Input Parameters

 1 width of image
 2 height of image
 3 maximum width of image
 4 maximum height of image
Output Parameters

 1 constrained width of image
 2 constrained height of image


GetImageDimensions

Return the dimensions of a given (gif/jpeg) image file.

Input Parameters

 1 path/filename 
Output Parameters

 1 width
 2 height
Note

Returns undef if the image does not exist


YearWeek2UnixTime

Convert a year and a week number to the Unix time of the Monday of that week.

Input Parameters

 1 Year (1999..2005)
 2 Week number (1..53)
   (default: 1)
 3 Number of days offset (e.g. 1 = Tuesday, -3 = Friday before)
   (default: 0)
Output Parameters

 1 UnixTime value of the indicated day at midnight GMT
Example

 $time = Liz::Calc::YearWeek2UnixTime( 1999,3 );
 print POSIX::ctime( $time )."\n";


CreditCardIssuer

Convert a credit card number to a string of the issuer. Return undefined if the issuer could not be determined. The following strings can now be expected:

 eurocard          Eurocard/Mastercard
 visa              VISA
 diners            Diners Club
 amex              American Express
 jcb               JCB

Can be called both as a method as well as a subroutine. See CreditCardValidate to validate a credit card number.

Input Parameters

 1 Credit card number
Output Parameters

 1 string for the issuer
   (undef if not able to determine)
Example

 if ($issuer = Liz::Calc::CreditCardIssuer( $card )) {
   print "The issuer of credit card $card is $issuer.\n";
 }


CreditCardValidate

Process a given credit card number and return a normalised number. Returns undef if the checksum test did not succeed.

Adapted from code written by Jon Orwant ( orwant@tpj.com ), The Perl Journal and MIT Media Lab.

Can be called both as a method and as a subroutine.

Input Parameters

 1 credit card number
Output Parameters

 1 normalised credit card number
   (undef if not valid)
Example

  $card = '5276 4400 6542 1319';
  if ($valid = Liz::Calc::CreditCardValidate( $card )) {
    $issuer = Liz::Calc::CreditCardIssuer( $card ) || 'but unknown';
    print "$valid is a valid $issuer credit card\n";
  } else {
    print "$card is not a valid credit card number\n";
  }


AUTHOR

Elizabeth Mattijsen ( lizperl@INC.nl )

plus contributions by:

 Sjoerd Lawende ( sjoerd@xxLINK.nl )

 Ronald Lens ( ronald@xxLINK.nl )


COPYRIGHT

(C) 1996-2000 International Network Consultants


HISTORY

Version 0.68, 15 June 2000

Fixed subroutine/method RandomList so that it returns unpredictable lists instead of the same under ModPerl. Removed the dependency on Math::Random, which should save a lot in the memory footprint. Now also allows passing the reference of a list for in place randomizing.

Version 0.67, 24 April 2000

Added '-' and '/' as possible separators in check in CreditCardIssuer. (Sjoerd).

Added method/subroutine CreditCardIssuer to determine the issuer of a credit card from a given credit card number.

Added method/subroutine CreditCardValidate to determine whether a credit card number is valid or not.

Version 0.66, 31 March 2000

Method GetImageDimensions now uses the binaries stored in the same directory as the module itself instead of at an arbitrary location.

Version 0.65, 27 August 1999

Removed srand() from source altogether: is not needed with newer Perl's anyway, and it was causing repeatable sequences in the ModPerl environment.

Version 0.64, 25 August 1999

Moved srand() to initialization section.

Simple Encrypt and Decrypt functions added: courtesy of Ronald Lens.

Changed RandomString to use allowable characters that are defined at require time of the module.

Changed to new source typography.

Version 0.63, 27 July 1999

Added new subroutine/method ISO2Country for translating ISO codes to country names.

Version 0.62, 10 April 1999

Added new method/subroutine Packets for calculating number of packets for a specific number of bytes.

Version 0.61, 6 April 1999

Added new method/subroutine Hash for creating a hash-key (4 byte integer) for a string.

Version 0.60, 31 March 1999

Moved subroutines Host2IP and IP2Host to the Liz.pm module.

Version 0.59, 12 March 1999

Updated all m// and s/// operators to include the ``o'' flag when appropriate.

Version 0.58, 23 February 1999

New subroutine/method RandomList: returns a list in a random order.

Version 0.57, 10 January 1999

New subroutine/method ListsSame added: returns true if two lists are the same.

Version 0.56, 5 January 1999

New subroutine/method YearWeek2UnixTime added: convert a year and a week number to the unix time of the Monday in that week.

Version 0.55, 4 January 1999

New subroutine/method Intel added: returns true when running under Intel (low-high) architecture.

Version 0.54, 1 January 1999

Method GetImageDimensions now uses external C-program to measure size.

Version 0.53, 28 December 1998

Moved method GetImageDimensions here from the Liz::Perl module.

Version 0.52, 18 November 1998

Subroutine IP2Host now always returns the name of the remote host, even in a list context.

Version 0.51, 6 October 1998

Reduced memory footprint by fully qualifying global variables and external subroutines.

Version 0.5, 16 September 1998

New subroutine NOverM added: returns selection of all N-tuplets out of a collection of M members.

Version 0.4, 6 September 1998

New method/subroutine ListsAll2List added: return list of elements that occur in all lists specified.

New method/subroutine ListsAny2List added: return list of elements that occur in at least one of the lists specified.

New method/subroutine ListsNot2List added: return list of elements that do not occur in both lists specified.

Version 0.34, 26 July 1998

New subroutine SizeImage added: constrain the width and height of an image between given parameters.

Version 0.33, 25 July 1998

Subroutines HTMLEncode and HTMLDecode added. Convert between extended ASCII characters and HTML entities.

Version 0.32, 22 July 1998

Subroutines Host2IP and IP2Host added. Convert between hostname and IP-number (when DNS allows, of course).

Version 0.31, 15 July 1998

Subroutine RGB2Hex added: convert from three integer values into a hexadecimal colour code.

Version 0.3, 13 July 1998

Subroutine Hex2RGB added: convert from hexadecimal colour codes to three integer values.

Version 0.2, 27 May 1998

Subroutine GET moved here from the Liz::Perl module. Allows obtaining the information of any URL on the Internet with the GET method.

New subroutine HEAD created. Allows simple checking whether an URL currently exists on the Internet.

New subroutines URLEncode and URLDecode: allow for URL encoding and URL decoding of strings that are part of a GET operation.

Version 0.1, 17 May 1998

First version of this true Perl module, based on routines developed for the LizPerl library.