=head1 NAME

URL::Encode - Encoding and decoding of C<application/x-www-form-urlencoded> encoding.

=head1 SYNOPSIS

    $octets = url_decode($octets);
    $string = url_decode_utf8($octets);
    $octets = url_encode($octets);
    $octets = url_encode_utf8($string);
              url_params_each($octets, $callback [, $utf8 = false]);
    $params = url_params_flat($octets [, $utf8 = false]);
    $params = url_params_mixed($octets [, $utf8 = false]);
    $params = url_params_multi($octets [, $utf8 = false]);

=head1 DESCRIPTION

This module provides functions to encode and decode strings into and from the 
C<application/x-www-form-urlencoded> encoding.

=head1 FUNCTIONS

=head2 url_decode

Decodes a urlencoded octet string.

I<Usage>

    $octets = url_decode($octets);

=head2 url_decode_utf8

Decodes a urlencoded octet string using the UTF-8 encoding scheme.

I<Usage>

    $string = url_decode_utf8($octets);

=head2 url_encode

Encodes an octet string into a urlencoded encoding.

I<Usage>

    $octets = url_encode($octets);

=head2 url_encode_utf8

Encodes a character string into a urlencoded encoding using the UTF-8 encoding
scheme.

I<Usage>

    $octets = url_encode($string);

=head2 url_params_each

Decodes a urlencoded data set invoking a callback for each name/value pair.

I<Usage>

    $callback = sub {
        my ($name, $value) = @_;
    };

    url_params_each($octets, $callback);
    url_params_each($octets, $callback, $utf8);

=head2 url_params_flat

Decodes a urlencoded data set into an C<ARRAY> reference like:

    [ "name", "value", "name", "value" ]

I<Usage>

    $array = url_params_flat($octets);
    $array = url_params_flat($octets, $utf8);

=head2 url_params_mixed

Decodes a urlencoded data set into a C<HASH> reference like:

    { name => "value", name => [ "value", "value" ] }

I<Usage>

    $hash = url_params_mixed($octets);
    $hash = url_params_mixed($octets, $utf8);

=head2 url_params_multi

Decodes a urlencoded data set into a C<HASH> reference like:

    { name => [ "value" ], name => [ "value", "value" ] }

I<Usage>

    $hash = url_params_multi($octets);
    $hash = url_params_multi($octets, $utf8);

=head1 EXPORTS

None by default. All functions can be exported using the C<:all> tag or individually.

=head1 DIAGNOSTICS

=over 4

=item B<(F)> Usage: %s

Subroutine called with wrong number of arguments.

=item B<(F)> Wide character in octet string

=item B<(F)> Malformed UTF-8 in URL-decoded octets

=back

=head1 SEE ALSO

=over 4

=item L<URL::Encode::XS>

XS implementation of C<URL::Encode>.

=item L<CGI::Deurl::XS>

=back

=head1 SUPPORT

Please report any bugs or feature requests to C<bug-url-encode@rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=URL-Encode>

=head1 AUTHOR

Christian Hansen C<chansen@cpan.org>

=head1 COPYRIGHT

Copyright 2011 by Christian Hansen.

This library is free software; you can redistribute it and/or modify 
it under the same terms as Perl itself.

