# $EPIC: encode,v 1.5 2001/07/16 18:57:15 jnelson Exp $
Synopsis:
   $encode(<text>)

Technical:
   * If the <text> argument is omitted the empty string is returned.
   * The output of this function is a transformation of <text> that has the
     following characteristics AND ONLY the following characteristics:
	* It is unique			encode(X) != encode(Y) for all X != Y
	* It is case sensitive:  	encode(foo) != encode(FOO)
        * It is reversable:      	decode($encode(foo)) == [foo]
        * It can be assigned to: 	@ encode(foo) = [bar]
   * This particular implementation breaks each octet in <text> into two
     four byte nybbles and adds the nybble to 0x41.  The return value is
     therefore twice the length of the input <text>.  THIS IS SUBJECT TO
     CHANGE IN THE FUTURE.
   * Hardcoding $encode()d values into your script IS A BAD THING.  Please
     be aware that $encode() may change in the future and your script will
     break and IT WON'T BE MY FAULT.

Practical:
   It is common practice to use associative arrays to store information about
   servers, channels, and nicknames.  Consider if you wanted to be able to 
   store the userhost of every user on every channel you are on.  You might
   want to organize it like:

   BAD:		/assign uh[<server>][<channel>][<nick>] <userhost>

   Unfortunately, <server>, <channel>, and <nick> might contain characters 
   that are not valid characters in a variable name.  If you tried to do it,
   you would get the error "ASSIGN names may not contain ...."  The $encode()
   function converts any arbitrary string of text into a string that can be 
   used as part of a variable name (Line broken up to improve clarity.  You
   would actually do this all on one line in a script)

   GOOD:	/assign uh[$encode(<server>)][$encode(<channel>)]\
			[$encode($<nick>)] <userhost>

   Then you can use /FOREACH to iterate over the sub-arrays:
		/assign array uh[$encode(<server>)][$encode(<channel>)]
		/foreach $array x {
			echo $array.$x
		}

Returns:
   A string that is deterministically based on <input>

Examples:
   $encode(hello there)               returns "GIGFGMGMGPCAHEGIGFHCGF"
   $decode(GIGFGMGMGPCAHEGIGFHCGF)    returns "hello there"
   $decode($encode(hello there))      returns "hello there"

History
   This function first appeared in ircII-2.2pre8.

See Also:
   assign(5); decode(6); foreach(5)

