minted library

Well-modelled value types (domain primitives) for entities usually left as a raw String: email, IBAN, and more.

Every type is built on "parse, don't validate": build it through parse (returns a ParseOutcome, the value or a typed failure) or tryParse (returns null), never a public constructor, so any instance that exists is guaranteed well-formed. No door throws; getOrThrow on an outcome is the caller opting in.

Classes

BicFailure
Why a Bic refused its input. Sealed, not an enum, because BicWrongLength and BicUnknownCountry report values read from the input.
BicInvalidCharacters
Something outside A-Z and 0-9 survived normalisation (whitespace is stripped first).
BicUnknownCountry
countryCode is not an ISO 3166-1 alpha-2 code, so positions 5 and 6 are mistyped. Digits landing there arrive here too, since they cannot name a country either.
BicWrongLength
Neither eight nor eleven characters survived normalisation, so this is a BIC of neither length.
Cidr
A CIDR block: a network address and how many leading bits of it the prefix covers, written 10.0.0.0/8 or 2001:db8::/32. Standards: RFC 4632 for v4, RFC 4291 §2.3 for v6.
CidrFailure
Why a Cidr refused its input. Sealed, not an enum, because three variants carry what failed, one of them another type's failure.
CidrHostBitsSet
Bits are set below the prefix, so this names a host rather than a network. networkAddress is the block the caller most likely meant.
CidrInvalidAddress
The part before the / is not an IpAddress, and reason says why.
CidrMalformed
The text is not an address followed by / and a decimal prefix length.
CidrPrefixLengthOutOfRange
The prefix length is a number, but not one this family has bits for.
Date
A calendar date: a year, month, and day, with no time-of-day and no time zone.
DateComponentFailure
Why one of a date's parts was refused: the subset Date.of can report, where the shape is not in question. Lets a caller assembling from parts switch without an arm for DateNotIso8601.
DateDayOutOfRange
The day falls outside 1-maxDay. The bound is leap-year aware, so 29 February is out of range in a common year and in range in a leap one.
DateFailure
Why a Date refused its input. Sealed, not an enum, because the variants report the offending number back. Two remedies: DateNotIso8601 means fix the format, the rest mean fix a number.
DateMonthOutOfRange
The month falls outside 1-12.
DateNotIso8601
The text is not the ISO 8601 YYYY-MM-DD shape.
DateYearOutOfRange
The year falls outside 0000-9999, the range a Date can hold.
Digits
An immutable, iterable sequence of decimal digits, each a Digit (0-9).
DnsNameFailure
Why a DnsName refused its input. Sealed, not an enum, because most variants echo the part of the input that failed.
DnsNameInvalidCharacters
character is ASCII but outside the letters, digits, hyphen and underscore this type allows.
DnsNameLabelEmpty
A label was empty, so two dots met or one sat at an edge. RFC 2181 gives a label one octet minimum, which is the only shape rule left once the hyphen-edge rule goes.
DnsNameLabelTooLong
A label ran past the 63 octets RFC 2181 §11 allows one.
DnsNameNotAscii
Something outside ASCII survived normalisation, so this may be an internationalised name.
DnsNameTooLong
The whole name ran past 253 characters: RFC 1035's 255-octet wire limit, in presentation form.
GeoCoordinate
A point on the Earth's surface: a latitude and a longitude, in decimal degrees.
GeoCoordinateFailure
Why a GeoCoordinate refused its input. Sealed, not an enum, because the range variants report the offending number back. Two remedies: GeoCoordinateNotIso6709 means fix the format, the other two mean fix a number.
GeoCoordinateLatitudeOutOfRange
The latitude falls outside -90 to 90.
GeoCoordinateLongitudeOutOfRange
The longitude falls outside -180 to 180.
GeoCoordinateNotIso6709
The text is not the ISO 6709 shape: a signed, fixed-width latitude and longitude closed by /. Minutes or seconds reaching 60 land here too, being part of the grammar, not a separate range.
GtinChecksumFailed
The check digit disagrees with the rest of the number: a digit is mistyped or transposed.
GtinFailure
Why a Gtin refused its input. Sealed, not an enum, because GtinWrongLength reports a value read from the input.
GtinInvalidCharacters
Something outside 0-9 survived normalisation (spaces and hyphens are stripped first).
GtinWrongLength
The digit count is none of the four GS1 lengths, so this is not a GTIN of any form.
HostnameFailure
Why a Hostname refused its input. Sealed, not an enum, because most variants echo the part of the input that failed.
HostnameInvalidCharacters
character is ASCII but outside the letters, digits and hyphen RFC 1123 allows.
HostnameLabelMalformed
label is empty, or opens or closes with a hyphen, which RFC 1123 reserves for the interior.
HostnameLabelTooLong
A label ran past the 63 octets RFC 1035 allows one.
HostnameNotAscii
Something outside ASCII survived normalisation, so this may be an internationalised name.
HostnameNumericTld
The last label is all digits, which RFC 1123 says a host name never is. It is an address.
HostnameTooLong
The whole name ran past 253 characters: RFC 1035's 255-octet wire limit, in presentation form.
IbanChecksumFailed
The mod-97 check digits disagree with the rest of the number: a character is mistyped.
IbanFailure
Why an Iban refused its input. Sealed, not an enum, because IbanUnknownCountry and IbanInvalidLength report values read from the input.
IbanInvalidCharacters
Something outside A-Z and 0-9 survived normalisation (whitespace is stripped first).
IbanInvalidLength
The country is known and fixes the length at expected, but the input is actual long.
IbanTooShort
Under four characters (empty included), so the country and check digits aren't there to inspect yet. Keep typing.
IbanUnknownCountry
countryCode is not in the IBAN registry, so this is unsupported rather than mistyped.
ImeiChecksumFailed
The check digit disagrees with the rest of the number: a digit is mistyped or transposed.
ImeiFailure
Why an Imei refused its input. Sealed, not an enum, because ImeiWrongLength reports a value read from the input.
ImeiInvalidCharacters
Something outside 0-9 survived normalisation (spaces and hyphens are stripped first).
ImeiWrongLength
Not fifteen digits, so this is not an IMEI. Sixteen is named as the IMEISV it is rather than called a miscount.
IpAddressFailure
Why an IpAddress refused its input. Sealed, not an enum, because three variants echo the part of the input that failed.
IpAddressLeadingZero
part carries a leading zero, which is refused rather than read.
IpAddressMalformed
The text is neither a dotted quad nor an RFC 4291 IPv6 address.
IpAddressPartOutOfRange
part is a well-formed number that does not fit its field: an octet past 255, or a hextet past four digits.
IpAddressWrongOctetCount
IpAddress.fromOctets got other than the 4 octets of IPv4 or the 16 of IPv6.
IsbnChecksumFailed
The check digit disagrees with the rest of the number: a character is mistyped or transposed.
IsbnFailure
Why an Isbn refused its input. Sealed, not an enum, because IsbnWrongLength and IsbnInvalidPrefix report values read from the input.
IsbnInvalidCharacters
Something outside 0-9 survived normalisation (spaces and hyphens are stripped first). X counts only as the last character of the ten-digit form, where it stands for the value ten.
IsbnInvalidPrefix
Thirteen digits, but prefix is not a range ISO 2108 gives to books: this is some other GS1 article number wearing the same shape.
IsbnWrongLength
Neither ten nor thirteen characters survived normalisation, so this is not an ISBN of either generation. Count again, or keep typing.
IsinChecksumFailed
The check digit disagrees with the rest: a character is mistyped or transposed.
IsinFailure
Why an Isin refused its input. Sealed, not an enum, because IsinWrongLength and IsinInvalidPrefix report values read from the input.
IsinInvalidCharacters
Something outside A-Z and 0-9 survived normalisation.
IsinInvalidPrefix
The leading two characters are not both letters. ISO 6166 requires them, whether or not they name a country: XS is Euroclear and Clearstream, and is as valid as GB.
IsinWrongLength
Not twelve characters once whitespace is stripped, so this is not an ISIN.
IsniChecksumFailed
The check character disagrees with the rest: a character is mistyped or transposed.
IsniFailure
Why an Isni refused its input. Sealed, not an enum, because IsniWrongLength reports a value read from the input.
IsniInvalidCharacters
Something outside 0-9 survived normalisation. X counts only as the final character, where it stands for the value ten.
IsniWrongLength
Not sixteen characters once separators are stripped, so this is not an ISNI.
Iso8601Duration
An ISO 8601 duration: P3Y6M4DT12H30M5S, or the week form P2W. Standard: ISO 8601.
Iso8601DurationDanglingTimeDesignator
A T with no time component after it, as in P1DT. The designator exists to separate months from minutes, so it means nothing on its own.
Iso8601DurationEmpty
P or PT with nothing after it. ISO 8601 requires at least one component, so a zero duration is written PT0S rather than P.
Iso8601DurationFailure
Why an Iso8601Duration refused its input. Sealed, not an enum, because three variants carry the part that broke.
Iso8601DurationFractionNotSmallest
A fraction sat above the smallest component present. ISO 8601 allows one only on the lowest-order component, so P0.5Y1M is refused where P1Y0.5M is not.
Iso8601DurationMalformed
The text is not a P-prefixed duration at all.
Iso8601DurationWeeksNotAlone
Weeks appeared beside another component. ISO 8601 makes PnW an alternative to PnYnMnDTnHnMnS, not a component of it, so the two never mix.
IssnChecksumFailed
The check character disagrees with the rest of the number: a character is mistyped or transposed.
IssnFailure
Why an Issn refused its input. Sealed, not an enum, because IssnWrongLength reports a value read from the input.
IssnInvalidCharacters
Something outside 0-9 survived normalisation (the hyphen and spaces are stripped first). X counts only as the final character, where it stands for the value ten.
IssnWrongLength
Not eight characters once the hyphen and any spaces are stripped, so this is not an ISSN.
MacAddressFailure
Why a MacAddress refused its input. Sealed, not an enum, because MacAddressWrongOctetCount reports a count read from the input.
MacAddressMalformed
The text is none of the four accepted notations, or mixes two of them.
MacAddressWrongOctetCount
The notation was recognised but held neither six octets (48-bit) nor eight (64-bit). Also what MacAddress.fromOctets rejects.
MintedFailure
Why a minted value type refused its input.
ParseFailure<F extends MintedFailure, T>
A parse that failed, for the reason given.
ParseOutcome<F extends MintedFailure, T>
The result of parsing text: either the value, or the MintedFailure saying why not.
ParseSuccess<F extends MintedFailure, T>
A parse that produced value.
PaymentCardNumber
A payment card number: the ISO/IEC 7812 primary account number (PAN), validated for digits, the 8-to-19-digit length window, and the Luhn check digit. Credit, debit, prepaid and gift cards all share the numbering scheme. Standard: ISO/IEC 7812.
PaymentCardNumberChecksumFailed
The final digit disagrees with the rest of the number: a digit is mistyped or transposed.
PaymentCardNumberFailure
Why a PaymentCardNumber refused its input. Sealed, not an enum, because PaymentCardNumberWrongLength reports a value read from the input.
PaymentCardNumberInvalidCharacters
Something outside 0-9 survived normalisation (spaces and hyphens are stripped first).
PaymentCardNumberWrongLength
Outside the 8-to-19-digit window ISO/IEC 7812 allows a primary account number.
UuidFailure
Why a Uuid refused its input. Sealed, not an enum, because UuidWrongByteCount reports a count known only per call.
UuidMalformed
The text is not the canonical 8-4-4-4-12 hex form, wrapped or otherwise.
UuidWrongByteCount
Uuid.fromBytes got other than 16 bytes. Every 16-byte sequence is a valid UUID, so length is all it can reject.

Enums

CardScheme
The card scheme (network) a PaymentCardNumber's prefix belongs to.
EmailFailure
Why an Email refused its input. One variant, and that is the ceiling, not a shortcut: email_validator exposes a single bool, so a finer diagnosis would be a guess.
IpVersion
Which family an IpAddress belongs to. Derived from an address that already parsed, so it is a classification rather than a value type: no parse door of its own.
Iso8601DurationComponent
Which component of an Iso8601Duration carries its fractional part. Derived from a duration that already parsed, so it is a classification rather than a value type: no parse door.
MonthFailure
Why a Month refused its input. One variant: a closed set of twelve has one way to miss.
PhoneNumberFailure
Why a PhoneNumber refused its input. Only unknownCountryCallingCode comes from the engine: phone_numbers_parser throws one of its five codes in practice, so the rest we check ourselves.
PhoneNumberType
PortRange
Which RFC 6335 range a Port falls in. Derived from a port that already parsed, so it is a classification rather than a value type: no parse door of its own.
UuidVariant
The variant of a Uuid: which layout family it belongs to, named by the variant bits (the first hex digit of the fourth group). See RFC 9562 §4.1.
Weekday
A day of the week, Monday to Sunday. Date.weekday returns one.

Extension Types

Bic
A BIC, better known as a SWIFT code: validated for structure and for a real ISO 3166-1 country. Standard: ISO 9362.
Digit
A single decimal digit, 0-9.
DnsName
A DNS name: the permissive counterpart to Hostname, e.g. _dmarc.example.com. Standards: RFC 2181 §11 for the syntax, RFC 8552 for the underscored names that need it.
Email
An email address, validated against the RFC 5322 grammar (via email_validator). Standard: RFC 5322.
Gtin
A GTIN (Global Trade Item Number): validated for digits, one of the four GS1 lengths, and the GS1 mod-10 check digit. The number inside an EAN-8, UPC-A, EAN-13 or ITF-14 barcode. Standard: GS1 GTIN.
Hostname
A hostname: the dot-separated name of a host on a network, e.g. www.example.com. Standards: RFC 1123 §2.1 for the grammar, RFC 1035 §2.3.4 for the size limits.
Iban
An IBAN: validated for structure, country-specific length, and the mod-97 checksum (via iban_validator). Standard: ISO 13616.
Imei
An IMEI (International Mobile Equipment Identity): validated for digits, the fifteen-digit length, and the Luhn check digit. Identifies one piece of mobile equipment, not its subscriber. Standard: 3GPP TS 23.003.
IpAddress
An IP address, v4 or v6, in canonical text form: 192.0.2.1, 2001:db8::1. Standards: RFC 791 and RFC 4291 for the addresses, RFC 5952 for the canonical IPv6 text.
Isbn
An ISBN (International Standard Book Number): validated for length, prefix, and the ISO 2108 check digit, mod-11 over the ten-digit form and GS1 mod-10 over the thirteen-digit one. Standard: ISO 2108.
Isin
An ISIN (International Securities Identification Number): validated for the twelve-character length, the A-Z0-9 charset, a two-letter prefix, and the ISO 6166 check digit. Standard: ISO 6166.
Isni
An ISNI (International Standard Name Identifier): validated for the sixteen-character length, the charset, and the ISO 7064 MOD 11-2 check character. Identifies a public identity: a person, a pseudonym, or an organisation. Standard: ISO 27729.
Issn
An ISSN (International Standard Serial Number): validated for characters, the eight-character length, and the ISO 3297 mod-11 check character. Identifies a serial title, not one issue of it. Standard: ISO 3297.
MacAddress
A MAC address: the 48- or 64-bit address identifying an IEEE 802 network interface, e.g. 00:00:5e:00:53:00. IEEE Std 802 defines the address itself; RFC 9542 fixes the terminology and reserves the documentation ranges.
Month
A month of the year, 1 (January) to 12 (December).
NaturalNumber
An integer strictly greater than zero: 1 or more.
Percentage
A proportion in hundredths, where 15 is fifteen percent.
PhoneNumber
A phone number, validated and stored in its canonical E.164 form (via phone_numbers_parser). Standard: E.164.
Port
A transport-layer port number, 0 to 65535. Standard: RFC 6335.
Probability
A probability: 0 to 1 inclusive, where 0.15 is a fifteen percent chance.
Uint
An integer that is never negative: 0 or more.
Uint16
An unsigned 16-bit integer: 0 to 65535.
Uint2
An unsigned 2-bit integer: 0 to 3.
Uint32
An unsigned 32-bit integer: 0 to 4294967295.
Uint4
An unsigned 4-bit integer, a nibble: 0 to 15.
Uint8
An unsigned 8-bit integer, a byte: 0 to 255.
Uuid
A UUID (Universally Unique IDentifier): 128 bits in the canonical 8-4-4-4-12 hex form, e.g. f81d4fae-7dec-11d0-a765-00a0c91e6bf6. Standard: RFC 9562, which obsoletes RFC 4122.

Exceptions / Errors

MintedFormatError
The error ParseOutcome.getOrThrow raises, carrying the typed failure and its rendered message.