XML::C...nTypes(3pm)

💖 NAME 💖

okay so bestie, this whole page is about XML::Compile::Schema::BuiltInTypes (you'll see it up top as XML::C...nTypes(3pm) because man pages love to truncate things 💀) — it's the module that defines handling of built-in data-types. ✨

---

🧬 INHERITANCE 🧬

the family tree is tiny, she's an exporter and that's the whole vibe:

XML::Compile::Schema::BuiltInTypes
  is an Exporter

---

✨ SYNOPSIS ✨

bestie this is literally not for end-users, okay? read the comment, she's telling you 🫶

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

---

🌸 DESCRIPTION 🌸

so different schema specs come with different available types, but there is a lot of overlap between them. the module that decides availability is XML::Compile::Schema::Specs, but this is where the types actually get implemented. 💅

and ngl, this implementation is not trying to be minimal in size. if it followed the letter of the restriction rules and the inheritance structure that the W3C schema specification defines, it would be way too slow. so it just… doesn't. iconic behaviour honestly. 👑

---

🔥 FUNCTIONS 🔥

🍓 Real functions

• builtin_type_info($type) — returns the configuration for $type, which is a HASH. ⚠️ and listen, the info inside that HASH will change over time without too much notice. so if you use it, please implement regression-tests on it. that's not a suggestion bestie, that's a warning. 😭

🦋 The Types

every single function named in this section is used at compile-time by the translator. at that moment they get placed into the kind-of opcode tree that will process the data at run-time. so like, you cannot call these functions yourself. periodt. 🙅‍♀️

also, XML::Compile will automatically format the value for you. for instance, a float supplied to a field defined as type Integer gets converted to an integer. data supplied to a field of type base64Binary gets encoded as Base64 for you: you shouldn't do the conversion yourself, you'll get double encoding! 💀

🌈 Any

• anyAtomicType(), anySimpleType(), anyType() — both any*Type built-ins can contain any kind of data. Perl decides how to represent the passed values. main character energy, she contains multitudes. 💫
• error() — (the original doesn't give her a description, she's just listed, and honestly? respect. 🙈)

🎀 Ungrouped types

• boolean() — contains "true", "false", 1 (is true), or 0 (is false). when the writer sees a value equal to 'true' or 'false', those are used. otherwise, the trueth value is evaluated into '0' or '1'.

the reader will return '0' (also when the XML contains the string 'false', to simplify the Perl code) or '1'. ✨

• pattern() — (again, no description in the original. she's mysterious. 🕵️‍♀️)

🧮 Big Integers

schema's define integer types which are derived from the decimal type. these values can grow enormously large, so they can only be handled correctly using Math::BigInt. 💪

when the translator is built with the sloppy_integers option, this will simplify (speed-up) the produced code considerably: all integers then shall be between -2G and +2G. trade-offs, bestie.

• integer() — an integer with an undertermined (but possibly large) number of digits.
• long() — a little bit shorter than an integer, but still up-to 19 digits.
• negativeInteger(), nonNegativeInteger(), nonPositiveInteger(), positiveInteger() — (listed together, no separate descriptions, they're the squad 💜)
• unsignedInt() — just too long to fit in Perl's ints.
• unsignedLong() — value up-to 20 digits.

🔢 Integers

• byte() — signed 8-bits value.
• int(), short() — signed 16-bits value.
• unsignedByte() — unsigned 8-bits value.
• unsignedShort() — unsigned 16-bits value.

🫧 Floating-point

• decimal() — decimals are painful: they can be very large, much larger than Perl's internal floats. so we need Math::BigFloat, which are slow but nearly seamlessly invisible in the application. she's slow but you'll barely notice her. 🧚
• double() — a floating-point value m x 2**e, where m is an integer whose absolute value is less than 253, and e is an integer between −1074 and 971, inclusive.

the implementation does not limited the double in size, but maps it onto an precisionDecimal (Math::BigFloat) unless sloppy_float is set.

• float() — a small floating-point value m x 2**e where m is an integer whose absolute value is less than 224, and e is an integer between −149 and 104, inclusive.

the implementation does not limited the float in size, but maps it onto an precisionDecimal (Math::BigFloat) unless sloppy_float is set.

• precisionDecimal() — floating point value that closely corresponds to the floating-point decimal datatypes described by IEEE/ANSI-754. ⭐

🔐 Encoding

• base64Binary() — in the hash, it will be kept as binary data. in XML, it will be base64 encoded.
• hexBinary() — in the hash, it will be kept as binary data. in XML, it will be hex encoded, two hex digits per byte.

📅 Dates

• date() — a day, represented in localtime as "YYYY-MM-DD" or "YYYY-MM-DD[-+]HH:mm". when a decimal value is passed, it is interpreted as "time" value in UTC, and will be formatted as required. when reading, the date string will not be parsed.
• dateTime() — a moment, represented as "date T time tz?", where date is "YYYY-MM-DD", time is "HH:MM:SS", and the time-zone tz is either "-HH:mm", "+HH:mm", or "Z" for UTC. the time-zone is optional, but can better be used because the default is not defined in the standard. for that reason, the "dateTimeStamp" got introduced, which requires the timezone.

when a decimal value is passed, it is interpreted as "time" value in UTC, and will be formatted as required. this will not work when the dateTime extended type has facet explicitTimeZome="prohibited".

when reading, the date string will not be parsed. parsing timestamps is quite expensive, therefore not preformed automatically. you may try Time::Local in combination with Date::Parse, or Time::Piece::ISO. ⚠️ be very careful with the timezone settings in your program, which effects mktime which is used by these implementations. best to run your application in GMT/UTC/UCT/Z. no cap.

• dateTimeStamp() — like "dateTime", but with required timezone which means that it is better defined. all other handling is the same. 💅
• gDay() — format "---12" or "---12+09:00" (12 days, optional time-zone)
• gMonth() — format "--09" or "--09+07:00" (9 months, optional time-zone)
• gMonthDay() — format "--09-12" or "--09-12+07:00" (9 months 12 days, optional time-zone)
• gYear() — format 2006 or "2006+07:00" (year 2006, optional time-zone)
• gYearMonth() — format "2006-11" or "2006-11+07:00" (november 2006, optional time-zone)
• time() — an moment in time, as can happen every day. 🕰️

⏳ Duration

see XML::Compile::Util::duration2secs() to convert duration stamps into seconds. iykyk.

• dayTimeDuration() — format "-PnDTnHnMnS", where optional starting "-" means negative. the "P" is obligatory, and the "T" indicates start of a time part. all other "n[DHMS]" are optional.
• duration() — format "-PnYnMnDTnHnMnS", where optional starting "-" means negative. the "P" is obligatory, and the "T" indicates start of a time part. all other "n[YMDHMS]" are optional.
• yearMonthDuration() — format "-PnYnMn", where optional starting "-" means negative. the "P" is obligatory, the "n[YM]" are optional.

🧵 Strings

• ID(, IDREF, IDREFS) — a label, reference to a label, or set of references.

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

• NCName(, ENTITY, ENTITIES) — a name which contains no colons (a non-colonized name).
• Name(), language() — an RFC3066 language indicator.
• normalizedString() — 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. so tidy ✨
• string() — (usually utf8) string.
• token(, NMTOKEN, NMTOKENS) — (listed with no description, she's just vibing 🫧)

🔗 URI

• NOTATION() — NOT IMPLEMENTED, so treated as string. it's giving "we'll deal with it later" 💀
• QName() — a qualified type name: a type name with optional prefix. the prefix notation "prefix:type" will be translated into the "{$ns}type" notation.

for writers, this translation can only happen when the $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 XML::Compile::Schema::compile(prefixes), predefining evenything what may be used, setting the "used" count to 1.

• anyURI() — 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.

🕰️ only in 1999 and 2000/10 schemas

• binary() — Perl strings can contain any byte, also nul-strings, so can contain any sequence of bits. limited to byte length.
• timeDuration() — 'Old' name for duration(). throwback era 🎀
• uriReference() — probably the same rules as anyURI().

---

👀 SEE ALSO 👀

this module is part of the XML-Compile distribution, version 1.64, built on October 21, 2024. website: http://perl.overmeer.net/xml-compile/ 🦋

---

📜 LICENSE 📜

copyrights 2006-2024 by [Mark Overmeer <markov@cpan.org>]. 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 http://dev.perl.org/licenses/

---

and that's the whole page bestie!! 💖 this was rendered by perl v5.40.0 on 2024-10-27, so if you ever see the footer XML::C...nTypes(3pm) again you'll know exactly whose group chat you walked into. slay, go compile something. ✨👑