=head1 NAME

XML::Compile::Schema::BuiltInTypes - Define handling of built-in data-types

=head1 INHERITANCE

 XML::Compile::Schema::BuiltInTypes
   is a Exporter

=head1 SYNOPSIS

 # Not for end-users
 use XML::Compile::Schema::BuiltInTypes qw/%builtin_types/;

=head1 DESCRIPTION

Different schema specifications specify different available types,
but there is a lot over overlap.  The L<XML::Compile::Schema::Specs|XML::Compile::Schema::Specs>
module defines the availability, but here the types are implemented.

This implementation certainly does not try to be minimal in size: using
the restriction rules and inheritance structure defined in the schema
specification would be too slow.

=head1 FUNCTIONS

The functions named in this chapter are all used at compile-time
by the translator.  At that moment, they will be placed in the
kind-of opcode tree which will process the data at run-time.
You B<cannot call> these functions yourself.

=head2 Any

B<anySimpleType>

=over 4

=back

B<anyType>

=over 4

Both any*Type built-ins can contain any kind of data.  Perl decides how
to represent the passed values.

=back

=head2 Ungrouped types

B<boolean>

=over 4

Contains C<true>, C<false>, C<1> (is true), or C<0> (is false).  Unchecked,
the actual value is used.  Otherwise, C<0> and C<1> are preferred for the
hash value and C<true> and C<false> in XML.

=back

=head2 Big Integers

Schema's define integer types which are derived from the C<decimal>
type.  These values can grow enormously large, and therefore can only be
handled correctly using Math::BigInt.  When the translator is
built with the C<sloppy_integers> option, this will simplify (speed-up)
the produced code considerably: all integers then shall be between
-2G and +2G.

B<integer>

=over 4

An integer with an undertermined (but possibly large) number of
digits.

=back

B<long>

=over 4

A little bit shorter than an integer, but still up-to 19 digits.

=back

B<negativeInteger>

=over 4

=back

B<nonNegativeInteger>

=over 4

=back

B<nonPositiveInteger>

=over 4

=back

B<positiveInteger>

=over 4

=back

B<unsignedInt>

=over 4

Just too long to fit in Perl's ints.

=back

B<unsignedLong>

=over 4

Value up-to 20 digits.

=back

=head2 Integers

B<byte>

=over 4

Signed 8-bits value.

=back

B<int>

=over 4

=back

B<precissionDecimal>

=over 4

PARTIAL IMPLEMENTATION.  Special values INF and NaN not handled.

=back

B<short>

=over 4

Signed 16-bits value.

=back

B<unsigned>(Short)

=over 4

unsigned 16-bits value.

=back

B<unsignedByte>

=over 4

Unsigned 8-bits value.

=back

=head2 Floating-point

PARTIAL IMPLEMENTATION: INF, NaN not handled.  The C<float> is not limited
in size, but mapped on double.

B<decimal>

=over 4

Decimals are painful: they can be very large, much larger than Perl's
internal floats.  The value is therefore kept as string.
Use Math::BigFloat when you need calculations.  You can also pass such
object here.

=back

B<double>

=over 4

A floating-point value.

=back

B<float>

=over 4

A small floating-point value.

=back

=head2 Binary

B<base64Binary>

=over 4

In the hash, it will be kept as binary data.  In XML, it will be
base64 encoded.

=back

B<hexBinary>

=over 4

In the hash, it will be kept as binary data.  In XML, it will be
hex encoded, two hex digits per byte.

=back

=head2 Dates

B<date>

=over 4

A day, represented in localtime as C<YYYY-MM-DD> or C<YYYY-MM-DD[-+]HH:mm>.
When a decimal value is passed, it is interpreted as C<time> value in UTC,
and will be formatted as required.  When reading, the date string will
not be parsed.

=back

B<dateTime>

=over 4

A moment, represented in localtime as "date T time tz", where date is
C<YYYY-MM-DD>, time is C<HH:MM:SS> and optional, and time-zone tz
is either C<-HH:mm>, C<+HH:mm>, or C<Z> for UTC.

When a decimal value is passed, it is interpreted as C<time> value in UTC,
and will be formatted as required.  When reading, the date string will
not be parsed.

=back

B<gDay>

=over 4

Format C<---12> or C<---12+09:00> (12 days, optional time-zone)

=back

B<gMonth>

=over 4

Format C<--09> or C<--09+07:00> (9 months, optional time-zone)

=back

B<gMonthDay>

=over 4

Format C<--09-12> or C<--09-12+07:00> (9 months 12 days, optional time-zone)

=back

B<gYear>

=over 4

Format C<2006> or C<2006+07:00> (year 2006, optional time-zone)

=back

B<gYearMonth>

=over 4

Format C<2006-11> or C<2006-11+07:00> (november 2006, optional time-zone)

=back

B<time>

=over 4

An moment in time, as can happen every day.

=back

=head2 Duration

B<dayTimeDuration>

=over 4

Format C<-PnDTnHnMnS>, where optional starting C<-> means negative.
The C<P> is obligatory, and the C<T> indicates start of a time part.
All other C<n[DHMS]> are optional.

=back

B<duration>

=over 4

Format C<-PnYnMnDTnHnMnS>, where optional starting C<-> means negative.
The C<P> is obligatory, and the C<T> indicates start of a time part.
All other C<n[YMDHMS]> are optional.

=back

B<yearMonthDuration>

=over 4

Format C<-PnYnMn>, where optional starting C<-> means negative.
The C<P> is obligatory, the C<n[YM]> are optional.

=back

=head2 Strings

B<ID>(, IDREF, IDREFS)

=over 4

A label, reference to a label, or set of references.

PARTIAL IMPLEMENTATION: the validity of used characters is not checked.

=back

B<NCName>(, ENTITY, ENTITIES)

=over 4

A name which contains no colons (a non-colonized name).

=back

B<Name>

=over 4

=back

B<language>

=over 4

An RFC3066 language indicator.

=back

B<normalizedString>

=over 4

String where all sequence of white-spaces (including new-lines) are
interpreted as one blank.  Blanks at beginning and the end of the
string are ignored.

=back

B<string>

=over 4

(Usually utf8) string.

=back

B<token>(, NMTOKEN, NMTOKENS)

=over 4

=back

=head2 URI

B<NOTATION>

=over 4

NOT IMPLEMENTED, so treated as string.

=back

B<QName>

=over 4

A qualified type name: a type name with optional prefix.  The prefix notation
C<prefix:type> will be translated into the C<{$ns}type> notation.

For writers, this translation can only happen when the C<$ns> is also
in use on some other place in the message: the name-space declaration
can not be added at run-time.  In other cases, you will get a run-time
error.  Play with L<XML::Compile::Schema::compile(output_namespaces)|XML::Compile::Schema/"Compilers">,
predefining evenything what may be used, setting the C<used> count to C<1>.

=back

B<anyURI>

=over 4

You may pass a string or, for instance, an URI object which will be
stringified into an URI.  When read, the data will not automatically
be translated into an URI object: it may not be used that way.

=back

=head2 only in 1999 and 2000/10 schemas

B<binary>

=over 4

Perl strings can contain any byte, also nul-strings, so can
contain any sequence of bits.  Limited to byte length.

=back

B<timeDuration>

=over 4

'Old' name for L<duration()|XML::Compile::Schema::BuiltInTypes/"Duration">.

=back

B<uriReference>

=over 4

Probably the same rules as L<anyURI()|XML::Compile::Schema::BuiltInTypes/"URI">.

=pod how to do these constants?

$builtin_types{century}       = {                     period => 'P100Y' }
$builtin_types{recurringDate} = { duration => 'P24H', period => 'P1Y'   }
$builtin_types{recurringDay}  = { duration => 'P24H', period => 'P1M'   }
$builtin_types{timeInstant}   = { duration => 'P0Y',  period => 'P0Y'   }
$builtin_types{timePeriod}    = { duration => 'P0Y' }
$builtin_types{year}          = {                     period => 'P1Y'   }
$builtin_types{recurringDuration} = ??

=back

=head1 SEE ALSO

This module is part of XML-Compile distribution version 0.76,
built on April 13, 2008. Website: F<http://perl.overmeer.net/xml-compile/>

=head1 LICENSE

Copyrights 2006-2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

