+ * Number of elements to sort. + *
+ * @param callable(non-negative-int):TElement $element+ * Callback used to retrieve an element by its sequential position. + *
+ * @param callable(non-negative-int, TElement):void $set+ * Callback used to replace an element at its sequential position. + *
+ * @param callable(TElement):TKey $key+ * Callback used to extract the integer distribution key from an element. + *
+ * + * @return void + */ + public function sort (int $size, callable $element, callable $set, callable $key):void; + +} \ No newline at end of file diff --git a/src/Boundary/Algorithm/Sorting/SortAlgorithm.php b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php new file mode 100644 index 0000000..f70fb46 --- /dev/null +++ b/src/Boundary/Algorithm/Sorting/SortAlgorithm.php @@ -0,0 +1,61 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Algorithm\Sorting; + +/** + * ### Sorting algorithm + * + * Defines a strategy for ordering elements within an indexed range. + * + * Elements are addressed internally by sequential positions, independently of the keys or indexes used by their + * underlying representation. This allows the algorithm to operate on sequential values, key-value entries, and other + * ordered representations without depending on their storage semantics. + * + * Sorting is performed in place through the supplied access and swap operations. + * @since 1.0.0 + * + * @template TElement + */ +interface SortAlgorithm { + + /** + * ### Sorts elements + * + * Rearranges the specified number of elements according to the supplied comparison callback. + * + * The callback must return a value less than zero when the first element should precede the second, zero when both + * elements compare equally, or a value greater than zero when the first element should follow the second. + * @since 1.0.0 + * + * @param non-negative-int $size+ * Number of elements to sort. + *
+ * @param callable(non-negative-int):TElement $element+ * Callback used to retrieve an element by its internal position. + *
+ * @param callable(non-negative-int, TElement):void $set+ * Callback used to replace an element at its sequential position. + *
+ * @param callable(non-negative-int, non-negative-int):void $swap+ * Callback used to exchange two elements by their internal positions. + *
+ * @param callable(TElement, TElement):int $comparator+ * Callback used to compare two elements. + *
+ * + * @return void + */ + public function sort (int $size, callable $element, callable $set, callable $swap, callable $comparator):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/BackAccess.php b/src/Boundary/Capability/Access/BackAccess.php new file mode 100644 index 0000000..e4c2192 --- /dev/null +++ b/src/Boundary/Capability/Access/BackAccess.php @@ -0,0 +1,41 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines access to the back boundary value + * + * Back access provides read-only access to the last value of an ordered sequence. + * + * The capability defines the fundamental operation for retrieving the value at the back boundary without + * prescribing how values are stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface BackAccess { + + /** + * ### Returns the last value + * + * Returns the value at the end of the sequence when it exists. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe+ * The index to check. + *
+ * + * @return bool True if the index exists, false otherwise. + */ + public function has (int $index):bool; + + /** + * ### Returns the value at the specified index + * + * Returns the value currently stored at the specified index. + * @since 1.0.0 + * + * @param int $index+ * The zero-based index of the value to retrieve. + *
+ * + * @return \FireHub\Core\Type\Maybe+ * The key to check. + *
+ * + * @return bool True if a value exists for the specified key, false otherwise. + */ + public function has (mixed $key):bool; + + /** + * ### Returns the value associated with the specified key + * @since 1.0.0 + * + * @param TKey $key+ * The key whose value should be returned. + *
+ * + * @return \FireHub\Core\Type\Maybe+ * The value whose occurrences should be counted. + *
+ * + * @return non-negative-int The number of occurrences of the specified value. + */ + public function frequency (mixed $value):int; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Access/ValueAccess.php b/src/Boundary/Capability/Access/ValueAccess.php new file mode 100644 index 0000000..fd80457 --- /dev/null +++ b/src/Boundary/Capability/Access/ValueAccess.php @@ -0,0 +1,41 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Access; + +/** + * ### Defines value-based access + * + * Value access provides the ability to determine whether a specific value is present within an object. + * + * The capability defines the fundamental operation for value membership without prescribing how values are stored, + * compared, indexed, or located internally. + * @since 1.0.0 + * + * @template TValue + */ +interface ValueAccess { + + /** + * ### Checks whether a value exists + * @since 1.0.0 + * + * @param TValue $value+ * The value to check. + *
+ * + * @return bool True if the value exists, false otherwise. + */ + public function contains (mixed $value):bool; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/BidirectionalIteration.php b/src/Boundary/Capability/BidirectionalIteration.php new file mode 100644 index 0000000..74d16c7 --- /dev/null +++ b/src/Boundary/Capability/BidirectionalIteration.php @@ -0,0 +1,40 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines bidirectional iteration over a sequence of values + * + * Bidirectional iteration extends standard iteration with access to the same sequence in reverse order without + * prescribing how those values are stored or represented. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Iteration+ * Maximum number of elements to yield. If null, traversal continues until the traversal naturally terminates. + *
+ * + * @return iterable+ * The values to insert at the back. + *
+ * + * @return void + */ + public function insertBack (mixed ...$values):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/BackMutation.php b/src/Boundary/Capability/Mutation/BackMutation.php new file mode 100644 index 0000000..b04e448 --- /dev/null +++ b/src/Boundary/Capability/Mutation/BackMutation.php @@ -0,0 +1,31 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines mutation at the back boundary + * + * Back mutation combines back insertion and back removal into a single capability, providing the complete set of + * mutation operations available at the back boundary of an ordered sequence. + * + * The capability defines only the operations for modifying the back boundary without prescribing how values are + * stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Mutation\BackInsertion+ * The values to insert at the front. + *
+ * + * @return void + */ + public function insertFront (mixed ...$values):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/FrontMutation.php b/src/Boundary/Capability/Mutation/FrontMutation.php new file mode 100644 index 0000000..fc58957 --- /dev/null +++ b/src/Boundary/Capability/Mutation/FrontMutation.php @@ -0,0 +1,31 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines mutation at the front boundary + * + * Front mutation combines front insertion and front removal into a single capability, providing the complete set + * of mutation operations available at the front boundary of an ordered sequence. + * + * The capability defines only the operations for modifying the front boundary without prescribing how values are + * stored, organized, or represented internally. + * @since 1.0.0 + * + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Mutation\FrontInsertion+ * Zero-based insertion index. + *
+ * @param TValue $value+ * Value to insert. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: CREATED if the value was + * inserted, or NOT_FOUND if the index does not exist. + */ + public function insertAt (int $index, mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/IndexMutation.php b/src/Boundary/Capability/Mutation/IndexMutation.php new file mode 100644 index 0000000..bff80cd --- /dev/null +++ b/src/Boundary/Capability/Mutation/IndexMutation.php @@ -0,0 +1,67 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines indexed mutation of values + * + * Indexed mutation provides the ability to create, replace, and remove values identified by an integer index. + * + * The capability defines the fundamental operations for modifying indexed values without prescribing how values + * are stored, organized, or represented internally. Each mutation operation reports its result through a + * MutationOutcome value. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexMutation { + + /** + * ### Sets the value at the specified index + * + * Associates the specified value with the given index. If the index does not exist, a new value is created. + * If the index already exists, its current value is replaced. + * @since 1.0.0 + * + * @param int $index+ * The index at which to set the value. + *
+ * + * @param TValue $value+ * The value to set. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, UPDATED if an existing value was replaced or NOT_FOUND if the index does not exist. + */ + public function set (int $index, mixed $value):MutationOutcome; + + /** + * ### Removes the value at the specified index + * + * Removes the value associated with the specified index when it exists. + * @since 1.0.0 + * + * @param int $index+ * The index of the value to remove. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the index does not exist. + */ + public function remove (int $index):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/IndexReplacement.php b/src/Boundary/Capability/Mutation/IndexReplacement.php new file mode 100644 index 0000000..d905903 --- /dev/null +++ b/src/Boundary/Capability/Mutation/IndexReplacement.php @@ -0,0 +1,51 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines indexed replacement of values + * + * Indexed replacement provides the ability to replace an existing value identified by an integer index without + * changing the structure in which the value is stored. + * + * The capability does not permit creation or removal of indexed values. Implementations preserve their existing + * indexed structure and report NOT_FOUND when the specified index does not exist. + * @since 1.0.0 + * + * @template TValue + */ +interface IndexReplacement { + + /** + * ### Replaces the value at the specified index + * + * Replaces the existing value associated with the specified index without creating a new index or otherwise + * changing the indexed structure. + * @since 1.0.0 + * + * @param int $index+ * The index whose value should be replaced. + *
+ * @param TValue $value+ * The replacement value. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: UPDATED if the value was + * replaced, or NOT_FOUND if the index does not exist. + */ + public function replace (int $index, mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/Insertion.php b/src/Boundary/Capability/Mutation/Insertion.php new file mode 100644 index 0000000..9c36600 --- /dev/null +++ b/src/Boundary/Capability/Mutation/Insertion.php @@ -0,0 +1,45 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +/** + * ### Defines insertion of values into a data structure + * + * Insertion defines the ability to add values to a data structure without prescribing their resulting positions. + * + * The capability allows the implementing structure to determine how inserted values are organized according + * to its ordering rules, structural constraints, or storage representation. + * @since 1.0.0 + * + * @template TValue + */ +interface Insertion { + + /** + * ### Inserts values into the data structure + * + * Inserts one or more values according to the organizational rules of the implementing structure. + * + * The operation does not guarantee that inserted values occupy the front, back, or any particular position. + * @since 1.0.0 + * + * @param TValue ...$values+ * Values to insert. + *
+ * + * @return void + */ + public function insert (mixed ...$values):void; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/KeyMutation.php b/src/Boundary/Capability/Mutation/KeyMutation.php new file mode 100644 index 0000000..bc337d8 --- /dev/null +++ b/src/Boundary/Capability/Mutation/KeyMutation.php @@ -0,0 +1,67 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines key-based mutation of values + * + * Key mutation provides the ability to create, replace, and remove values identified by their keys. + * + * The capability defines the fundamental operations for modifying keyed values without prescribing how values + * are stored, organized, or represented internally. Each mutation operation reports its result through a + * MutationOutcome value. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyMutation { + + /** + * ### Sets the value associated with the specified key + * + * Associates the specified value with the given key. If the key does not exist, a new value is created. If the + * key already exists, its current value is replaced. + * @since 1.0.0 + * + * @param TKey $key+ * The key with which to associate the value. + *
+ * @param TValue $value+ * The value to set. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, or UPDATED if an existing value was replaced. + */ + public function set (mixed $key, mixed $value):MutationOutcome; + + /** + * ### Removes the value associated with the specified key + * + * Removes the value associated with the specified key when it exists. + * @since 1.0.0 + * + * @param TKey $key+ * The key whose associated value should be removed. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the key does not exist. + */ + public function remove (mixed $key):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/KeyReplacement.php b/src/Boundary/Capability/Mutation/KeyReplacement.php new file mode 100644 index 0000000..39af173 --- /dev/null +++ b/src/Boundary/Capability/Mutation/KeyReplacement.php @@ -0,0 +1,52 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines key-based replacement of values + * + * Key replacement provides the ability to replace an existing value identified by its key without changing the + * keyed structure in which the value is stored. + * + * The capability does not permit creation or removal of keyed values. Implementations preserve their existing set + * of keys and report NOT_FOUND when the specified key does not exist. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyReplacement { + + /** + * ### Replaces the value associated with the specified key + * + * Replaces the existing value associated with the specified key without creating a new key or otherwise + * changing the keyed structure. + * @since 1.0.0 + * + * @param TKey $key+ * The key whose associated value should be replaced. + *
+ * @param TValue $value+ * The replacement value. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the replacement: UPDATED if the value was + * replaced, or NOT_FOUND if the key does not exist. + */ + public function replace (mixed $key, mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/MultiplicityMutation.php b/src/Boundary/Capability/Mutation/MultiplicityMutation.php new file mode 100644 index 0000000..ff1eae7 --- /dev/null +++ b/src/Boundary/Capability/Mutation/MultiplicityMutation.php @@ -0,0 +1,81 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines multiplicity-based value mutation + * + * Multiplicity mutation provides the ability to add and remove a specified number of occurrences of a value and + * remove all occurrences of a value. + * + * The capability applies to objects whose mutation semantics allow logically equal values to occur multiple times. + * It does not prescribe how values, occurrence counts, or equality semantics are represented internally. + * @since 1.0.0 + * + * @template TValue + */ +interface MultiplicityMutation { + + /** + * ### Adds occurrences of a value + * @since 1.0.0 + * + * @param TValue $value+ * The value whose occurrences should be added. + *
+ * + * @param positive-int $count+ * The number of occurrences to add. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was created, + * or UPDATED if the value already exists a new occurrence was added. + */ + public function add (mixed $value, int $count = 1):MutationOutcome; + + /** + * ### Removes occurrences of a value + * + * Removes up to the specified number of occurrences of the value. + * @since 1.0.0 + * + * @param TValue $value+ * The value whose occurrences should be removed. + *
+ * + * @param positive-int $count+ * The maximum number of occurrences to remove. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if last value was removed, + * UPDATED if value was removed but some are still left, or NOT_FOUND if the value does not exist. + */ + public function remove (mixed $value, int $count = 1):MutationOutcome; + + /** + * ### Removes all occurrences of a value + * @since 1.0.0 + * + * @param TValue $value+ * The value whose occurrences should be removed. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if all values were removed, + * or NOT_FOUND if the value does not exist. + */ + public function removeAll (mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Mutation/ValueMutation.php b/src/Boundary/Capability/Mutation/ValueMutation.php new file mode 100644 index 0000000..f0be3e9 --- /dev/null +++ b/src/Boundary/Capability/Mutation/ValueMutation.php @@ -0,0 +1,61 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Mutation; + +use FireHub\Core\Meta\Enum\MutationOutcome; + +/** + * ### Defines value-based mutation + * + * Value mutation provides the ability to add and remove values using the value itself as the mutation target. + * + * The capability defines the fundamental mutation operations without prescribing how values are stored, compared, + * indexed, or modified internally. + * @since 1.0.0 + * + * @template TValue + */ +interface ValueMutation { + + /** + * ### Adds a value + * + * Adds a value to the sequence. If the value already exists, it is ignored. + * @since 1.0.0 + * + * @param TValue $value+ * The value to add. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: CREATED if a new value was + * created, or ALREADY_EXISTS if the value already exists. + */ + public function add (mixed $value):MutationOutcome; + + /** + * ### Removes a value + * + * Removes a value from the sequence. If the value does not exist, it is ignored. + * @since 1.0.0 + * + * @param TValue $value+ * The value to remove. + *
+ * + * @return \FireHub\Core\Meta\Enum\MutationOutcome The outcome of the mutation: REMOVED if a value was removed, + * or NOT_FOUND if the key does not exist. + */ + public function remove (mixed $value):MutationOutcome; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Query/RandomSelectable.php b/src/Boundary/Capability/Query/RandomSelectable.php new file mode 100644 index 0000000..e8bb1d8 --- /dev/null +++ b/src/Boundary/Capability/Query/RandomSelectable.php @@ -0,0 +1,59 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Query; + +use FireHub\Core\Type\Maybe; + +/** + * ### Defines random selection of values + * + * Random selection provides the ability to select one or more values from a data structure without modifying its + * contents. + * + * Implementations determine how randomness is produced and how values participate in selection according to the + * semantics of the implementing data structure. + * @since 1.0.0 + * + * @template TValue + */ +interface RandomSelectable { + + /** + * ### Selects a random value + * + * Selects and returns one randomly chosen value from the data structure without modifying its contents. + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Maybe+ * The maximum number of values to select. + *
+ * + * @return static A structure containing the randomly selected values. + */ + public function sample (int $size):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Query/Searchable.php b/src/Boundary/Capability/Query/Searchable.php new file mode 100644 index 0000000..df30a9c --- /dev/null +++ b/src/Boundary/Capability/Query/Searchable.php @@ -0,0 +1,43 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=7.4 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Query; + +/** + * ### Defines value searching + * + * Provides the ability to search for a value and return a result identifying the matching value or its location + * within a data structure. + * + * The capability does not prescribe how values are searched, compared, stored, or represented, nor does it + * prescribe the representation of a successful search result. + * @since 1.0.0 + * + * @template TValue + * @template TResult + */ +interface Searchable { + + /** + * ### Searches for a value + * + * Searches for the specified value and returns the corresponding search result when a match exists. + * @since 1.0.0 + * + * @param TValue $value Value to search for. + * + * @return null|TResult Search result if the value was found, null otherwise. + */ + public function search (mixed $value):mixed; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Thawable.php b/src/Boundary/Capability/Thawable.php new file mode 100644 index 0000000..f9a83f4 --- /dev/null +++ b/src/Boundary/Capability/Thawable.php @@ -0,0 +1,41 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines a contract for objects that can produce a mutable instance + * + * A thawable object can create a new mutable instance derived from its current state without modifying the original + * instance. + * + * The returned instance represents the same logical state at the time of thawing but may maintain its state + * independently or share the underlying state when the implementation supports copy-on-write semantics. + * @since 1.0.0 + */ +interface Thawable { + + /** + * ### Creates a mutable instance + * + * Creates a new mutable instance derived from the current instance without modifying the state of the current + * instance. + * + * The returned instance must be mutable and distinct from the current instance. + * @since 1.0.0 + * + * @return static A new mutable instance. + */ + public function thaw ():static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Concatenable.php b/src/Boundary/Capability/Transformation/Concatenable.php new file mode 100644 index 0000000..a889a72 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Concatenable.php @@ -0,0 +1,42 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines concatenation capability + * + * Defines the capability for producing a structure containing the values of the current structure followed by the + * values provided by another iterable source. + * @since 1.0.0 + * + * @template TValue + */ +interface Concatenable { + + /** + * ### Concatenates values + * + * Creates a new instance containing the values of the current structure followed by the specified values while + * preserving their iteration order. + * @since 1.0.0 + * + * @param iterable+ * The values to concatenate. + *
+ * + * @return static A new instance containing the concatenated values. + */ + public function concat (iterable $values):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/DistributionSortable.php b/src/Boundary/Capability/Transformation/DistributionSortable.php new file mode 100644 index 0000000..4c6ac6d --- /dev/null +++ b/src/Boundary/Capability/Transformation/DistributionSortable.php @@ -0,0 +1,55 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +use FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm; + +/** + * ### Defines distribution sorting capability + * + * Defines the capability for producing a representation whose values are ordered using a distribution sorting + * algorithm. + * + * Unlike comparison-based sorting, distribution sorting derives ordering from integer keys extracted from individual + * values rather than by comparing pairs of values. + * + * Implementations determine how values are accessed, reordered, and stored while the supplied algorithm determines + * the distribution strategy used to establish their resulting order. + * @since 1.0.0 + * + * @template TValue + */ +interface DistributionSortable { + + /** + * ### Sorts values using a distribution sorting algorithm + * + * Produces a representation whose values are ordered according to integer keys extracted from each value by the + * supplied key extractor. + * @since 1.0.0 + * + * @template TKey of int|float + * + * @param \FireHub\Core\Boundary\Algorithm\Sorting\DistributionSortAlgorithm+ * Distribution sorting algorithm used to order the values. + *
+ * @param callable(TValue):int $key+ * Callback used to extract the integer distribution key from each value. + *
+ * + * @return static Sorted representation. + */ + public function distributionSort (DistributionSortAlgorithm $algorithm, callable $key):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Filterable.php b/src/Boundary/Capability/Transformation/Filterable.php new file mode 100644 index 0000000..c3a5f17 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Filterable.php @@ -0,0 +1,47 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines value filtering capability + * + * Represents the capability of producing a structure containing only values that satisfy a specified predicate. + * + * Each value is evaluated by the specified callback and retained in the resulting structure when the callback + * evaluates to true. + * + * Implementations determine the concrete type, key semantics, and execution strategy of the resulting structure. + * Filtering may therefore be performed eagerly, lazily, or through another implementation-specific strategy. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Filterable { + + /** + * ### Filters values + * + * Produces a structure containing only values that satisfy the specified predicate. + * @since 1.0.0 + * + * @param callable(TValue, TKey=):bool $callback+ * Predicate used to determine whether each value should be retained. + *
+ * + * @return static The resulting structure containing the filtered values. + */ + public function filter (callable $callback):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/KeyMappable.php b/src/Boundary/Capability/Transformation/KeyMappable.php new file mode 100644 index 0000000..8e4aa66 --- /dev/null +++ b/src/Boundary/Capability/Transformation/KeyMappable.php @@ -0,0 +1,45 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines key mapping transformation + * + * Key mapping provides the ability to transform the keys of a structure while preserving their associated + * values. + * + * Implementations define how collisions are handled when multiple keys are transformed into the same key. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface KeyMappable { + + /** + * ### Maps keys using the specified callback + * + * Creates a transformed representation by applying the specified callback to each key while preserving the + * value associated with that key. + * @since 1.0.0 + * + * @param callable(TKey, TValue=):TKey $callback+ * Callback used to transform each key. + *
+ * + * @return static+ * Direction in which the keys are ordered. + *
+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *
+ * + * @return static The sorted instance. + */ + public function sortKeys (Order $order = Order::ASC, ?SortAlgorithm $algorithm = null):static; + + /** + * ### Sorts keys using a comparator + * + * Produces a new instance whose entries are arranged according to the supplied key comparison callback. + * + * The callback must return a value less than zero when the first key should precede the second, zero when both + * keys compare equally, or a value greater than zero when the first key should follow the second. + * @since 1.0.0 + * + * @param callable(TKey, TKey):int<-1, 1> $comparator+ * Callback used to compare two keys. + *
+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *
+ * + * @return static The key-sorted instance. + */ + public function sortKeysWith (callable $comparator, ?SortAlgorithm $algorithm = null):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Mappable.php b/src/Boundary/Capability/Transformation/Mappable.php new file mode 100644 index 0000000..fefaa17 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Mappable.php @@ -0,0 +1,47 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines value mapping capability + * + * Represents the capability of transforming the values of a structure using a mapping operation. + * + * Each value is passed to the specified callback and replaced in the resulting structure by the value produced by + * that callback. + * + * Implementations determine the concrete type and execution strategy of the resulting structure. Mapping may + * therefore be performed eagerly, lazily, or through another implementation-specific strategy. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Mappable { + + /** + * ### Maps values + * + * Applies the specified mapping operation to each value. + * @since 1.0.0 + * + * @param callable(TValue, TKey=):TValue $callback+ * Mapping operation to apply to each value. + *
+ * + * @return static+ * The key-value associations to merge. + *
+ * + * @return static A new instance containing the merged key-value associations. + */ + public function merge (iterable $values):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Rejectable.php b/src/Boundary/Capability/Transformation/Rejectable.php new file mode 100644 index 0000000..b3aac80 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Rejectable.php @@ -0,0 +1,44 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +/** + * ### Defines rejection capability + * + * Defines the ability to create a transformed instance containing only elements that do not satisfy a given + * predicate. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends \FireHub\Core\Boundary\Capability\Transformation\Filterable+ * Predicate used to determine which elements should be rejected. + *
+ * + * @return static The transformed instance. + */ + public function reject (callable $callback):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Transformation/Sortable.php b/src/Boundary/Capability/Transformation/Sortable.php new file mode 100644 index 0000000..5bb7632 --- /dev/null +++ b/src/Boundary/Capability/Transformation/Sortable.php @@ -0,0 +1,71 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability\Transformation; + +use FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm; +use FireHub\Core\Meta\Enum\Order; + +/** + * ### Sortable capability + * + * Defines a capability for producing an ordered representation of an instance according to its values. + * + * Implementations may provide specialized sorting strategies appropriate to their underlying representation while + * preserving the semantics of the requested comparison mode or comparison callback. + * + * Sorting does not mutate the source instance. Instead, a new instance of the same concrete type is returned. + * @since 1.0.0 + * + * @template TValue + */ +interface Sortable { + + /** + * ### Sorts values + * + * Produces a new instance whose values are arranged according to the specified ordering mode. + * @since 1.0.0 + * + * @param \FireHub\Core\Meta\Enum\Order $order [optional]+ * Direction in which the values are ordered. + *
+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *
+ * + * @return static The sorted instance. + */ + public function sort (Order $order = Order::ASC, ?SortAlgorithm $algorithm = null):static; + + /** + * ### Sorts values using a comparator + * + * Produces a new instance whose values are arranged according to the supplied comparison callback. + * + * The callback must return a value less than zero when the first value should precede the second, zero when both + * values compare equally, or a value greater than zero when the first value should follow the second. + * @since 1.0.0 + * + * @param callable(TValue, TValue):int<-1, 1> $comparator+ * Callback used to compare two values. + *
+ * @param null|\FireHub\Core\Boundary\Algorithm\Sorting\SortAlgorithm+ * Sorting algorithm to use, or null to use the implementation's default sorting strategy. + *
+ * + * @return static The sorted instance. + */ + public function sortWith (callable $comparator, ?SortAlgorithm $algorithm = null):static; + +} \ No newline at end of file diff --git a/src/Boundary/Capability/Traversal.php b/src/Boundary/Capability/Traversal.php new file mode 100644 index 0000000..a6064c3 --- /dev/null +++ b/src/Boundary/Capability/Traversal.php @@ -0,0 +1,43 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.0 + * @package Core + */ + +namespace FireHub\Core\Boundary\Capability; + +/** + * ### Defines traversal of a sequence of values + * + * Traversal provides access to values through an iterable sequence without prescribing how the values are stored + * or represented. Implementations define the order and semantics in which values are traversed. + * @since 1.0.0 + * + * @template TKey + * @template TValue + */ +interface Traversal { + + /** + * ### Traverses the values + * + * Returns iterable that yields values according to the traversal order defined by the implementation. + * Traversal may be limited to a maximum number of elements. + * @since 1.0.0 + * + * @param null|int $limit+ * Maximum number of elements to yield. If null, traversal continues until the traversal naturally terminates. + *
+ * + * @return iterable
+ * 1970-01-01T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case UNIX = '1970-01-01T00:00:00+00:00';
+
+ /**
+ * ### GPS epoch
+ *
+ * The GPS epoch is the reference point used by the Global Positioning System (GPS) timescale.
+ * It begins at 1980-01-06T00:00:00+00:00 and is used as the starting point for measuring GPS time in seconds and
+ * fractional seconds.
+ *
+ *
+ * 1980-01-06T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case GPS = '1980-01-06T00:00:00+00:00';
+
+ /**
+ * ### NTP epoch
+ *
+ * The NTP epoch is the reference point used by the Network Time Protocol (NTP) timescale.
+ * It begins at 1900-01-01T00:00:00+00:00 and is used as the starting point for measuring NTP time in seconds and
+ * fractional seconds.
+ *
+ *
+ * 1900-01-01T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case NTP = '1900-01-01T00:00:00+00:00';
+
+ /**
+ * ### Windows NT epoch
+ *
+ * The Windows NT epoch is the reference point used by the Windows NT family of operating systems.
+ * It begins at 1601-01-01T00:00:00+00:00 and is used as the starting point for measuring Windows NT time in seconds
+ * and fractional seconds.
+ *
+ *
+ * 1601-01-01T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case WINDOWS_NT = '1601-01-01T00:00:00+00:00';
+
+ /**
+ * ### Excel epoch
+ *
+ * The Excel epoch is the reference point used by Microsoft Excel's serial date system.
+ * It begins at 1899-12-30T00:00:00+00:00 and is used as the starting point for measuring Excel serial date and
+ * time values.
+ *
+ *
+ * 1899-12-30T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case EXCEL = '1899-12-30T00:00:00+00:00';
+
+ /**
+ * ### Y2K epoch
+ *
+ * The Y2K epoch is the reference point marking the beginning of the year 2000.
+ * It begins at 2000-01-01T00:00:00+00:00 and can be used as an alternative starting point for measuring time.
+ *
+ *
+ * 2000-01-01T00:00:00+00:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case Y2K = '2000-01-01T00:00:00+00:00';
+
+ /**
+ * ### Returns the Unix epoch offset in seconds
+ * @since 1.0.0
+ *
+ * @return int Unix epoch offset in seconds
+ */
+ public function unixOffset ():int {
+
+ return match ($this) {
+ self::UNIX => 0,
+ self::GPS => 315964800,
+ self::NTP => 2208988800,
+ self::WINDOWS_NT => -11644473600,
+ self::EXCEL => -2209161600,
+ self::Y2K => 946684800,
+ };
+
+ }
+
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Expression/DateKeyword.php b/src/Meta/Enum/Date/Expression/DateKeyword.php
new file mode 100644
index 0000000..1723acb
--- /dev/null
+++ b/src/Meta/Enum/Date/Expression/DateKeyword.php
@@ -0,0 +1,50 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Expression;
+
+/**
+ * ### Defines date-related temporal keywords
+ *
+ * The DateKeyword enum defines keywords that identify a calendar date relative to the current date.
+ *
+ * These values are commonly used when parsing human-readable date and time expressions.
+ * @since 1.0.0
+ */
+enum DateKeyword:string {
+
+ /**
+ * ### Yesterday
+ *
+ * The calendar day immediately preceding the current day.
+ * @since 1.0.0
+ */
+ case YESTERDAY = 'yesterday';
+
+ /**
+ * ### Today
+ *
+ * The current calendar day.
+ * @since 1.0.0
+ */
+ case TODAY = 'today';
+
+ /**
+ * ### Tomorrow
+ *
+ * The calendar day immediately follows the current day.
+ * @since 1.0.0
+ */
+ case TOMORROW = 'tomorrow';
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Expression/Keyword.php b/src/Meta/Enum/Date/Expression/Keyword.php
new file mode 100644
index 0000000..042f1a2
--- /dev/null
+++ b/src/Meta/Enum/Date/Expression/Keyword.php
@@ -0,0 +1,34 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Expression;
+
+/**
+ * ### Defines temporal keywords
+ *
+ * The Keyword enum defines keywords that identify specific or relative date and time within a temporal expression.
+ *
+ * These values are commonly used when parsing human-readable date and time expressions.
+ * @since 1.0.0
+ */
+enum Keyword:string {
+
+ /**
+ * ### Now
+ *
+ * The current date and time.
+ * @since 1.0.0
+ */
+ case NOW = 'now';
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Expression/Ordinal.php b/src/Meta/Enum/Date/Expression/Ordinal.php
new file mode 100644
index 0000000..3173aa2
--- /dev/null
+++ b/src/Meta/Enum/Date/Expression/Ordinal.php
@@ -0,0 +1,98 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Expression;
+
+/**
+ * ### Defines ordinal positions
+ *
+ * The Ordinal enum defines ordinal positions from first through twelfth.
+ *
+ * Ordinal positions can be used to describe the position of a temporal occurrence within a larger temporal unit.
+ * @since 1.0.0
+ */
+enum Ordinal:string {
+
+ /**
+ * ### First
+ * @since 1.0.0
+ */
+ case FIRST = 'first';
+
+ /**
+ * ### Second
+ * @since 1.0.0
+ */
+ case SECOND = 'second';
+
+ /**
+ * ### Third
+ * @since 1.0.0
+ */
+ case THIRD = 'third';
+
+ /**
+ * ### Fourth
+ * @since 1.0.0
+ */
+ case FOURTH = 'fourth';
+
+ /**
+ * ### Fifth
+ * @since 1.0.0
+ */
+ case FIFTH = 'fifth';
+
+ /**
+ * ### Sixth
+ * @since 1.0.0
+ */
+ case SIXTH = 'sixth';
+
+ /**
+ * ### Seventh
+ * @since 1.0.0
+ */
+ case SEVENTH = 'seventh';
+
+ /**
+ * ### Eighth
+ * @since 1.0.0
+ */
+ case EIGHTH = 'eighth';
+
+ /**
+ * ### Ninth
+ * @since 1.0.0
+ */
+ case NINTH = 'ninth';
+
+ /**
+ * ### Tenth
+ * @since 1.0.0
+ */
+ case TENTH = 'tenth';
+
+ /**
+ * ### Eleventh
+ * @since 1.0.0
+ */
+ case ELEVENTH = 'eleventh';
+
+ /**
+ * ### Twelfth
+ * @since 1.0.0
+ */
+ case TWELFTH = 'twelfth';
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Expression/Relative.php b/src/Meta/Enum/Date/Expression/Relative.php
new file mode 100644
index 0000000..5cd550a
--- /dev/null
+++ b/src/Meta/Enum/Date/Expression/Relative.php
@@ -0,0 +1,59 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Expression;
+
+/**
+ * ### Defines relative temporal positions
+ *
+ * The Relative enum defines temporal positions relative to a reference date or time.
+ *
+ * These values can be used to describe a temporal unit as preceding, following, or coinciding with a reference
+ * period.
+ * @since 1.0.0
+ */
+enum Relative:string {
+
+ /**
+ * ### Next
+ *
+ * The temporal period immediately follows the reference period.
+ * @since 1.0.0
+ */
+ case NEXT = 'next';
+
+ /**
+ * ### Last
+ *
+ * The immediately preceding temporal period.
+ * @since 1.0.0
+ */
+ case LAST = 'last';
+
+ /**
+ * ### Previous
+ *
+ * The temporal period immediately preceding the reference period.
+ * @since 1.0.0
+ */
+ case PREVIOUS = 'previous';
+
+ /**
+ * ### This
+ *
+ * The temporal period contains the reference point.
+ * @since 1.0.0
+ */
+ case THIS = 'this';
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Expression/TimeKeyword.php b/src/Meta/Enum/Date/Expression/TimeKeyword.php
new file mode 100644
index 0000000..90b5420
--- /dev/null
+++ b/src/Meta/Enum/Date/Expression/TimeKeyword.php
@@ -0,0 +1,42 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Expression;
+
+/**
+ * ### Defines time-related temporal keywords
+ *
+ * The TimeKeyword enum defines keywords that identify specific or relative times within a temporal expression.
+ *
+ * These values are commonly used when parsing human-readable date and time expressions.
+ * @since 1.0.0
+ */
+enum TimeKeyword:string {
+
+ /**
+ * ### Midnight
+ *
+ * The beginning of the calendar day at 00:00:00.
+ * @since 1.0.0
+ */
+ case MIDNIGHT = 'midnight';
+
+ /**
+ * ### Now
+ *
+ * The current date and time.
+ * @since 1.0.0
+ */
+ case NOW = 'now';
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/ExtendedUnit.php b/src/Meta/Enum/Date/ExtendedUnit.php
new file mode 100644
index 0000000..9a67229
--- /dev/null
+++ b/src/Meta/Enum/Date/ExtendedUnit.php
@@ -0,0 +1,99 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date;
+
+/**
+ * ### Defines extended date and time units
+ *
+ * The ExtendedUnit enum defines calendar-derived date and time units supported by the FireHub temporal system.
+ *
+ * Each case represents an extended temporal unit that provides higher-level calendar semantics beyond the
+ * fundamental date and time units.
+ * @since 1.0.0
+ */
+enum ExtendedUnit {
+
+ /**
+ * ### Millennium
+ *
+ * A period of time spanning 1,000 years.
+ * @since 1.0.0
+ */
+ case MILLENNIUM;
+
+ /**
+ * ### Century
+ *
+ * A period of time spanning 100 years.
+ * @since 1.0.0
+ */
+ case CENTURY;
+
+ /**
+ * ### Decade
+ *
+ * A period of time spanning 10 years.
+ * @since 1.0.0
+ */
+ case DECADE;
+
+ /**
+ * ### Quarter
+ *
+ * A calendar quarter.
+ * @since 1.0.0
+ */
+ case QUARTER;
+
+ /**
+ * ### Get the base unit
+ *
+ * Returns the base temporal unit from which the current unit is derived.
+ *
+ * The base unit represents the unit to which the current unit can be reduced using its conversion factor.
+ * @since 1.0.0
+ *
+ * @return \FireHub\Core\Meta\Enum\Date\Unit The base unit, or null if the unit is not derived from another unit.
+ */
+ public function base ():Unit {
+
+ return match ($this) {
+ self::MILLENNIUM, self::CENTURY, self::DECADE => Unit::YEAR,
+ self::QUARTER => Unit::MONTH
+ };
+
+ }
+
+ /**
+ * ### Get the conversion factor
+ *
+ * Returns the number of base units contained in one instance of the current unit.
+ *
+ * The factor defines the relationship between the current unit and its base unit.
+ * @since 1.0.0
+ *
+ * @return int<1,max> The number of base units represented by one current unit.
+ */
+ public function factor ():int {
+
+ return match ($this) {
+ self::MILLENNIUM => 1000,
+ self::CENTURY => 100,
+ self::DECADE => 10,
+ self::QUARTER => 3
+ };
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format.php b/src/Meta/Enum/Date/Format.php
new file mode 100644
index 0000000..c954ed2
--- /dev/null
+++ b/src/Meta/Enum/Date/Format.php
@@ -0,0 +1,206 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date;
+
+use FireHub\Core\Meta\Enum\Date\Format\Token;
+
+/**
+ * ### Provides predefined date and time formatting standards
+ *
+ * The TemporalFormat enum defines commonly used PHP date and time format patterns for parsing and formatting temporal
+ * values throughout the FireHub ecosystem.
+ *
+ * It provides reusable predefined formats for date, time, and combined date-time values while allowing temporal value
+ * objects to maintain support for arbitrary custom PHP format strings.
+ * @since 1.0.0
+ */
+enum Format:string implements Token {
+
+ /**
+ * ### ISO 8601 calendar date
+ *
+ *
+ * 2000-12-31
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_DATE = 'Y-m-d';
+
+ /**
+ * ### ISO time
+ *
+ *
+ * 23:59:50
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_TIME = 'H:i:s';
+
+ /**
+ * ### ISO time with microseconds
+ *
+ *
+ * 23:59:50.000000
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_TIME_MICROSECONDS = 'H:i:s.u';
+
+ /**
+ * ### ISO date and time
+ *
+ *
+ * 2000-12-31 23:59:50
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_DATE_TIME = 'Y-m-d H:i:s';
+
+ /**
+ * ### ISO date and time with microseconds
+ *
+ *
+ * 2000-12-31 23:59:50.000000
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_DATE_TIME_MICROSECONDS = 'Y-m-d H:i:s.u';
+
+ /**
+ * ### ATOM date and time
+ *
+ *
+ * 2000-12-31T23:59:50+01:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case ATOM = 'Y-m-d\TH:i:sP';
+
+ /**
+ * ### ATOM date and time with milliseconds
+ *
+ *
+ * 2000-12-31T23:59:50.000+01:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case ATOM_EXTENDED = 'Y-m-d\TH:i:s.vP';
+
+ /**
+ * ### ATOM date and time with microseconds
+ *
+ *
+ * 2000-12-31T23:59:50.000000+01:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case ATOM_MICROSECONDS = 'Y-m-d\TH:i:s.uP';
+
+ /**
+ * ### HTTP cookie date and time
+ *
+ *
+ * Sunday, 31-Dec-2000 23:59:50 CET
+ *
+ *
+ * @since 1.0.0
+ */
+ case COOKIE = 'l, d-M-Y H:i:s T';
+
+ /**
+ * ### ISO 8601 date and time with numeric timezone offset
+ *
+ *
+ * 2000-12-31T23:59:50+0100
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO8601 = 'Y-m-d\TH:i:sO';
+
+ /**
+ * ### ISO 8601 expanded date and time
+ *
+ *
+ * +2000-12-31T23:59:50+01:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO8601_EXPANDED = 'X-m-d\TH:i:sP';
+
+ /**
+ * ### RFC 822 date and time
+ *
+ *
+ * Sun, 31 Dec 00 23:59:50 +0100
+ *
+ *
+ * @since 1.0.0
+ */
+ case RFC822 = 'D, d M y H:i:s O';
+
+ /**
+ * ### RFC 850 date and time
+ *
+ *
+ * Sunday, 31-Dec-00 23:59:50 CET
+ *
+ *
+ * @since 1.0.0
+ */
+ case RFC850 = 'l, d-M-y H:i:s T';
+
+ /**
+ * ### RFC 7231 HTTP date and time
+ *
+ *
+ * Sun, 31 Dec 2000 23:59:50 GMT
+ *
+ *
+ * @since 1.0.0
+ */
+ case RFC7231 = 'D, d M Y H:i:s \G\M\T';
+
+ /**
+ * ### RSS date and time
+ *
+ *
+ * Sun, 31 Dec 2000 23:59:50 +0100
+ *
+ *
+ * @since 1.0.0
+ */
+ case RSS = 'D, d M Y H:i:s O';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Day.php b/src/Meta/Enum/Date/Format/Day.php
new file mode 100644
index 0000000..ac2e12d
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Day.php
@@ -0,0 +1,142 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines day format tokens
+ *
+ * The Day enum defines the supported format tokens for representing the day of the month or day of the week.
+ *
+ * Each case corresponds to a native PHP date and time format character and represents a specific day representation,
+ * such as numeric, zero-padded numeric, abbreviated textual, or full textual output.
+ * @since 1.0.0
+ */
+enum Day:string implements Token {
+
+ /**
+ * ### Day of the month without leading zeros
+ *
+ * A numeric representation of the day of the month without leading zeros.
+ *
+ *
+ * 1-31
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER = 'j';
+
+ /**
+ * ### Day of the month with leading zeros
+ *
+ * A two-digit numeric representation of the day of the month.
+ *
+ *
+ * 01-31
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER_PADDED = 'd';
+
+ /**
+ * ### Short textual day name
+ *
+ * A three-letter textual representation of the day of the week.
+ *
+ *
+ * Mon-Sun
+ *
+ *
+ * @since 1.0.0
+ */
+ case TEXT_SHORT = 'D';
+
+ /**
+ * ### Full textual day name
+ *
+ * The full textual representation of the day of the week.
+ *
+ *
+ * Monday-Sunday
+ *
+ *
+ * @since 1.0.0
+ */
+ case TEXT_LONG = 'l';
+
+ /**
+ * ### Day of the year
+ *
+ * A numeric representation of the day of the year, starting at zero.
+ *
+ *
+ * 0-365
+ *
+ *
+ * @since 1.0.0
+ */
+ case DAY_OF_YEAR = 'z';
+
+ /**
+ * ### Day of the week
+ *
+ * A numeric representation of the day of the week, with Sunday represented by zero.
+ *
+ *
+ * 0-6
+ *
+ *
+ * @since 1.0.0
+ */
+ case DAY_OF_WEEK = 'w';
+
+ /**
+ * ### ISO day of the week
+ *
+ * A numeric representation of the ISO-8601 day of the week, with Monday represented by one and Sunday by seven.
+ *
+ *
+ * 1-7
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_DAY_OF_WEEK = 'N';
+
+ /**
+ * ### English ordinal suffix
+ *
+ * The English ordinal suffix for the day of the month.
+ *
+ *
+ * st, nd, rd, th
+ *
+ *
+ * @since 1.0.0
+ */
+ case ORDINAL_SUFFIX = 'S';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Month.php b/src/Meta/Enum/Date/Format/Month.php
new file mode 100644
index 0000000..f6871fc
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Month.php
@@ -0,0 +1,102 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines month format tokens
+ *
+ * The Month enum defines the supported format tokens for representing the month and its properties.
+ *
+ * Each case corresponds to a native PHP date and time format character.
+ * @since 1.0.0
+ */
+enum Month:string implements Token {
+
+ /**
+ * ### Full textual month name
+ *
+ * The full textual representation of the month.
+ *
+ *
+ * January-December
+ *
+ *
+ * @since 1.0.0
+ */
+ case TEXT_LONG = 'F';
+
+ /**
+ * ### Short textual month name
+ *
+ * A three-letter textual representation of the month.
+ *
+ *
+ * Jan-Dec
+ *
+ *
+ * @since 1.0.0
+ */
+ case TEXT_SHORT = 'M';
+
+ /**
+ * ### Month number with leading zero
+ *
+ * A two-digit numeric representation of the month.
+ *
+ *
+ * 01-12
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER_PADDED = 'm';
+
+ /**
+ * ### Month number without leading zero
+ *
+ * A numeric representation of the month without leading zeros.
+ *
+ *
+ * 1-12
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER = 'n';
+
+ /**
+ * ### Number of days in the month
+ *
+ * The number of days in the month is represented by the current date.
+ *
+ *
+ * 28-31
+ *
+ *
+ * @since 1.0.0
+ */
+ case DAYS_IN_MONTH = 't';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Time.php b/src/Meta/Enum/Date/Format/Time.php
new file mode 100644
index 0000000..361d323
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Time.php
@@ -0,0 +1,180 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines time format tokens
+ *
+ * The Time enum defines the supported format tokens for representing the time of day and its fractional components.
+ *
+ * Each case corresponds to a native PHP date and time format character.
+ * @since 1.0.0
+ */
+enum Time:string implements Token {
+
+ /**
+ * ### Uppercase ante meridiem or post meridiem
+ *
+ * A textual representation indicating whether the time is before or after noon.
+ *
+ *
+ * AM or PM
+ *
+ *
+ * @since 1.0.0
+ */
+ case MERIDIEM_UPPER = 'A';
+
+ /**
+ * ### Lowercase ante meridiem or post meridiem
+ *
+ * A lowercase textual representation indicating whether the time is before or after noon.
+ *
+ *
+ * am or pm
+ *
+ *
+ * @since 1.0.0
+ */
+ case MERIDIEM_LOWER = 'a';
+
+ /**
+ * ### Swatch Internet Time
+ *
+ * The current time in Swatch Internet Time, represented as beats from 000 to 999.
+ *
+ *
+ * 000-999
+ *
+ *
+ * @since 1.0.0
+ */
+ case SWATCH_BEAT = 'B';
+
+ /**
+ * ### Hour in 12-hour format
+ *
+ * A numeric representation of the hour in a 12-hour format without leading zeros.
+ *
+ *
+ * 1-12
+ *
+ *
+ * @since 1.0.0
+ */
+ case HOUR_12 = 'g';
+
+ /**
+ * ### Hour in 24-hour format
+ *
+ * A numeric representation of the hour in a 24-hour format without leading zeros.
+ *
+ *
+ * 0-23
+ *
+ *
+ * @since 1.0.0
+ */
+ case HOUR_24 = 'G';
+
+ /**
+ * ### Hour in 12-hour format with leading zero
+ *
+ * A two-digit numeric representation of the hour in 12-hour format.
+ *
+ *
+ * 01-12
+ *
+ *
+ * @since 1.0.0
+ */
+ case HOUR_12_PADDED = 'h';
+
+ /**
+ * ### Hour in 24-hour format with leading zero
+ *
+ * A two-digit numeric representation of the hour in 24-hour format.
+ *
+ *
+ * 00-23
+ *
+ *
+ * @since 1.0.0
+ */
+ case HOUR_24_PADDED = 'H';
+
+ /**
+ * ### Minutes with leading zero
+ *
+ * A two-digit numeric representation of the minutes.
+ *
+ *
+ * 00-59
+ *
+ *
+ * @since 1.0.0
+ */
+ case MINUTE = 'i';
+
+ /**
+ * ### Seconds with leading zero
+ *
+ * A two-digit numeric representation of the seconds.
+ *
+ *
+ * 00-59
+ *
+ *
+ * @since 1.0.0
+ */
+ case SECOND = 's';
+
+ /**
+ * ### Milliseconds
+ *
+ * A three-digit numeric representation of milliseconds.
+ *
+ *
+ * 000-999
+ *
+ *
+ * @since 1.0.0
+ */
+ case MILLISECOND = 'v';
+
+ /**
+ * ### Microseconds
+ *
+ * A six-digit numeric representation of microseconds.
+ *
+ *
+ * 000000-999999
+ *
+ *
+ * @since 1.0.0
+ */
+ case MICROSECOND = 'u';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Timezone.php b/src/Meta/Enum/Date/Format/Timezone.php
new file mode 100644
index 0000000..4cdc479
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Timezone.php
@@ -0,0 +1,102 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines timezone format tokens
+ *
+ * The Timezone enum defines the supported format tokens for representing timezone information and UTC offsets.
+ *
+ * Each case corresponds to a native PHP date and time format character.
+ * @since 1.0.0
+ */
+enum Timezone:string implements Token {
+
+ /**
+ * ### Daylight Saving Time indicator
+ *
+ * Indicates whether daylight saving time is currently active.
+ *
+ *
+ * 1 or 0
+ *
+ *
+ * @since 1.0.0
+ */
+ case DAYLIGHT_SAVING = 'I';
+
+ /**
+ * ### UTC offset in hours
+ *
+ * The difference from Coordinated Universal Time (UTC) in hours.
+ *
+ *
+ * +0200
+ *
+ *
+ * @since 1.0.0
+ */
+ case OFFSET = 'O';
+
+ /**
+ * ### UTC offset with colon
+ *
+ * The difference from Coordinated Universal Time (UTC) with a colon separating hours and minutes.
+ *
+ *
+ * +02:00
+ *
+ *
+ * @since 1.0.0
+ */
+ case OFFSET_COLON = 'P';
+
+ /**
+ * ### Timezone abbreviation
+ *
+ * The abbreviated timezone name.
+ *
+ *
+ * CET
+ *
+ *
+ * @since 1.0.0
+ */
+ case ABBREVIATION = 'T';
+
+ /**
+ * ### Timezone offset in seconds
+ *
+ * The total timezone offset from UTC, expressed in seconds.
+ *
+ *
+ * 7200
+ *
+ *
+ * @since 1.0.0
+ */
+ case OFFSET_SECONDS = 'Z';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Token.php b/src/Meta/Enum/Date/Format/Token.php
new file mode 100644
index 0000000..010913a
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Token.php
@@ -0,0 +1,35 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines a date and time format token
+ *
+ * The Token interface defines the common contract for enumerations representing native PHP date and time format
+ * tokens.
+ *
+ * Implementations provide a specific format token used to represent a date or time component.
+ * @since 1.0.0
+ */
+interface Token {
+
+ /**
+ * ### Returns the format token value
+ * @since 1.0.0
+ *
+ * @return non-empty-string The format token value.
+ */
+ public function value ():string;
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Week.php b/src/Meta/Enum/Date/Format/Week.php
new file mode 100644
index 0000000..3db4fb3
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Week.php
@@ -0,0 +1,50 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines week format tokens
+ *
+ * The Week enum defines the supported format tokens for representing calendar weeks.
+ *
+ * Each case corresponds to a native PHP date and time format character.
+ * @since 1.0.0
+ */
+enum Week:string implements Token {
+
+ /**
+ * ### ISO week number
+ *
+ * The ISO-8601 week number of the year.
+ *
+ *
+ * 01-53
+ *
+ *
+ * @since 1.0.0
+ */
+ case ISO_NUMBER = 'W';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Format/Year.php b/src/Meta/Enum/Date/Format/Year.php
new file mode 100644
index 0000000..38d88d9
--- /dev/null
+++ b/src/Meta/Enum/Date/Format/Year.php
@@ -0,0 +1,76 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date\Format;
+
+/**
+ * ### Defines year format tokens
+ *
+ * The Year enum defines the supported format tokens for representing calendar years and leap years.
+ *
+ * Each case corresponds to a native PHP date and time format character.
+ * @since 1.0.0
+ */
+enum Year:string implements Token {
+
+ /**
+ * ### Two-digit year
+ *
+ * A two-digit numeric representation of the year.
+ *
+ *
+ * 00-99
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER_SHORT = 'y';
+
+ /**
+ * ### Four-digit year
+ *
+ * A four-digit numeric representation of the year.
+ *
+ *
+ * 0000-9999
+ *
+ *
+ * @since 1.0.0
+ */
+ case NUMBER_LONG = 'Y';
+
+ /**
+ * ### Leap year indicator
+ *
+ * Indicates whether the current year is a leap year.
+ *
+ *
+ * 1 or 0
+ *
+ *
+ * @since 1.0.0
+ */
+ case LEAP_YEAR = 'L';
+
+ /**
+ * @inheritDoc
+ *
+ * @since 1.0.0
+ */
+ public function value ():string {
+
+ return $this->value;
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Month.php b/src/Meta/Enum/Date/Month.php
new file mode 100644
index 0000000..de19fe8
--- /dev/null
+++ b/src/Meta/Enum/Date/Month.php
@@ -0,0 +1,172 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date;
+
+/**
+ * ### Defines calendar months
+ *
+ * The Month enum defines the twelve months of the Gregorian calendar.
+ *
+ * Each case represents a specific calendar month and provides its corresponding numeric month value.
+ * @since 1.0.0
+ */
+enum Month:int {
+
+ /**
+ * ### January
+ *
+ * The first month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case JANUARY = 1;
+
+ /**
+ * ### February
+ *
+ * The second month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case FEBRUARY = 2;
+
+ /**
+ * ### March
+ *
+ * The third month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case MARCH = 3;
+
+ /**
+ * ### April
+ *
+ * The fourth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case APRIL = 4;
+
+ /**
+ * ### May
+ *
+ * The fifth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case MAY = 5;
+
+ /**
+ * ### June
+ *
+ * The sixth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case JUNE = 6;
+
+ /**
+ * ### July
+ *
+ * The seventh month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case JULY = 7;
+
+ /**
+ * ### August
+ *
+ * The eighth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case AUGUST = 8;
+
+ /**
+ * ### September
+ *
+ * The ninth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case SEPTEMBER = 9;
+
+ /**
+ * ### October
+ *
+ * The tenth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case OCTOBER = 10;
+
+ /**
+ * ### November
+ *
+ * The eleventh month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case NOVEMBER = 11;
+
+ /**
+ * ### December
+ *
+ * The twelfth month of the Gregorian calendar year.
+ * @since 1.0.0
+ */
+ case DECEMBER = 12;
+
+ /**
+ * ### Returns the long name of the month
+ * @since 1.0.0
+ *
+ * @return non-empty-string The long name of the month.
+ */
+ public function longName ():string {
+
+ return match ($this) {
+ self::JANUARY => 'January',
+ self::FEBRUARY => 'February',
+ self::MARCH => 'March',
+ self::APRIL => 'April',
+ self::MAY => 'May',
+ self::JUNE => 'June',
+ self::JULY => 'July',
+ self::AUGUST => 'August',
+ self::SEPTEMBER => 'September',
+ self::OCTOBER => 'October',
+ self::NOVEMBER => 'November',
+ self::DECEMBER => 'December'
+ };
+
+ }
+
+ /**
+ * ### Returns the short name of the month
+ * @since 1.0.0
+ *
+ * @return non-empty-string The short name of the month.
+ */
+ public function shortName ():string {
+
+ return match ($this) {
+ self::JANUARY => 'Jan',
+ self::FEBRUARY => 'Feb',
+ self::MARCH => 'Mar',
+ self::APRIL => 'Apr',
+ self::MAY => 'May',
+ self::JUNE => 'Jun',
+ self::JULY => 'Jul',
+ self::AUGUST => 'Aug',
+ self::SEPTEMBER => 'Sep',
+ self::OCTOBER => 'Oct',
+ self::NOVEMBER => 'Nov',
+ self::DECEMBER => 'Dec'
+ };
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/Unit.php b/src/Meta/Enum/Date/Unit.php
new file mode 100644
index 0000000..06d0850
--- /dev/null
+++ b/src/Meta/Enum/Date/Unit.php
@@ -0,0 +1,115 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date;
+
+/**
+ * ### Defines basic date and time units
+ *
+ * The Unit enum defines the fundamental calendar and time units supported by the FireHub temporal system.
+ *
+ * Each case represents a basic temporal unit that can be used as a reference for date and time calculations,
+ * comparisons, intervals, and conversions.
+ * @since 1.0.0
+ */
+enum Unit {
+
+ /**
+ * ### Year
+ *
+ * A calendar year.
+ * @since 1.0.0
+ */
+ case YEAR;
+
+ /**
+ * ### Month
+ *
+ * A calendar month.
+ * @since 1.0.0
+ */
+ case MONTH;
+
+ /**
+ * ### Fortnight
+ *
+ * A period of time spanning 14 days.
+ * @since 1.0.0
+ */
+ case FORTNIGHT;
+
+ /**
+ * ### Week
+ *
+ * A calendar week.
+ * @since 1.0.0
+ */
+ case WEEK;
+
+ /**
+ * ### Week day
+ *
+ * A day of the week.
+ * @since 1.0.0
+ */
+ case WEEKDAY;
+
+ /**
+ * ### Day
+ *
+ * A calendar day.
+ * @since 1.0.0
+ */
+ case DAY;
+
+ /**
+ * ### Hour
+ *
+ * An hour of time.
+ * @since 1.0.0
+ */
+ case HOUR;
+
+ /**
+ * ### Minute
+ *
+ * A minute of time.
+ * @since 1.0.0
+ */
+ case MINUTE;
+
+ /**
+ * ### Second
+ *
+ * A second of time.
+ * @since 1.0.0
+ */
+ case SECOND;
+
+ /**
+ * ### Millisecond
+ *
+ * A millisecond of time.
+ * @since 1.0.0
+ */
+ case MILLISECOND;
+
+ /**
+ * ### Microsecond
+ *
+ * A microsecond of time.
+ * @since 1.0.0
+ */
+ case MICROSECOND;
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Date/WeekDay.php b/src/Meta/Enum/Date/WeekDay.php
new file mode 100644
index 0000000..51ec160
--- /dev/null
+++ b/src/Meta/Enum/Date/WeekDay.php
@@ -0,0 +1,145 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Date;
+
+/**
+ * ### Defines the days of the week
+ *
+ * The Weekday enum defines the seven days of the Gregorian calendar week.
+ *
+ * Each case represents a specific day of the week and provides its corresponding numeric value according to the
+ * native PHP date and time representation.
+ * @since 1.0.0
+ */
+enum WeekDay:int {
+
+ /**
+ * ### Sunday
+ *
+ * The first day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case SUNDAY = 0;
+
+ /**
+ * ### Monday
+ *
+ * The second day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case MONDAY = 1;
+
+ /**
+ * ### Tuesday
+ *
+ * The third day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case TUESDAY = 2;
+
+ /**
+ * ### Wednesday
+ *
+ * The fourth day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case WEDNESDAY = 3;
+
+ /**
+ * ### Thursday
+ *
+ * The fifth day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case THURSDAY = 4;
+
+ /**
+ * ### Friday
+ *
+ * The sixth day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case FRIDAY = 5;
+
+ /**
+ * ### Saturday
+ *
+ * The seventh day of the week according to the native PHP date and time representation.
+ * @since 1.0.0
+ */
+ case SATURDAY = 6;
+
+ /**
+ * ### Returns the ISO weekday number
+ *
+ * Returns the numeric representation of the weekday according to ISO 8601, where Monday is 1 and Sunday is 7.
+ * @since 1.0.0
+ *
+ * @return int<1,7> The ISO weekday number.
+ */
+ public function isoValue ():int {
+
+ return match ($this) {
+ self::MONDAY => 1,
+ self::TUESDAY => 2,
+ self::WEDNESDAY => 3,
+ self::THURSDAY => 4,
+ self::FRIDAY => 5,
+ self::SATURDAY => 6,
+ self::SUNDAY => 7,
+ };
+
+ }
+
+ /**
+ * ### Returns the long name of the weekday
+ * @since 1.0.0
+ *
+ * @return non-empty-string The long name of the weekday.
+ */
+ public function longName ():string {
+
+ return match ($this) {
+ self::SUNDAY => 'Sunday',
+ self::MONDAY => 'Monday',
+ self::TUESDAY => 'Tuesday',
+ self::WEDNESDAY => 'Wednesday',
+ self::THURSDAY => 'Thursday',
+ self::FRIDAY => 'Friday',
+ self::SATURDAY => 'Saturday',
+ };
+
+ }
+
+ /**
+ * ### Returns the short name of the weekday
+ * @since 1.0.0
+ *
+ * @return non-empty-string The short name of the weekday.
+ */
+ public function shortName ():string {
+
+ return match ($this) {
+ self::SUNDAY => 'Sun',
+ self::MONDAY => 'Mon',
+ self::TUESDAY => 'Tue',
+ self::WEDNESDAY => 'Wed',
+ self::THURSDAY => 'Thu',
+ self::FRIDAY => 'Fri',
+ self::SATURDAY => 'Sat',
+ };
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/MutationOutcome.php b/src/Meta/Enum/MutationOutcome.php
new file mode 100644
index 0000000..256a5f3
--- /dev/null
+++ b/src/Meta/Enum/MutationOutcome.php
@@ -0,0 +1,54 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum;
+
+/**
+ * ### Represents the outcome of a mutation operation
+ *
+ * MutationOutcome describes the result of an operation that attempts to create, update, or remove an entry.
+ * @since 1.0.0
+ */
+enum MutationOutcome {
+
+ /**
+ * ### New Entry Created
+ * @since 1.0.0
+ */
+ case CREATED;
+
+ /**
+ * ### Existing Entry Updated
+ * @since 1.0.0
+ */
+ case UPDATED;
+
+ /**
+ * ### Entry Already Exists
+ * @since 1.0.0
+ */
+ case ALREADY_EXISTS;
+
+ /**
+ * ### Entry Removed
+ * @since 1.0.0
+ */
+ case REMOVED;
+
+ /**
+ * ### Entry Not Found
+ * @since 1.0.0
+ */
+ case NOT_FOUND;
+
+}
\ No newline at end of file
diff --git a/src/Meta/Enum/Number/Format.php b/src/Meta/Enum/Number/Format.php
new file mode 100644
index 0000000..ad395ec
--- /dev/null
+++ b/src/Meta/Enum/Number/Format.php
@@ -0,0 +1,81 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.1
+ * @package Core
+ */
+
+namespace FireHub\Core\Meta\Enum\Number;
+
+/**
+ * ### Defines predefined numeric formatting conventions
+ *
+ * Provides commonly used numeric formatting conventions for interpreting decimal values.
+ *
+ * Each case defines the decimal and a thousand separators associated with the convention.
+ * @since 1.0.0
+ */
+enum Format {
+
+ /**
+ * ### Defines the international dot-decimal convention
+ *
+ * Uses a dot as the decimal separator and a comma as the thousand separator.
+ * @since 1.0.0
+ */
+ case DOT;
+
+ /**
+ * ### Defines the comma-decimal convention
+ *
+ * Uses a comma as the decimal separator and a dot as the thousand separator.
+ * @since 1.0.0
+ */
+ case COMMA;
+
+ /**
+ * ### Defines the SI-style convention
+ *
+ * Uses a dot as the decimal separator and a space as the thousand separator.
+ * @since 1.0.0
+ */
+ case SI;
+
+ /**
+ * ### Returns the decimal separator
+ * @since 1.0.0
+ *
+ * @return string The decimal separator.
+ */
+ public function decimalSeparator ():string {
+
+ return match ($this) {
+ self::DOT, self::SI => '.',
+ self::COMMA => ',',
+ };
+
+ }
+
+ /**
+ * ### Returns a thousand separator
+ * @since 1.0.0
+ *
+ * @return string The thousand separator.
+ */
+ public function thousandsSeparator ():string {
+
+ return match ($this) {
+ self::DOT => ',',
+ self::COMMA => '.',
+ self::SI => ' ',
+ };
+
+ }
+
+}
\ No newline at end of file
diff --git a/src/Type/Boolean.php b/src/Type/Boolean.php
new file mode 100644
index 0000000..05a8b07
--- /dev/null
+++ b/src/Type/Boolean.php
@@ -0,0 +1,69 @@
+
+ * @copyright 2026-present The FireHub Project - All rights reserved
+ * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0
+ *
+ * @php-version >=8.2
+ * @package Core
+ */
+
+namespace FireHub\Core\Type;
+
+/**
+ * ### Defines the base boolean Value Object type within the FireHub ecosystem
+ *
+ * This abstract class represents the foundation for all boolean-based Value Objects.
+ *
+ * It provides immutable boolean value semantics while allowing concrete implementations to extend the type with
+ * domain-specific behavior.
+ *
+ * The class keeps the Core layer focused on defining the boolean value contract, while concrete implementations
+ * belong to higher-level layers such as Foundation.
+ * @since 1.0.0
+ *
+ * @template TValue of bool
+ *
+ * @extends \FireHub\Core\Type\ValueObject+ * The code point value. + *
+ * + * @throws \FireHub\Core\Exception\Runtime\System\Invariant\InvalidCodepointException If the condition is not met. + * @throws \FireHub\Core\Exception\FireHubException If the condition is not met. + * @throws \FireHub\Core\Type\Exception\ValueObjectException If the exception is not a FireHubException. + * + * @return void + */ + public function __construct ( + private int $value + ) { + + $this->guard( + fn() => $value >= 0 && $value <= 0x10FFFF && ($value < 0xD800 || $value > 0xDFFF), + fn() => new InvalidCodepointException('Value must be a valid Unicode code point.') + ); + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():int { + + return $this->value; + + } + +} \ No newline at end of file diff --git a/src/Type/DataStructure/Map/Entry.php b/src/Type/DataStructure/Map/Entry.php new file mode 100644 index 0000000..0c83e6a --- /dev/null +++ b/src/Type/DataStructure/Map/Entry.php @@ -0,0 +1,70 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.2 + * @package Core + */ + +namespace FireHub\Core\Type\DataStructure\Map; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Map entry + * + * Represents an immutable key-value entry belonging to a map. + * + * A map entry groups a key together with its associated value and represents that association as a single value + * object. It provides a strongly typed representation of an individual map entry when the key and value need to be + * passed, returned, or otherwise handled together. + * + * The entry does not provide map storage or lookup behavior and does not maintain any relationship with the map from + * which it originated. It represents only the key-value association itself. + * @since 1.0.0 + * + * @template TKey + * @template TValue + * + * @extends ValueObject+ * The entry key. + *
+ * @param TValue $value+ * The entry value. + *
+ * + * @return void + */ + public function __construct ( + public mixed $key, + public mixed $value + ) {} + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():array { + + return [ + 'key' => $this->key, + 'value' => $this->value + ]; + + } + +} \ No newline at end of file diff --git a/src/Type/DataStructure/PriorityQueue/Entry.php b/src/Type/DataStructure/PriorityQueue/Entry.php new file mode 100644 index 0000000..0fb9d7e --- /dev/null +++ b/src/Type/DataStructure/PriorityQueue/Entry.php @@ -0,0 +1,70 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.2 + * @package Core + */ + +namespace FireHub\Core\Type\DataStructure\PriorityQueue; + +use FireHub\Core\Type\ValueObject; + +/** + * ### Priority queue entry + * + * Represents an immutable priority-value entry belonging to a priority queue. + * + * A priority queue entry groups a priority together with its associated value and represents that association as a + * single value object. It provides a strongly typed representation of an individual priority queue entry when the + * priority and value need to be passed, returned, or otherwise handled together. + * + * The entry does not provide priority queue storage or ordering behavior and does not maintain any relationship with + * the priority queue from which it originated. It represents only the priority-value association itself. + * @since 1.0.0 + * + * @template TPriority + * @template TValue + * + * @extends ValueObject+ * The entry priority. + *
+ * @param TValue $value+ * The entry value. + *
+ * + * @return void + */ + public function __construct ( + public mixed $priority, + public mixed $value + ) {} + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function value ():array { + + return [ + 'priority' => $this->priority, + 'value' => $this->value + ]; + + } + +} \ No newline at end of file diff --git a/src/Type/Exception/NoValueException.php b/src/Type/Exception/NoValueException.php new file mode 100644 index 0000000..67667f1 --- /dev/null +++ b/src/Type/Exception/NoValueException.php @@ -0,0 +1,27 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.3 + * @package Core + */ + +namespace FireHub\Core\Type\Exception; + +/** + * ### Thrown when attempting to access a value that does not exist + * + * This exception is thrown when an operation attempts to retrieve the contained value from a Maybe instance that + * represents the absence of a value. + * @since 1.0.0 + */ +final class NoValueException extends ValueObjectException { + + protected const string DEFAULT_MESSAGE = 'No value exists'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent.php b/src/Type/Geo/Continent.php new file mode 100644 index 0000000..ee8dc52 --- /dev/null +++ b/src/Type/Geo/Continent.php @@ -0,0 +1,121 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Type\Geo\Continent\ { + Geological, Landmass, PhysiographicRegion +}; + +/** + * ### Defines the world's continents + * + * The Continent enum represents the recognized continents of the world within the FireHub Core geographic type + * system. + * + * It provides a strongly typed representation of continental geographic regions without coupling the Core layer + * to external geographic codes, databases, or runtime-specific implementations. + * @since 1.0.0 + */ +enum Continent:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ASIA = 'Asia'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EUROPE = 'Europe'; + + /** + * @since 1.0.0 + */ + case NORTH_AMERICA = 'North America'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + + /** + * ## Gets a continent as a geological continent + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\Geological Geological continent. + */ + public function geological ():Geological { + + return match ($this) { + self::AFRICA => Geological::AFRICA, + self::ANTARCTICA => Geological::ANTARCTICA, + self::ASIA, self::EUROPE => Geological::EURASIA, + self::AUSTRALIA => Geological::AUSTRALIA, + self::NORTH_AMERICA => Geological::NORTH_AMERICA, + self::SOUTH_AMERICA => Geological::SOUTH_AMERICA + }; + + } + + /** + * ## Gets a continent as a physiographic region + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\PhysiographicRegion Physiographic region. + */ + public function physiographicRegion ():PhysiographicRegion { + + return match ($this) { + self::AFRICA => PhysiographicRegion::AFRICA, + self::ANTARCTICA => PhysiographicRegion::ANTARCTICA, + self::ASIA, self::EUROPE => PhysiographicRegion::EURASIA, + self::AUSTRALIA => PhysiographicRegion::AUSTRALIA, + self::NORTH_AMERICA, self::SOUTH_AMERICA => PhysiographicRegion::AMERICA + }; + + } + + /** + * ## Gets a continent as a landmass + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent\Landmass Landmass. + */ + public function landmass ():Landmass { + + return match ($this) { + self::AFRICA, self::ASIA, self::EUROPE => Landmass::AFRO_EURASIA, + self::ANTARCTICA => Landmass::ANTARCTICA, + self::AUSTRALIA => Landmass::AUSTRALIA, + self::NORTH_AMERICA, self::SOUTH_AMERICA => Landmass::AMERICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/Geological.php b/src/Type/Geo/Continent/Geological.php new file mode 100644 index 0000000..fa1ec50 --- /dev/null +++ b/src/Type/Geo/Continent/Geological.php @@ -0,0 +1,58 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the geological continental divisions of the world + * + * The Geological enum represents major geological divisions used to classify continents and their underlying + * continental structures within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of geological continental groupings independently of political, + * cultural, or administrative boundaries. + * @since 1.0.0 + */ +enum Geological:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EURASIA = 'Eurasia'; + + /** + * @since 1.0.0 + */ + case NORTH_AMERICA = 'North America'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/Landmass.php b/src/Type/Geo/Continent/Landmass.php new file mode 100644 index 0000000..26c55e0 --- /dev/null +++ b/src/Type/Geo/Continent/Landmass.php @@ -0,0 +1,48 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the major landmasses of the world + * + * The Landmass enum represents major continuous land areas used to classify continents according to their physical + * connection to other continental land areas within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of landmass groupings independently of political, cultural, or + * administrative boundaries. + * @since 1.0.0 + */ +enum Landmass :string { + + /** + * @since 1.0.0 + */ + case AFRO_EURASIA = 'Afro-Eurasia'; + + /** + * @since 1.0.0 + */ + case AMERICA = 'America'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Continent/PhysiographicRegion.php b/src/Type/Geo/Continent/PhysiographicRegion.php new file mode 100644 index 0000000..166175b --- /dev/null +++ b/src/Type/Geo/Continent/PhysiographicRegion.php @@ -0,0 +1,53 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo\Continent; + +/** + * ### Defines the major physiographic regions of the world + * + * The PhysiographicRegion enum represents major physical geographic regions used to classify continents according to + * their shared physical and geographic characteristics within the FireHub Core geographic type system. + * + * It provides a strongly typed representation of physiographic regional groupings independently of political, + * cultural, or administrative boundaries. + * @since 1.0.0 + */ +enum PhysiographicRegion:string { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case AMERICA = 'America'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case EURASIA = 'Eurasia'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Country.php b/src/Type/Geo/Country.php new file mode 100644 index 0000000..c3f55b6 --- /dev/null +++ b/src/Type/Geo/Country.php @@ -0,0 +1,2389 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\ { + M49, ISO3166 +}; + +/** + * ### Defines the world's countries + * + * The Country enum represents the recognized countries of the world within the FireHub Core geographic type + * system. + * + * It provides a strongly typed representation of countries independently of political, cultural, or administrative + * data that may change over time. + * @since 1.0.0 + */ +enum Country:string implements M49, ISO3166 { + + /** + * @since 1.0.0 + */ + case AFGHANISTAN = 'Afghanistan'; + + /** + * @since 1.0.0 + */ + case ALAND_ISLANDS = 'Åland Islands'; + + /** + * @since 1.0.0 + */ + case ALBANIA = 'Albania'; + + /** + * @since 1.0.0 + */ + case ALGERIA = 'Algeria'; + + /** + * @since 1.0.0 + */ + case AMERICAN_SAMOA = 'American Samoa'; + + /** + * @since 1.0.0 + */ + case ANDORRA = 'Andorra'; + + /** + * @since 1.0.0 + */ + case ANGOLA = 'Angola'; + + /** + * @since 1.0.0 + */ + case ANGUILLA = 'Anguilla'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ANTIGUA_AND_BARBUDA = 'Antigua and Barbuda'; + + /** + * @since 1.0.0 + */ + case ARGENTINA = 'Argentina'; + + /** + * @since 1.0.0 + */ + case ARMENIA = 'Armenia'; + + /** + * @since 1.0.0 + */ + case ARUBA = 'Aruba'; + + /** + * @since 1.0.0 + */ + case AUSTRALIA = 'Australia'; + + /** + * @since 1.0.0 + */ + case AUSTRIA = 'Austria'; + + /** + * @since 1.0.0 + */ + case AZERBAIJAN = 'Azerbaijan'; + + /** + * @since 1.0.0 + */ + case BAHAMAS = 'Bahamas'; + + /** + * @since 1.0.0 + */ + case BAHRAIN = 'Bahrain'; + + /** + * @since 1.0.0 + */ + case BANGLADESH = 'Bangladesh'; + + /** + * @since 1.0.0 + */ + case BARBADOS = 'Barbados'; + + /** + * @since 1.0.0 + */ + case BELARUS = 'Belarus'; + + /** + * @since 1.0.0 + */ + case BELGIUM = 'Belgium'; + + /** + * @since 1.0.0 + */ + case BELIZE = 'Belize'; + + /** + * @since 1.0.0 + */ + case BENIN = 'Benin'; + + /** + * @since 1.0.0 + */ + case BERMUDA = 'Bermuda'; + + /** + * @since 1.0.0 + */ + case BHUTAN = 'Bhutan'; + + /** + * @since 1.0.0 + */ + case BOLIVIA_PLURINATIONAL_STATE_OF = 'Bolivia, Plurinational State of'; + + /** + * @since 1.0.0 + */ + case BONAIRE_SINT_EUSTATIUS_AND_SABA = 'Bonaire, Sint Eustatius and Saba'; + + /** + * @since 1.0.0 + */ + case BOSNIA_AND_HERZEGOVINA = 'Bosnia and Herzegovina'; + + /** + * @since 1.0.0 + */ + case BOTSWANA = 'Botswana'; + + /** + * @since 1.0.0 + */ + case BOUVET_ISLAND = 'Bouvet Island'; + + /** + * @since 1.0.0 + */ + case BRAZIL = 'Brazil'; + + /** + * @since 1.0.0 + */ + case BRITISH_INDIAN_OCEAN_TERRITORY = 'British Indian Ocean Territory'; + + /** + * @since 1.0.0 + */ + case BRUNEI_DARUSSALAM = 'Brunei Darussalam'; + + /** + * @since 1.0.0 + */ + case BULGARIA = 'Bulgaria'; + + /** + * @since 1.0.0 + */ + case BURKINA_FASO = 'Burkina Faso'; + + /** + * @since 1.0.0 + */ + case BURUNDI = 'Burundi'; + + /** + * @since 1.0.0 + */ + case CABO_VERDE = 'Cabo Verde'; + + /** + * @since 1.0.0 + */ + case CAMBODIA = 'Cambodia'; + + /** + * @since 1.0.0 + */ + case CAMEROON = 'Cameroon'; + + /** + * @since 1.0.0 + */ + case CANADA = 'Canada'; + + /** + * @since 1.0.0 + */ + case CAYMAN_ISLANDS = 'Cayman Islands'; + + /** + * @since 1.0.0 + */ + case CENTRAL_AFRICAN_REPUBLIC = 'Central African Republic'; + + /** + * @since 1.0.0 + */ + case CHAD = 'Chad'; + + /** + * @since 1.0.0 + */ + case CHILE = 'Chile'; + + /** + * @since 1.0.0 + */ + case CHINA = 'China'; + + /** + * @since 1.0.0 + */ + case CHRISTMAS_ISLAND = 'Christmas Island'; + + /** + * @since 1.0.0 + */ + case COCOS_KEELING_ISLANDS = 'Cocos (Keeling) Islands'; + + /** + * @since 1.0.0 + */ + case COLOMBIA = 'Colombia'; + + /** + * @since 1.0.0 + */ + case COMOROS = 'Comoros'; + + /** + * @since 1.0.0 + */ + case CONGO = 'Congo'; + + /** + * @since 1.0.0 + */ + case CONGO_DEMOCRATIC_REPUBLIC_OF_THE = 'Congo, Democratic Republic of the'; + + /** + * @since 1.0.0 + */ + case COOK_ISLANDS = 'Cook Islands'; + + /** + * @since 1.0.0 + */ + case COSTA_RICA = 'Costa Rica'; + + /** + * @since 1.0.0 + */ + case COTE_D_IVOIRE = "Côte d'Ivoire"; + + /** + * @since 1.0.0 + */ + case CROATIA = 'Croatia'; + + /** + * @since 1.0.0 + */ + case CUBA = 'Cuba'; + + /** + * @since 1.0.0 + */ + case CURACAO = 'Curaçao'; + + /** + * @since 1.0.0 + */ + case CYPRUS = 'Cyprus'; + + /** + * @since 1.0.0 + */ + case CZECHIA = 'Czechia'; + + /** + * @since 1.0.0 + */ + case DENMARK = 'Denmark'; + + /** + * @since 1.0.0 + */ + case DJIBOUTI = 'Djibouti'; + + /** + * @since 1.0.0 + */ + case DOMINICA = 'Dominica'; + + /** + * @since 1.0.0 + */ + case DOMINICAN_REPUBLIC = 'Dominican Republic'; + + /** + * @since 1.0.0 + */ + case ECUADOR = 'Ecuador'; + + /** + * @since 1.0.0 + */ + case EGYPT = 'Egypt'; + + /** + * @since 1.0.0 + */ + case EL_SALVADOR = 'El Salvador'; + + /** + * @since 1.0.0 + */ + case EQUATORIAL_GUINEA = 'Equatorial Guinea'; + + /** + * @since 1.0.0 + */ + case ERITREA = 'Eritrea'; + + /** + * @since 1.0.0 + */ + case ESTONIA = 'Estonia'; + + /** + * @since 1.0.0 + */ + case ESWATINI = 'Eswatini'; + + /** + * @since 1.0.0 + */ + case ETHIOPIA = 'Ethiopia'; + + /** + * @since 1.0.0 + */ + case FALKLAND_ISLANDS_MALVINAS = 'Falkland Islands (Malvinas)'; + + /** + * @since 1.0.0 + */ + case FAROE_ISLANDS = 'Faroe Islands'; + + /** + * @since 1.0.0 + */ + case FIJI = 'Fiji'; + + /** + * @since 1.0.0 + */ + case FINLAND = 'Finland'; + + /** + * @since 1.0.0 + */ + case FRANCE = 'France'; + + /** + * @since 1.0.0 + */ + case FRENCH_GUIANA = 'French Guiana'; + + /** + * @since 1.0.0 + */ + case FRENCH_POLYNESIA = 'French Polynesia'; + + /** + * @since 1.0.0 + */ + case FRENCH_SOUTHERN_TERRITORIES = 'French Southern Territories'; + + /** + * @since 1.0.0 + */ + case GABON = 'Gabon'; + + /** + * @since 1.0.0 + */ + case GAMBIA = 'Gambia'; + + /** + * @since 1.0.0 + */ + case GEORGIA = 'Georgia'; + + /** + * @since 1.0.0 + */ + case GERMANY = 'Germany'; + + /** + * @since 1.0.0 + */ + case GHANA = 'Ghana'; + + /** + * @since 1.0.0 + */ + case GIBRALTAR = 'Gibraltar'; + + /** + * @since 1.0.0 + */ + case GREECE = 'Greece'; + + /** + * @since 1.0.0 + */ + case GREENLAND = 'Greenland'; + + /** + * @since 1.0.0 + */ + case GRENADA = 'Grenada'; + + /** + * @since 1.0.0 + */ + case GUADELOUPE = 'Guadeloupe'; + + /** + * @since 1.0.0 + */ + case GUAM = 'Guam'; + + /** + * @since 1.0.0 + */ + case GUATEMALA = 'Guatemala'; + + /** + * @since 1.0.0 + */ + case GUERNSEY = 'Guernsey'; + + /** + * @since 1.0.0 + */ + case GUINEA = 'Guinea'; + + /** + * @since 1.0.0 + */ + case GUINEA_BISSAU = 'Guinea-Bissau'; + + /** + * @since 1.0.0 + */ + case GUYANA = 'Guyana'; + + /** + * @since 1.0.0 + */ + case HAITI = 'Haiti'; + + /** + * @since 1.0.0 + */ + case HEARD_ISLAND_AND_MCDONALD_ISLANDS = 'Heard Island and McDonald Islands'; + + /** + * @since 1.0.0 + */ + case HOLY_SEE = 'Holy See'; + + /** + * @since 1.0.0 + */ + case HONDURAS = 'Honduras'; + + /** + * @since 1.0.0 + */ + case HONG_KONG = 'Hong Kong'; + + /** + * @since 1.0.0 + */ + case HUNGARY = 'Hungary'; + + /** + * @since 1.0.0 + */ + case ICELAND = 'Iceland'; + + /** + * @since 1.0.0 + */ + case INDIA = 'India'; + + /** + * @since 1.0.0 + */ + case INDONESIA = 'Indonesia'; + + /** + * @since 1.0.0 + */ + case IRAN_ISLAMIC_REPUBLIC_OF = 'Iran, Islamic Republic of'; + + /** + * @since 1.0.0 + */ + case IRAQ = 'Iraq'; + + /** + * @since 1.0.0 + */ + case IRELAND = 'Ireland'; + + /** + * @since 1.0.0 + */ + case ISLE_OF_MAN = 'Isle of Man'; + + /** + * @since 1.0.0 + */ + case ISRAEL = 'Israel'; + + /** + * @since 1.0.0 + */ + case ITALY = 'Italy'; + + /** + * @since 1.0.0 + */ + case JAMAICA = 'Jamaica'; + + /** + * @since 1.0.0 + */ + case JAPAN = 'Japan'; + + /** + * @since 1.0.0 + */ + case JERSEY = 'Jersey'; + + /** + * @since 1.0.0 + */ + case JORDAN = 'Jordan'; + + /** + * @since 1.0.0 + */ + case KAZAKHSTAN = 'Kazakhstan'; + + /** + * @since 1.0.0 + */ + case KENYA = 'Kenya'; + + /** + * @since 1.0.0 + */ + case KIRIBATI = 'Kiribati'; + + /** + * @since 1.0.0 + */ + case KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF = "Korea, Democratic People's Republic of"; + + /** + * @since 1.0.0 + */ + case KOREA_REPUBLIC_OF = 'Korea, Republic of'; + + /** + * @since 1.0.0 + */ + case KOSOVO = 'Kosovo'; + + /** + * @since 1.0.0 + */ + case KUWAIT = 'Kuwait'; + + /** + * @since 1.0.0 + */ + case KYRGYZSTAN = 'Kyrgyzstan'; + + /** + * @since 1.0.0 + */ + case LAO_PEOPLES_DEMOCRATIC_REPUBLIC = "Lao People's Democratic Republic"; + + /** + * @since 1.0.0 + */ + case LATVIA = 'Latvia'; + + /** + * @since 1.0.0 + */ + case LEBANON = 'Lebanon'; + + /** + * @since 1.0.0 + */ + case LESOTHO = 'Lesotho'; + + /** + * @since 1.0.0 + */ + case LIBERIA = 'Liberia'; + + /** + * @since 1.0.0 + */ + case LIBYA = 'Libya'; + + /** + * @since 1.0.0 + */ + case LIECHTENSTEIN = 'Liechtenstein'; + + /** + * @since 1.0.0 + */ + case LITHUANIA = 'Lithuania'; + + /** + * @since 1.0.0 + */ + case LUXEMBOURG = 'Luxembourg'; + + /** + * @since 1.0.0 + */ + case MACAO = 'Macao'; + + /** + * @since 1.0.0 + */ + case MADAGASCAR = 'Madagascar'; + + /** + * @since 1.0.0 + */ + case MALAWI = 'Malawi'; + + /** + * @since 1.0.0 + */ + case MALAYSIA = 'Malaysia'; + + /** + * @since 1.0.0 + */ + case MALDIVES = 'Maldives'; + + /** + * @since 1.0.0 + */ + case MALI = 'Mali'; + + /** + * @since 1.0.0 + */ + case MALTA = 'Malta'; + + /** + * @since 1.0.0 + */ + case MARSHALL_ISLANDS = 'Marshall Islands'; + + /** + * @since 1.0.0 + */ + case MARTINIQUE = 'Martinique'; + + /** + * @since 1.0.0 + */ + case MAURITANIA = 'Mauritania'; + + /** + * @since 1.0.0 + */ + case MAURITIUS = 'Mauritius'; + + /** + * @since 1.0.0 + */ + case MAYOTTE = 'Mayotte'; + + /** + * @since 1.0.0 + */ + case MEXICO = 'Mexico'; + + /** + * @since 1.0.0 + */ + case MICRONESIA_FEDERATED_STATES_OF = 'Micronesia, Federated States of'; + + /** + * @since 1.0.0 + */ + case MOLDOVA_REPUBLIC_OF = 'Moldova, Republic of'; + + /** + * @since 1.0.0 + */ + case MONACO = 'Monaco'; + + /** + * @since 1.0.0 + */ + case MONGOLIA = 'Mongolia'; + + /** + * @since 1.0.0 + */ + case MONTENEGRO = 'Montenegro'; + + /** + * @since 1.0.0 + */ + case MONTSERRAT = 'Montserrat'; + + /** + * @since 1.0.0 + */ + case MOROCCO = 'Morocco'; + + /** + * @since 1.0.0 + */ + case MOZAMBIQUE = 'Mozambique'; + + /** + * @since 1.0.0 + */ + case MYANMAR = 'Myanmar'; + + /** + * @since 1.0.0 + */ + case NAMIBIA = 'Namibia'; + + /** + * @since 1.0.0 + */ + case NAURU = 'Nauru'; + + /** + * @since 1.0.0 + */ + case NEPAL = 'Nepal'; + + /** + * @since 1.0.0 + */ + case NETHERLANDS_KINGDOM_OF_THE = 'Netherlands, Kingdom of the'; + + /** + * @since 1.0.0 + */ + case NEW_CALEDONIA = 'New Caledonia'; + + /** + * @since 1.0.0 + */ + case NEW_ZEALAND = 'New Zealand'; + + /** + * @since 1.0.0 + */ + case NICARAGUA = 'Nicaragua'; + + /** + * @since 1.0.0 + */ + case NIGER = 'Niger'; + + /** + * @since 1.0.0 + */ + case NIGERIA = 'Nigeria'; + + /** + * @since 1.0.0 + */ + case NIUE = 'Niue'; + + /** + * @since 1.0.0 + */ + case NORFOLK_ISLAND = 'Norfolk Island'; + + /** + * @since 1.0.0 + */ + case NORTH_MACEDONIA = 'North Macedonia'; + + /** + * @since 1.0.0 + */ + case NORTHERN_MARIANA_ISLANDS = 'Northern Mariana Islands'; + + /** + * @since 1.0.0 + */ + case NORWAY = 'Norway'; + + /** + * @since 1.0.0 + */ + case OMAN = 'Oman'; + + /** + * @since 1.0.0 + */ + case PAKISTAN = 'Pakistan'; + + /** + * @since 1.0.0 + */ + case PALAU = 'Palau'; + + /** + * @since 1.0.0 + */ + case PALESTINE_STATE_OF = 'Palestine, State of'; + + /** + * @since 1.0.0 + */ + case PANAMA = 'Panama'; + + /** + * @since 1.0.0 + */ + case PAPUA_NEW_GUINEA = 'Papua New Guinea'; + + /** + * @since 1.0.0 + */ + case PARAGUAY = 'Paraguay'; + + /** + * @since 1.0.0 + */ + case PERU = 'Peru'; + + /** + * @since 1.0.0 + */ + case PHILIPPINES = 'Philippines'; + + /** + * @since 1.0.0 + */ + case PITCAIRN = 'Pitcairn'; + + /** + * @since 1.0.0 + */ + case POLAND = 'Poland'; + + /** + * @since 1.0.0 + */ + case PORTUGAL = 'Portugal'; + + /** + * @since 1.0.0 + */ + case PUERTO_RICO = 'Puerto Rico'; + + /** + * @since 1.0.0 + */ + case QATAR = 'Qatar'; + + /** + * @since 1.0.0 + */ + case REUNION = 'Réunion'; + + /** + * @since 1.0.0 + */ + case ROMANIA = 'Romania'; + + /** + * @since 1.0.0 + */ + case RUSSIAN_FEDERATION = 'Russian Federation'; + + /** + * @since 1.0.0 + */ + case RWANDA = 'Rwanda'; + + /** + * @since 1.0.0 + */ + case SAINT_BARTHELEMY = 'Saint Barthélemy'; + + /** + * @since 1.0.0 + */ + case SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA = 'Saint Helena, Ascension and Tristan da Cunha'; + + /** + * @since 1.0.0 + */ + case SAINT_KITTS_AND_NEVIS = 'Saint Kitts and Nevis'; + + /** + * @since 1.0.0 + */ + case SAINT_LUCIA = 'Saint Lucia'; + + /** + * @since 1.0.0 + */ + case SAINT_MARTIN_FRENCH_PART = 'Saint Martin (French part)'; + + /** + * @since 1.0.0 + */ + case SAINT_PIERRE_AND_MIQUELON = 'Saint Pierre and Miquelon'; + + /** + * @since 1.0.0 + */ + case SAINT_VINCENT_AND_THE_GRENADINES = 'Saint Vincent and the Grenadines'; + + /** + * @since 1.0.0 + */ + case SAMOA = 'Samoa'; + + /** + * @since 1.0.0 + */ + case SAN_MARINO = 'San Marino'; + + /** + * @since 1.0.0 + */ + case SAO_TOME_AND_PRINCIPE = 'Sao Tome and Principe'; + + /** + * @since 1.0.0 + */ + case SAUDI_ARABIA = 'Saudi Arabia'; + + /** + * @since 1.0.0 + */ + case SENEGAL = 'Senegal'; + + /** + * @since 1.0.0 + */ + case SERBIA = 'Serbia'; + + /** + * @since 1.0.0 + */ + case SEYCHELLES = 'Seychelles'; + + /** + * @since 1.0.0 + */ + case SIERRA_LEONE = 'Sierra Leone'; + + /** + * @since 1.0.0 + */ + case SINGAPORE = 'Singapore'; + + /** + * @since 1.0.0 + */ + case SINT_MAARTEN_DUTCH_PART = 'Sint Maarten (Dutch part)'; + + /** + * @since 1.0.0 + */ + case SLOVAKIA = 'Slovakia'; + + /** + * @since 1.0.0 + */ + case SLOVENIA = 'Slovenia'; + + /** + * @since 1.0.0 + */ + case SOLOMON_ISLANDS = 'Solomon Islands'; + + /** + * @since 1.0.0 + */ + case SOMALIA = 'Somalia'; + + /** + * @since 1.0.0 + */ + case SOUTH_AFRICA = 'South Africa'; + + /** + * @since 1.0.0 + */ + case SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS = 'South Georgia and the South Sandwich Islands'; + + /** + * @since 1.0.0 + */ + case SOUTH_SUDAN = 'South Sudan'; + + /** + * @since 1.0.0 + */ + case SPAIN = 'Spain'; + + /** + * @since 1.0.0 + */ + case SRI_LANKA = 'Sri Lanka'; + + /** + * @since 1.0.0 + */ + case SUDAN = 'Sudan'; + + /** + * @since 1.0.0 + */ + case SURINAME = 'Suriname'; + + /** + * @since 1.0.0 + */ + case SVALBARD_AND_JAN_MAYEN = 'Svalbard and Jan Mayen'; + + /** + * @since 1.0.0 + */ + case SWEDEN = 'Sweden'; + + /** + * @since 1.0.0 + */ + case SWITZERLAND = 'Switzerland'; + + /** + * @since 1.0.0 + */ + case SYRIAN_ARAB_REPUBLIC = 'Syrian Arab Republic'; + + /** + * @since 1.0.0 + */ + case TAIWAN_PROVINCE_OF_CHINA = 'Taiwan, Province of China'; + + /** + * @since 1.0.0 + */ + case TAJIKISTAN = 'Tajikistan'; + + /** + * @since 1.0.0 + */ + case TANZANIA_UNITED_REPUBLIC_OF = 'Tanzania, United Republic of'; + + /** + * @since 1.0.0 + */ + case THAILAND = 'Thailand'; + + /** + * @since 1.0.0 + */ + case TIMOR_LESTE = 'Timor-Leste'; + + /** + * @since 1.0.0 + */ + case TOGO = 'Togo'; + + /** + * @since 1.0.0 + */ + case TOKELAU = 'Tokelau'; + + /** + * @since 1.0.0 + */ + case TONGA = 'Tonga'; + + /** + * @since 1.0.0 + */ + case TRINIDAD_AND_TOBAGO = 'Trinidad and Tobago'; + + /** + * @since 1.0.0 + */ + case TUNISIA = 'Tunisia'; + + /** + * @since 1.0.0 + */ + case TURKIYE = 'Türkiye'; + + /** + * @since 1.0.0 + */ + case TURKMENISTAN = 'Turkmenistan'; + + /** + * @since 1.0.0 + */ + case TURKS_AND_CAICOS_ISLANDS = 'Turks and Caicos Islands'; + + /** + * @since 1.0.0 + */ + case TUVALU = 'Tuvalu'; + + /** + * @since 1.0.0 + */ + case UGANDA = 'Uganda'; + + /** + * @since 1.0.0 + */ + case UKRAINE = 'Ukraine'; + + /** + * @since 1.0.0 + */ + case UNITED_ARAB_EMIRATES = 'United Arab Emirates'; + + /** + * @since 1.0.0 + */ + case UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND = 'United Kingdom of Great Britain and Northern Ireland'; + + /** + * @since 1.0.0 + */ + case UNITED_STATES_MINOR_OUTLYING_ISLANDS = 'United States Minor Outlying Islands'; + + /** + * @since 1.0.0 + */ + case UNITED_STATES_OF_AMERICA = 'United States of America'; + + /** + * @since 1.0.0 + */ + case URUGUAY = 'Uruguay'; + + /** + * @since 1.0.0 + */ + case UZBEKISTAN = 'Uzbekistan'; + + /** + * @since 1.0.0 + */ + case VANUATU = 'Vanuatu'; + + /** + * @since 1.0.0 + */ + case VENEZUELA_BOLIVARIAN_REPUBLIC_OF = 'Venezuela, Bolivarian Republic of'; + + /** + * @since 1.0.0 + */ + case VIET_NAM = 'Viet Nam'; + + /** + * @since 1.0.0 + */ + case VIRGIN_ISLANDS_BRITISH = 'Virgin Islands (British)'; + + /** + * @since 1.0.0 + */ + case VIRGIN_ISLANDS_US = 'Virgin Islands (U.S.)'; + + /** + * @since 1.0.0 + */ + case WALLIS_AND_FUTUNA = 'Wallis and Futuna'; + + /** + * @since 1.0.0 + */ + case WESTERN_SAHARA = 'Western Sahara'; + + /** + * @since 1.0.0 + */ + case YEMEN = 'Yemen'; + + /** + * @since 1.0.0 + */ + case ZAMBIA = 'Zambia'; + + /** + * @since 1.0.0 + */ + case ZIMBABWE = 'Zimbabwe'; + + /** + * ### Get county from alpha 2 code + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::alpha2() To check alpha 2 code for country. + * + * @return null|self Returns country if found or null if country not found. + */ + public static function fromAlpha2 (string $code):?self { + + foreach (self::cases() as $case) + if ($case->alpha2() === $code) return $case; + + return null; + + } + + /** + * ### Get county from alpha 3 code + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::alpha3() To check alpha 3 code for country. + * + * @return null|self Returns country if found or null if country not found. + */ + public static function fromAlpha3 (string $code):?self { + + foreach (self::cases() as $case) + if ($case->alpha3() === $code) return $case; + + return null; + + } + + /** + * ### Get all country's from a provided region + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::is() To check if the country is a region. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region+ * The region to filter by. + *
+ * + * @return \FireHub\Core\Type\Geo\Country[] List of country's. + */ + public static function casesFrom (M49 $region):array { + + $cases = []; + + foreach (self::cases() as $case) + if ($case->is($region)) $cases[] = $case; + + return $cases; + + } + + /** + * ### Get all country's from a provided continent or ocean + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::continentOrOcean() To check a country's continent or ocean. + * + * @param \FireHub\Core\Type\Geo\Continent|\FireHub\Core\Type\Geo\Ocean $continent_or_ocean+ * Continent or ocean to filter by. + *
+ * + * @return \FireHub\Core\Type\Geo\Country[] List of country's. + */ + public static function casesFromContinentOrOcean (Continent|Ocean $continent_or_ocean):array { + + $cases = []; + + foreach (self::cases() as $case) + if ($case->continentOrOcean() === $continent_or_ocean) $cases[] = $case; + + return $cases; + + } + + /** + * ### Check if the country is a region + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\Geo\Country::check() To check country's region. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region+ * The region to check for. + *
+ * + * @return bool True if country is a region type, false otherwise. + */ + public function is (M49 $region):bool { + + return $this->check($region, $this); + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AFGHANISTAN => '004', + self::ALAND_ISLANDS => '248', + self::ALBANIA => '008', + self::ALGERIA => '012', + self::AMERICAN_SAMOA => '016', + self::ANDORRA => '020', + self::ANGOLA => '024', + self::ANGUILLA => '660', + self::ANTARCTICA => '010', + self::ANTIGUA_AND_BARBUDA => '028', + self::ARGENTINA => '032', + self::ARMENIA => '051', + self::ARUBA => '533', + self::AUSTRALIA => '036', + self::AUSTRIA => '040', + self::AZERBAIJAN => '031', + self::BAHAMAS => '044', + self::BAHRAIN => '048', + self::BANGLADESH => '050', + self::BARBADOS => '052', + self::BELARUS => '112', + self::BELGIUM => '056', + self::BELIZE => '084', + self::BENIN => '204', + self::BERMUDA => '060', + self::BHUTAN => '064', + self::BOLIVIA_PLURINATIONAL_STATE_OF => '068', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => '535', + self::BOSNIA_AND_HERZEGOVINA => '070', + self::BOTSWANA => '072', + self::BOUVET_ISLAND => '074', + self::BRAZIL => '076', + self::BRITISH_INDIAN_OCEAN_TERRITORY => '086', + self::BRUNEI_DARUSSALAM => '096', + self::BULGARIA => '100', + self::BURKINA_FASO => '854', + self::BURUNDI => '108', + self::CABO_VERDE => '132', + self::CAMBODIA => '116', + self::CAMEROON => '120', + self::CANADA => '124', + self::CAYMAN_ISLANDS => '136', + self::CENTRAL_AFRICAN_REPUBLIC => '140', + self::CHAD => '148', + self::CHILE => '152', + self::CHINA => '156', + self::CHRISTMAS_ISLAND => '162', + self::COCOS_KEELING_ISLANDS => '166', + self::COLOMBIA => '170', + self::COMOROS => '174', + self::CONGO => '178', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => '180', + self::COOK_ISLANDS => '184', + self::COSTA_RICA => '188', + self::COTE_D_IVOIRE => '384', + self::CROATIA => '191', + self::CUBA => '192', + self::CURACAO => '531', + self::CYPRUS => '196', + self::CZECHIA => '203', + self::DENMARK => '208', + self::DJIBOUTI => '262', + self::DOMINICA => '212', + self::DOMINICAN_REPUBLIC => '214', + self::ECUADOR => '218', + self::EGYPT => '818', + self::EL_SALVADOR => '222', + self::EQUATORIAL_GUINEA => '226', + self::ERITREA => '232', + self::ESTONIA => '233', + self::ESWATINI => '748', + self::ETHIOPIA => '231', + self::FALKLAND_ISLANDS_MALVINAS => '238', + self::FAROE_ISLANDS => '234', + self::FIJI => '242', + self::FINLAND => '246', + self::FRANCE => '250', + self::FRENCH_GUIANA => '254', + self::FRENCH_POLYNESIA => '258', + self::FRENCH_SOUTHERN_TERRITORIES => '260', + self::GABON => '266', + self::GAMBIA => '270', + self::GEORGIA => '268', + self::GERMANY => '276', + self::GHANA => '288', + self::GIBRALTAR => '292', + self::GREECE => '300', + self::GREENLAND => '304', + self::GRENADA => '308', + self::GUADELOUPE => '312', + self::GUAM => '316', + self::GUATEMALA => '320', + self::GUERNSEY => '831', + self::GUINEA => '324', + self::GUINEA_BISSAU => '624', + self::GUYANA => '328', + self::HAITI => '332', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => '334', + self::HOLY_SEE => '336', + self::HONDURAS => '340', + self::HONG_KONG => '344', + self::HUNGARY => '348', + self::ICELAND => '352', + self::INDIA => '356', + self::INDONESIA => '360', + self::IRAN_ISLAMIC_REPUBLIC_OF => '364', + self::IRAQ => '368', + self::IRELAND => '372', + self::ISLE_OF_MAN => '833', + self::ISRAEL => '376', + self::ITALY => '380', + self::JAMAICA => '388', + self::JAPAN => '392', + self::JERSEY => '832', + self::JORDAN => '400', + self::KAZAKHSTAN => '398', + self::KENYA => '404', + self::KIRIBATI => '296', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => '408', + self::KOREA_REPUBLIC_OF => '410', + self::KOSOVO => '412', + self::KUWAIT => '414', + self::KYRGYZSTAN => '417', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => '418', + self::LATVIA => '428', + self::LEBANON => '422', + self::LESOTHO => '426', + self::LIBERIA => '430', + self::LIBYA => '434', + self::LIECHTENSTEIN => '438', + self::LITHUANIA => '440', + self::LUXEMBOURG => '442', + self::MACAO => '446', + self::MADAGASCAR => '450', + self::MALAWI => '454', + self::MALAYSIA => '458', + self::MALDIVES => '462', + self::MALI => '466', + self::MALTA => '470', + self::MARSHALL_ISLANDS => '584', + self::MARTINIQUE => '474', + self::MAURITANIA => '478', + self::MAURITIUS => '480', + self::MAYOTTE => '175', + self::MEXICO => '484', + self::MICRONESIA_FEDERATED_STATES_OF => '583', + self::MOLDOVA_REPUBLIC_OF => '498', + self::MONACO => '492', + self::MONGOLIA => '496', + self::MONTENEGRO => '499', + self::MONTSERRAT => '500', + self::MOROCCO => '504', + self::MOZAMBIQUE => '508', + self::MYANMAR => '104', + self::NAMIBIA => '516', + self::NAURU => '520', + self::NEPAL => '524', + self::NETHERLANDS_KINGDOM_OF_THE => '528', + self::NEW_CALEDONIA => '540', + self::NEW_ZEALAND => '554', + self::NICARAGUA => '558', + self::NIGER => '562', + self::NIGERIA => '566', + self::NIUE => '570', + self::NORFOLK_ISLAND => '574', + self::NORTH_MACEDONIA => '807', + self::NORTHERN_MARIANA_ISLANDS => '580', + self::NORWAY => '578', + self::OMAN => '512', + self::PAKISTAN => '586', + self::PALAU => '585', + self::PALESTINE_STATE_OF => '275', + self::PANAMA => '591', + self::PAPUA_NEW_GUINEA => '598', + self::PARAGUAY => '600', + self::PERU => '604', + self::PHILIPPINES => '608', + self::PITCAIRN => '612', + self::POLAND => '616', + self::PORTUGAL => '620', + self::PUERTO_RICO => '630', + self::QATAR => '634', + self::REUNION => '638', + self::ROMANIA => '642', + self::RUSSIAN_FEDERATION => '643', + self::RWANDA => '646', + self::SAINT_BARTHELEMY => '652', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => '654', + self::SAINT_KITTS_AND_NEVIS => '659', + self::SAINT_LUCIA => '662', + self::SAINT_MARTIN_FRENCH_PART => '663', + self::SAINT_PIERRE_AND_MIQUELON => '666', + self::SAINT_VINCENT_AND_THE_GRENADINES => '670', + self::SAMOA => '882', + self::SAN_MARINO => '674', + self::SAO_TOME_AND_PRINCIPE => '678', + self::SAUDI_ARABIA => '682', + self::SENEGAL => '686', + self::SERBIA => '688', + self::SEYCHELLES => '690', + self::SIERRA_LEONE => '694', + self::SINGAPORE => '702', + self::SINT_MAARTEN_DUTCH_PART => '534', + self::SLOVAKIA => '703', + self::SLOVENIA => '705', + self::SOLOMON_ISLANDS => '090', + self::SOMALIA => '706', + self::SOUTH_AFRICA => '710', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => '239', + self::SOUTH_SUDAN => '728', + self::SPAIN => '724', + self::SRI_LANKA => '144', + self::SUDAN => '729', + self::SURINAME => '740', + self::SVALBARD_AND_JAN_MAYEN => '744', + self::SWEDEN => '752', + self::SWITZERLAND => '756', + self::SYRIAN_ARAB_REPUBLIC => '760', + self::TAIWAN_PROVINCE_OF_CHINA => '158', + self::TAJIKISTAN => '762', + self::TANZANIA_UNITED_REPUBLIC_OF => '834', + self::THAILAND => '764', + self::TIMOR_LESTE => '626', + self::TOGO => '768', + self::TOKELAU => '772', + self::TONGA => '776', + self::TRINIDAD_AND_TOBAGO => '780', + self::TUNISIA => '788', + self::TURKIYE => '792', + self::TURKMENISTAN => '795', + self::TURKS_AND_CAICOS_ISLANDS => '796', + self::TUVALU => '798', + self::UGANDA => '800', + self::UKRAINE => '804', + self::UNITED_ARAB_EMIRATES => '784', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => '826', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => '581', + self::UNITED_STATES_OF_AMERICA => '840', + self::URUGUAY => '858', + self::UZBEKISTAN => '860', + self::VANUATU => '548', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => '862', + self::VIET_NAM => '704', + self::VIRGIN_ISLANDS_BRITISH => '092', + self::VIRGIN_ISLANDS_US => '850', + self::WALLIS_AND_FUTUNA => '876', + self::WESTERN_SAHARA => '732', + self::YEMEN => '887', + self::ZAMBIA => '894', + self::ZIMBABWE => '716' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::AFGHANISTAN, self::BANGLADESH, self::BHUTAN, self::INDIA, self::IRAN_ISLAMIC_REPUBLIC_OF, + self::MALDIVES, self::NEPAL, self::PAKISTAN, self::SRI_LANKA + => SubRegion::SOUTHERN_ASIA, + self::ALAND_ISLANDS, self::DENMARK, self::ESTONIA, self::FAROE_ISLANDS, self::FINLAND, self::GUERNSEY, + self::ICELAND, self::IRELAND, self::ISLE_OF_MAN, self::JERSEY, self::LATVIA, self::LITHUANIA, self::NORWAY, + self::SVALBARD_AND_JAN_MAYEN, self::SWEDEN, self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND + => SubRegion::NORTHERN_EUROPE, + self::ALBANIA, self::ANDORRA, self::BOSNIA_AND_HERZEGOVINA, self::CROATIA, self::GIBRALTAR, self::GREECE, + self::HOLY_SEE, self::ITALY, self::KOSOVO, self::MALTA, self::MONTENEGRO, self::NORTH_MACEDONIA, + self::PORTUGAL, self::SAN_MARINO, self::SERBIA, self::SLOVENIA, self::SPAIN + => SubRegion::SOUTHERN_EUROPE, + self::ALGERIA, self::EGYPT, self::LIBYA, self::MOROCCO, self::SUDAN, self::TUNISIA, self::WESTERN_SAHARA + => SubRegion::NORTHERN_AFRICA, + self::AMERICAN_SAMOA, self::COOK_ISLANDS, self::FRENCH_POLYNESIA, self::NIUE, self::PITCAIRN, self::SAMOA, + self::TOKELAU, self::TONGA, self::TUVALU, self::WALLIS_AND_FUTUNA + => SubRegion::POLYNESIA, + self::ANGOLA, self::CAMEROON, self::CENTRAL_AFRICAN_REPUBLIC, self::CHAD, self::CONGO, + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE, self::EQUATORIAL_GUINEA, self::GABON, + self::SAO_TOME_AND_PRINCIPE + => IntermediateRegion::MIDDLE_AFRICA, + self::ANGUILLA, self::ANTIGUA_AND_BARBUDA, self::ARUBA, self::BAHAMAS, self::BARBADOS, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::CAYMAN_ISLANDS, self::CUBA, self::CURACAO, self::DOMINICA, + self::DOMINICAN_REPUBLIC, self::GRENADA, self::GUADELOUPE, self::HAITI, self::JAMAICA, self::MARTINIQUE, + self::MONTSERRAT, self::PUERTO_RICO, self::SAINT_BARTHELEMY, self::SAINT_KITTS_AND_NEVIS, self::SAINT_LUCIA, + self::SAINT_MARTIN_FRENCH_PART, self::SAINT_VINCENT_AND_THE_GRENADINES, self::SINT_MAARTEN_DUTCH_PART, + self::TRINIDAD_AND_TOBAGO, self::TURKS_AND_CAICOS_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, + self::VIRGIN_ISLANDS_US + => IntermediateRegion::CARIBBEAN, + self::ANTARCTICA + => Region::ANTARCTICA, + self::ARGENTINA, self::BOLIVIA_PLURINATIONAL_STATE_OF, self::BOUVET_ISLAND, self::BRAZIL, self::CHILE, + self::COLOMBIA, self::ECUADOR, self::FALKLAND_ISLANDS_MALVINAS, self::FRENCH_GUIANA, self::GUYANA, + self::PARAGUAY, self::PERU, self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SURINAME, + self::URUGUAY, self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF + => IntermediateRegion::SOUTH_AMERICA, + self::ARMENIA, self::AZERBAIJAN, self::BAHRAIN, self::CYPRUS, self::GEORGIA, self::IRAQ, self::ISRAEL, + self::JORDAN, self::KUWAIT, self::LEBANON, self::OMAN, self::PALESTINE_STATE_OF, self::QATAR, + self::SAUDI_ARABIA, self::SYRIAN_ARAB_REPUBLIC, self::TURKIYE, self::UNITED_ARAB_EMIRATES, + self::YEMEN + => SubRegion::WESTERN_ASIA, + self::AUSTRALIA, self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, self::NEW_ZEALAND, + self::NORFOLK_ISLAND + => SubRegion::AUSTRALIA_AND_NEW_ZEALAND, + self::AUSTRIA, self::BELGIUM, self::FRANCE, self::GERMANY, self::LIECHTENSTEIN, self::LUXEMBOURG, + self::MONACO, self::NETHERLANDS_KINGDOM_OF_THE, self::SWITZERLAND + => SubRegion::WESTERN_EUROPE, + self::BELARUS, self::BULGARIA, self::CZECHIA, self::HUNGARY, self::MOLDOVA_REPUBLIC_OF, self::POLAND, + self::ROMANIA, self::RUSSIAN_FEDERATION, self::SLOVAKIA, self::UKRAINE + => SubRegion::EASTERN_EUROPE, + self::BELIZE, self::COSTA_RICA, self::EL_SALVADOR, self::GUATEMALA, self::HONDURAS, self::MEXICO, + self::NICARAGUA, self::PANAMA + => IntermediateRegion::CENTRAL_AMERICA, + self::BENIN, self::BURKINA_FASO, self::CABO_VERDE, self::COTE_D_IVOIRE, self::GAMBIA, self::GHANA, + self::GUINEA, self::GUINEA_BISSAU, self::LIBERIA, self::MALI, self::MAURITANIA, self::NIGER, self::NIGERIA, + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SENEGAL, self::SIERRA_LEONE, + self::TOGO + => IntermediateRegion::WESTERN_AFRICA, + self::BERMUDA, self::CANADA, self::GREENLAND, self::SAINT_PIERRE_AND_MIQUELON, self::UNITED_STATES_OF_AMERICA + => SubRegion::NORTHERN_AMERICA, + self::BOTSWANA, self::ESWATINI, self::LESOTHO, self::NAMIBIA, self::SOUTH_AFRICA + => IntermediateRegion::SOUTHERN_AFRICA, + self::BRITISH_INDIAN_OCEAN_TERRITORY, self::BURUNDI, self::COMOROS, self::DJIBOUTI, self::ERITREA, + self::ETHIOPIA, self::FRENCH_SOUTHERN_TERRITORIES, self::KENYA, self::MADAGASCAR, self::MALAWI, + self::MAURITIUS, self::MAYOTTE, self::MOZAMBIQUE, self::REUNION, self::RWANDA, self::SEYCHELLES, + self::SOMALIA, self::SOUTH_SUDAN, self::TANZANIA_UNITED_REPUBLIC_OF, self::UGANDA, self::ZAMBIA, + self::ZIMBABWE + => IntermediateRegion::EASTERN_AFRICA, + self::BRUNEI_DARUSSALAM, self::CAMBODIA, self::INDONESIA, self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC, + self::MALAYSIA, self::MYANMAR, self::PHILIPPINES, self::SINGAPORE, self::THAILAND, self::TIMOR_LESTE, + self::VIET_NAM + => SubRegion::SOUTH_EASTERN_ASIA, + self::CHINA, self::HONG_KONG, self::JAPAN, self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF, + self::KOREA_REPUBLIC_OF, self::MACAO, self::MONGOLIA, self::TAIWAN_PROVINCE_OF_CHINA + => SubRegion::EASTERN_ASIA, + self::FIJI, self::NEW_CALEDONIA, self::PAPUA_NEW_GUINEA, self::SOLOMON_ISLANDS, self::VANUATU + => SubRegion::MELANESIA, + self::GUAM, self::KIRIBATI, self::MARSHALL_ISLANDS, self::MICRONESIA_FEDERATED_STATES_OF, self::NAURU, + self::NORTHERN_MARIANA_ISLANDS, self::PALAU, self::UNITED_STATES_MINOR_OUTLYING_ISLANDS + => SubRegion::MICRONESIA, + self::KAZAKHSTAN, self::KYRGYZSTAN, self::TAJIKISTAN, self::TURKMENISTAN, self::UZBEKISTAN + => SubRegion::CENTRAL_ASIA + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function alpha2 ():string { + + return match ($this) { + self::AFGHANISTAN => 'AF', + self::ALAND_ISLANDS => 'AX', + self::ALBANIA => 'AL', + self::ALGERIA => 'DZ', + self::AMERICAN_SAMOA => 'AS', + self::ANDORRA => 'AD', + self::ANGOLA => 'AO', + self::ANGUILLA => 'AI', + self::ANTARCTICA => 'AQ', + self::ANTIGUA_AND_BARBUDA => 'AG', + self::ARGENTINA => 'AR', + self::ARMENIA => 'AM', + self::ARUBA => 'AW', + self::AUSTRALIA => 'AU', + self::AUSTRIA => 'AT', + self::AZERBAIJAN => 'AZ', + self::BAHAMAS => 'BS', + self::BAHRAIN => 'BH', + self::BANGLADESH => 'BD', + self::BARBADOS => 'BB', + self::BELARUS => 'BY', + self::BELGIUM => 'BE', + self::BELIZE => 'BZ', + self::BENIN => 'BJ', + self::BERMUDA => 'BM', + self::BHUTAN => 'BT', + self::BOLIVIA_PLURINATIONAL_STATE_OF => 'BO', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => 'BQ', + self::BOSNIA_AND_HERZEGOVINA => 'BA', + self::BOTSWANA => 'BW', + self::BOUVET_ISLAND => 'BV', + self::BRAZIL => 'BR', + self::BRITISH_INDIAN_OCEAN_TERRITORY => 'IO', + self::BRUNEI_DARUSSALAM => 'BN', + self::BULGARIA => 'BG', + self::BURKINA_FASO => 'BF', + self::BURUNDI => 'BI', + self::CABO_VERDE => 'CV', + self::CAMBODIA => 'KH', + self::CAMEROON => 'CM', + self::CANADA => 'CA', + self::CAYMAN_ISLANDS => 'KY', + self::CENTRAL_AFRICAN_REPUBLIC => 'CF', + self::CHAD => 'TD', + self::CHILE => 'CL', + self::CHINA => 'CN', + self::CHRISTMAS_ISLAND => 'CX', + self::COCOS_KEELING_ISLANDS => 'CC', + self::COLOMBIA => 'CO', + self::COMOROS => 'KM', + self::CONGO => 'CG', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => 'CD', + self::COOK_ISLANDS => 'CK', + self::COSTA_RICA => 'CR', + self::COTE_D_IVOIRE => 'CI', + self::CROATIA => 'HR', + self::CUBA => 'CU', + self::CURACAO => 'CW', + self::CYPRUS => 'CY', + self::CZECHIA => 'CZ', + self::DENMARK => 'DK', + self::DJIBOUTI => 'DJ', + self::DOMINICA => 'DM', + self::DOMINICAN_REPUBLIC => 'DO', + self::ECUADOR => 'EC', + self::EGYPT => 'EG', + self::EL_SALVADOR => 'SV', + self::EQUATORIAL_GUINEA => 'GQ', + self::ERITREA => 'ER', + self::ESTONIA => 'EE', + self::ESWATINI => 'SZ', + self::ETHIOPIA => 'ET', + self::FALKLAND_ISLANDS_MALVINAS => 'FK', + self::FAROE_ISLANDS => 'FO', + self::FIJI => 'FJ', + self::FINLAND => 'FI', + self::FRANCE => 'FR', + self::FRENCH_GUIANA => 'GF', + self::FRENCH_POLYNESIA => 'PF', + self::FRENCH_SOUTHERN_TERRITORIES => 'TF', + self::GABON => 'GA', + self::GAMBIA => 'GM', + self::GEORGIA => 'GE', + self::GERMANY => 'DE', + self::GHANA => 'GH', + self::GIBRALTAR => 'GI', + self::GREECE => 'GR', + self::GREENLAND => 'GL', + self::GRENADA => 'GD', + self::GUADELOUPE => 'GP', + self::GUAM => 'GU', + self::GUATEMALA => 'GT', + self::GUERNSEY => 'GG', + self::GUINEA => 'GN', + self::GUINEA_BISSAU => 'GW', + self::GUYANA => 'GY', + self::HAITI => 'HT', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => 'HM', + self::HOLY_SEE => 'VA', + self::HONDURAS => 'HN', + self::HONG_KONG => 'HK', + self::HUNGARY => 'HU', + self::ICELAND => 'IS', + self::INDIA => 'IN', + self::INDONESIA => 'ID', + self::IRAN_ISLAMIC_REPUBLIC_OF => 'IR', + self::IRAQ => 'IQ', + self::IRELAND => 'IE', + self::ISLE_OF_MAN => 'IM', + self::ISRAEL => 'IL', + self::ITALY => 'IT', + self::JAMAICA => 'JM', + self::JAPAN => 'JP', + self::JERSEY => 'JE', + self::JORDAN => 'JO', + self::KAZAKHSTAN => 'KZ', + self::KENYA => 'KE', + self::KIRIBATI => 'KI', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => 'KP', + self::KOREA_REPUBLIC_OF => 'KR', + self::KOSOVO => 'XK', + self::KUWAIT => 'KW', + self::KYRGYZSTAN => 'KG', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => 'LA', + self::LATVIA => 'LV', + self::LEBANON => 'LB', + self::LESOTHO => 'LS', + self::LIBERIA => 'LR', + self::LIBYA => 'LY', + self::LIECHTENSTEIN => 'LI', + self::LITHUANIA => 'LT', + self::LUXEMBOURG => 'LU', + self::MACAO => 'MO', + self::MADAGASCAR => 'MG', + self::MALAWI => 'MW', + self::MALAYSIA => 'MY', + self::MALDIVES => 'MV', + self::MALI => 'ML', + self::MALTA => 'MT', + self::MARSHALL_ISLANDS => 'MH', + self::MARTINIQUE => 'MQ', + self::MAURITANIA => 'MR', + self::MAURITIUS => 'MU', + self::MAYOTTE => 'YT', + self::MEXICO => 'MX', + self::MICRONESIA_FEDERATED_STATES_OF => 'FM', + self::MOLDOVA_REPUBLIC_OF => 'MD', + self::MONACO => 'MC', + self::MONGOLIA => 'MN', + self::MONTENEGRO => 'ME', + self::MONTSERRAT => 'MS', + self::MOROCCO => 'MA', + self::MOZAMBIQUE => 'MZ', + self::MYANMAR => 'MM', + self::NAMIBIA => 'NA', + self::NAURU => 'NR', + self::NEPAL => 'NP', + self::NETHERLANDS_KINGDOM_OF_THE => 'NL', + self::NEW_CALEDONIA => 'NC', + self::NEW_ZEALAND => 'NZ', + self::NICARAGUA => 'NI', + self::NIGER => 'NE', + self::NIGERIA => 'NG', + self::NIUE => 'NU', + self::NORFOLK_ISLAND => 'NF', + self::NORTH_MACEDONIA => 'MK', + self::NORTHERN_MARIANA_ISLANDS => 'MP', + self::NORWAY => 'NO', + self::OMAN => 'OM', + self::PAKISTAN => 'PK', + self::PALAU => 'PW', + self::PALESTINE_STATE_OF => 'PS', + self::PANAMA => 'PA', + self::PAPUA_NEW_GUINEA => 'PG', + self::PARAGUAY => 'PY', + self::PERU => 'PE', + self::PHILIPPINES => 'PH', + self::PITCAIRN => 'PN', + self::POLAND => 'PL', + self::PORTUGAL => 'PT', + self::PUERTO_RICO => 'PR', + self::QATAR => 'QA', + self::REUNION => 'RE', + self::ROMANIA => 'RO', + self::RUSSIAN_FEDERATION => 'RU', + self::RWANDA => 'RW', + self::SAINT_BARTHELEMY => 'BL', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => 'SH', + self::SAINT_KITTS_AND_NEVIS => 'KN', + self::SAINT_LUCIA => 'LC', + self::SAINT_MARTIN_FRENCH_PART => 'MF', + self::SAINT_PIERRE_AND_MIQUELON => 'PM', + self::SAINT_VINCENT_AND_THE_GRENADINES => 'VC', + self::SAMOA => 'WS', + self::SAN_MARINO => 'SM', + self::SAO_TOME_AND_PRINCIPE => 'ST', + self::SAUDI_ARABIA => 'SA', + self::SENEGAL => 'SN', + self::SERBIA => 'RS', + self::SEYCHELLES => 'SC', + self::SIERRA_LEONE => 'SL', + self::SINGAPORE => 'SG', + self::SINT_MAARTEN_DUTCH_PART => 'SX', + self::SLOVAKIA => 'SK', + self::SLOVENIA => 'SI', + self::SOLOMON_ISLANDS => 'SB', + self::SOMALIA => 'SO', + self::SOUTH_AFRICA => 'ZA', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => 'GS', + self::SOUTH_SUDAN => 'SS', + self::SPAIN => 'ES', + self::SRI_LANKA => 'LK', + self::SUDAN => 'SD', + self::SURINAME => 'SR', + self::SVALBARD_AND_JAN_MAYEN => 'SJ', + self::SWEDEN => 'SE', + self::SWITZERLAND => 'CH', + self::SYRIAN_ARAB_REPUBLIC => 'SY', + self::TAIWAN_PROVINCE_OF_CHINA => 'TW', + self::TAJIKISTAN => 'TJ', + self::TANZANIA_UNITED_REPUBLIC_OF => 'TZ', + self::THAILAND => 'TH', + self::TIMOR_LESTE => 'TL', + self::TOGO => 'TG', + self::TOKELAU => 'TK', + self::TONGA => 'TO', + self::TRINIDAD_AND_TOBAGO => 'TT', + self::TUNISIA => 'TN', + self::TURKIYE => 'TR', + self::TURKMENISTAN => 'TM', + self::TURKS_AND_CAICOS_ISLANDS => 'TC', + self::TUVALU => 'TV', + self::UGANDA => 'UG', + self::UKRAINE => 'UA', + self::UNITED_ARAB_EMIRATES => 'AE', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => 'GB', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => 'UM', + self::UNITED_STATES_OF_AMERICA => 'US', + self::URUGUAY => 'UY', + self::UZBEKISTAN => 'UZ', + self::VANUATU => 'VU', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => 'VE', + self::VIET_NAM => 'VN', + self::VIRGIN_ISLANDS_BRITISH => 'VG', + self::VIRGIN_ISLANDS_US => 'VI', + self::WALLIS_AND_FUTUNA => 'WF', + self::WESTERN_SAHARA => 'EH', + self::YEMEN => 'YE', + self::ZAMBIA => 'ZM', + self::ZIMBABWE => 'ZW' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function alpha3 ():string { + + return match ($this) { + self::AFGHANISTAN => 'AFG', + self::ALAND_ISLANDS => 'ALA', + self::ALBANIA => 'ALB', + self::ALGERIA => 'DZA', + self::AMERICAN_SAMOA => 'ASM', + self::ANDORRA => 'AND', + self::ANGOLA => 'AGO', + self::ANGUILLA => 'AIA', + self::ANTARCTICA => 'ATA', + self::ANTIGUA_AND_BARBUDA => 'ATG', + self::ARGENTINA => 'ARG', + self::ARMENIA => 'ARM', + self::ARUBA => 'ABW', + self::AUSTRALIA => 'AUS', + self::AUSTRIA => 'AUT', + self::AZERBAIJAN => 'AZE', + self::BAHAMAS => 'BHS', + self::BAHRAIN => 'BHR', + self::BANGLADESH => 'BGD', + self::BARBADOS => 'BRB', + self::BELARUS => 'BLR', + self::BELGIUM => 'BEL', + self::BELIZE => 'BLZ', + self::BENIN => 'BEN', + self::BERMUDA => 'BMU', + self::BHUTAN => 'BTN', + self::BOLIVIA_PLURINATIONAL_STATE_OF => 'BOL', + self::BONAIRE_SINT_EUSTATIUS_AND_SABA => 'BES', + self::BOSNIA_AND_HERZEGOVINA => 'BIH', + self::BOTSWANA => 'BWA', + self::BOUVET_ISLAND => 'BVT', + self::BRAZIL => 'BRA', + self::BRITISH_INDIAN_OCEAN_TERRITORY => 'IOT', + self::BRUNEI_DARUSSALAM => 'BRN', + self::BULGARIA => 'BGR', + self::BURKINA_FASO => 'BFA', + self::BURUNDI => 'BDI', + self::CABO_VERDE => 'CPV', + self::CAMBODIA => 'KHM', + self::CAMEROON => 'CMR', + self::CANADA => 'CAN', + self::CAYMAN_ISLANDS => 'CYM', + self::CENTRAL_AFRICAN_REPUBLIC => 'CAF', + self::CHAD => 'TCD', + self::CHILE => 'CHL', + self::CHINA => 'CHN', + self::CHRISTMAS_ISLAND => 'CXR', + self::COCOS_KEELING_ISLANDS => 'CCK', + self::COLOMBIA => 'COL', + self::COMOROS => 'COM', + self::CONGO => 'COG', + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE => 'COD', + self::COOK_ISLANDS => 'COK', + self::COSTA_RICA => 'CRI', + self::COTE_D_IVOIRE => 'CIV', + self::CROATIA => 'HRV', + self::CUBA => 'CUB', + self::CURACAO => 'CUW', + self::CYPRUS => 'CYP', + self::CZECHIA => 'CZE', + self::DENMARK => 'DNK', + self::DJIBOUTI => 'DJI', + self::DOMINICA => 'DMA', + self::DOMINICAN_REPUBLIC => 'DOM', + self::ECUADOR => 'ECU', + self::EGYPT => 'EGY', + self::EL_SALVADOR => 'SLV', + self::EQUATORIAL_GUINEA => 'GNQ', + self::ERITREA => 'ERI', + self::ESTONIA => 'EST', + self::ESWATINI => 'SWZ', + self::ETHIOPIA => 'ETH', + self::FALKLAND_ISLANDS_MALVINAS => 'FLK', + self::FAROE_ISLANDS => 'FRO', + self::FIJI => 'FJI', + self::FINLAND => 'FIN', + self::FRANCE => 'FRA', + self::FRENCH_GUIANA => 'GUF', + self::FRENCH_POLYNESIA => 'PYF', + self::FRENCH_SOUTHERN_TERRITORIES => 'ATF', + self::GABON => 'GAB', + self::GAMBIA => 'GMB', + self::GEORGIA => 'GEO', + self::GERMANY => 'DEU', + self::GHANA => 'GHA', + self::GIBRALTAR => 'GIB', + self::GREECE => 'GRC', + self::GREENLAND => 'GRL', + self::GRENADA => 'GRD', + self::GUADELOUPE => 'GLP', + self::GUAM => 'GUM', + self::GUATEMALA => 'GTM', + self::GUERNSEY => 'GGY', + self::GUINEA => 'GIN', + self::GUINEA_BISSAU => 'GNB', + self::GUYANA => 'GUY', + self::HAITI => 'HTI', + self::HEARD_ISLAND_AND_MCDONALD_ISLANDS => 'HMD', + self::HOLY_SEE => 'VAT', + self::HONDURAS => 'HND', + self::HONG_KONG => 'HKG', + self::HUNGARY => 'HUN', + self::ICELAND => 'ISL', + self::INDIA => 'IND', + self::INDONESIA => 'IDN', + self::IRAN_ISLAMIC_REPUBLIC_OF => 'IRN', + self::IRAQ => 'IRQ', + self::IRELAND => 'IRL', + self::ISLE_OF_MAN => 'IMN', + self::ISRAEL => 'ISR', + self::ITALY => 'ITA', + self::JAMAICA => 'JAM', + self::JAPAN => 'JPN', + self::JERSEY => 'JEY', + self::JORDAN => 'JOR', + self::KAZAKHSTAN => 'KAZ', + self::KENYA => 'KEN', + self::KIRIBATI => 'KIR', + self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF => 'PRK', + self::KOREA_REPUBLIC_OF => 'KOR', + self::KOSOVO => 'UNK', + self::KUWAIT => 'KWT', + self::KYRGYZSTAN => 'KGZ', + self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC => 'LAO', + self::LATVIA => 'LVA', + self::LEBANON => 'LBN', + self::LESOTHO => 'LSO', + self::LIBERIA => 'LBR', + self::LIBYA => 'LBY', + self::LIECHTENSTEIN => 'LIE', + self::LITHUANIA => 'LTU', + self::LUXEMBOURG => 'LUX', + self::MACAO => 'MAC', + self::MADAGASCAR => 'MDG', + self::MALAWI => 'MWI', + self::MALAYSIA => 'MYS', + self::MALDIVES => 'MDV', + self::MALI => 'MLI', + self::MALTA => 'MLT', + self::MARSHALL_ISLANDS => 'MHL', + self::MARTINIQUE => 'MTQ', + self::MAURITANIA => 'MRT', + self::MAURITIUS => 'MUS', + self::MAYOTTE => 'MYT', + self::MEXICO => 'MEX', + self::MICRONESIA_FEDERATED_STATES_OF => 'FSM', + self::MOLDOVA_REPUBLIC_OF => 'MDA', + self::MONACO => 'MCO', + self::MONGOLIA => 'MNG', + self::MONTENEGRO => 'MNE', + self::MONTSERRAT => 'MSR', + self::MOROCCO => 'MAR', + self::MOZAMBIQUE => 'MOZ', + self::MYANMAR => 'MMR', + self::NAMIBIA => 'NAM', + self::NAURU => 'NRU', + self::NEPAL => 'NPL', + self::NETHERLANDS_KINGDOM_OF_THE => 'NLD', + self::NEW_CALEDONIA => 'NCL', + self::NEW_ZEALAND => 'NZL', + self::NICARAGUA => 'NIC', + self::NIGER => 'NER', + self::NIGERIA => 'NGA', + self::NIUE => 'NIU', + self::NORFOLK_ISLAND => 'NFK', + self::NORTH_MACEDONIA => 'MKD', + self::NORTHERN_MARIANA_ISLANDS => 'MNP', + self::NORWAY => 'NOR', + self::OMAN => 'OMN', + self::PAKISTAN => 'PAK', + self::PALAU => 'PLW', + self::PALESTINE_STATE_OF => 'PSE', + self::PANAMA => 'PAN', + self::PAPUA_NEW_GUINEA => 'PNG', + self::PARAGUAY => 'PRY', + self::PERU => 'PER', + self::PHILIPPINES => 'PHL', + self::PITCAIRN => 'PCN', + self::POLAND => 'POL', + self::PORTUGAL => 'PRT', + self::PUERTO_RICO => 'PRI', + self::QATAR => 'QAT', + self::REUNION => 'REU', + self::ROMANIA => 'ROU', + self::RUSSIAN_FEDERATION => 'RUS', + self::RWANDA => 'RWA', + self::SAINT_BARTHELEMY => 'BLM', + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA => 'SHN', + self::SAINT_KITTS_AND_NEVIS => 'KNA', + self::SAINT_LUCIA => 'LCA', + self::SAINT_MARTIN_FRENCH_PART => 'MAF', + self::SAINT_PIERRE_AND_MIQUELON => 'SPM', + self::SAINT_VINCENT_AND_THE_GRENADINES => 'VCT', + self::SAMOA => 'WSM', + self::SAN_MARINO => 'SMR', + self::SAO_TOME_AND_PRINCIPE => 'STP', + self::SAUDI_ARABIA => 'SAU', + self::SENEGAL => 'SEN', + self::SERBIA => 'SRB', + self::SEYCHELLES => 'SYC', + self::SIERRA_LEONE => 'SLE', + self::SINGAPORE => 'SGP', + self::SINT_MAARTEN_DUTCH_PART => 'SXM', + self::SLOVAKIA => 'SVK', + self::SLOVENIA => 'SVN', + self::SOLOMON_ISLANDS => 'SLB', + self::SOMALIA => 'SOM', + self::SOUTH_AFRICA => 'ZAF', + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS => 'SGS', + self::SOUTH_SUDAN => 'SSD', + self::SPAIN => 'ESP', + self::SRI_LANKA => 'LKA', + self::SUDAN => 'SDN', + self::SURINAME => 'SUR', + self::SVALBARD_AND_JAN_MAYEN => 'SJM', + self::SWEDEN => 'SWE', + self::SWITZERLAND => 'CHE', + self::SYRIAN_ARAB_REPUBLIC => 'SYR', + self::TAIWAN_PROVINCE_OF_CHINA => 'TWN', + self::TAJIKISTAN => 'TJK', + self::TANZANIA_UNITED_REPUBLIC_OF => 'TZA', + self::THAILAND => 'THA', + self::TIMOR_LESTE => 'TLS', + self::TOGO => 'TGO', + self::TOKELAU => 'TKL', + self::TONGA => 'TON', + self::TRINIDAD_AND_TOBAGO => 'TTO', + self::TUNISIA => 'TUN', + self::TURKIYE => 'TUR', + self::TURKMENISTAN => 'TKM', + self::TURKS_AND_CAICOS_ISLANDS => 'TCA', + self::TUVALU => 'TUV', + self::UGANDA => 'UGA', + self::UKRAINE => 'UKR', + self::UNITED_ARAB_EMIRATES => 'ARE', + self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND => 'GBR', + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS => 'UMI', + self::UNITED_STATES_OF_AMERICA => 'USA', + self::URUGUAY => 'URY', + self::UZBEKISTAN => 'UZB', + self::VANUATU => 'VUT', + self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF => 'VEN', + self::VIET_NAM => 'VNM', + self::VIRGIN_ISLANDS_BRITISH => 'VGB', + self::VIRGIN_ISLANDS_US => 'VIR', + self::WALLIS_AND_FUTUNA => 'WLF', + self::WESTERN_SAHARA => 'ESH', + self::YEMEN => 'YEM', + self::ZAMBIA => 'ZMB', + self::ZIMBABWE => 'ZWE' + }; + + } + + /** + * ### Country's continent or ocean + * @since 1.0.0 + * + * @return \FireHub\Core\Type\Geo\Continent|\FireHub\Core\Type\Geo\Ocean Country's continent or ocean. + */ + public function continentOrOcean ():Continent|Ocean { + + return match ($this) { + self::AFGHANISTAN, self::BANGLADESH, self::BHUTAN, self::INDIA, self::IRAN_ISLAMIC_REPUBLIC_OF, + self::MALDIVES, self::NEPAL, self::PAKISTAN, self::SRI_LANKA, self::ARMENIA, self::AZERBAIJAN, + self::BAHRAIN, self::CYPRUS, self::GEORGIA, self::IRAQ, self::ISRAEL, self::JORDAN, self::KUWAIT, + self::LEBANON, self::OMAN, self::PALESTINE_STATE_OF, self::QATAR, self::SAUDI_ARABIA, + self::SYRIAN_ARAB_REPUBLIC, self::TURKIYE, self::UNITED_ARAB_EMIRATES, self::YEMEN, + self::BRUNEI_DARUSSALAM, self::CAMBODIA, self::INDONESIA, self::LAO_PEOPLES_DEMOCRATIC_REPUBLIC, + self::MALAYSIA, self::MYANMAR, self::PHILIPPINES, self::SINGAPORE, self::THAILAND, self::TIMOR_LESTE, + self::VIET_NAM, self::CHINA, self::HONG_KONG, self::JAPAN, self::KOREA_DEMOCRATIC_PEOPLES_REPUBLIC_OF, + self::KOREA_REPUBLIC_OF, self::MACAO, self::MONGOLIA, self::TAIWAN_PROVINCE_OF_CHINA, self::KAZAKHSTAN, + self::KYRGYZSTAN, self::TAJIKISTAN, self::TURKMENISTAN, self::UZBEKISTAN + => Continent::ASIA, + self::ALAND_ISLANDS, self::DENMARK, self::ESTONIA, self::FAROE_ISLANDS, self::FINLAND, self::GUERNSEY, + self::ICELAND, self::IRELAND, self::ISLE_OF_MAN, self::JERSEY, self::LATVIA, self::LITHUANIA, self::NORWAY, + self::SVALBARD_AND_JAN_MAYEN, self::SWEDEN, self::UNITED_KINGDOM_OF_GREAT_BRITAIN_AND_NORTHERN_IRELAND, + self::ALBANIA, self::ANDORRA, self::BOSNIA_AND_HERZEGOVINA, self::CROATIA, self::GIBRALTAR, self::GREECE, + self::HOLY_SEE, self::ITALY, self::KOSOVO, self::MALTA, self::MONTENEGRO, self::NORTH_MACEDONIA, + self::PORTUGAL, self::SAN_MARINO, self::SERBIA, self::SLOVENIA, self::SPAIN, self::AUSTRIA, + self::BELGIUM, self::FRANCE, self::GERMANY, self::LIECHTENSTEIN, self::LUXEMBOURG, self::MONACO, + self::NETHERLANDS_KINGDOM_OF_THE, self::SWITZERLAND, self::BELARUS, self::BULGARIA, self::CZECHIA, + self::HUNGARY, self::MOLDOVA_REPUBLIC_OF, self::POLAND, self::ROMANIA, self::RUSSIAN_FEDERATION, + self::SLOVAKIA, self::UKRAINE + => Continent::EUROPE, + self::ALGERIA, self::EGYPT, self::LIBYA, self::MOROCCO, self::SUDAN, self::TUNISIA, self::WESTERN_SAHARA, + self::ANGOLA, self::CAMEROON, self::CENTRAL_AFRICAN_REPUBLIC, self::CHAD, self::CONGO, + self::CONGO_DEMOCRATIC_REPUBLIC_OF_THE, self::EQUATORIAL_GUINEA, self::GABON, self::SAO_TOME_AND_PRINCIPE, + self::BOTSWANA, self::ESWATINI, self::LESOTHO, self::NAMIBIA, self::SOUTH_AFRICA, + self::BRITISH_INDIAN_OCEAN_TERRITORY, self::BURUNDI, self::COMOROS, self::DJIBOUTI, self::ERITREA, + self::ETHIOPIA, self::FRENCH_SOUTHERN_TERRITORIES, self::KENYA, self::MADAGASCAR, self::MALAWI, + self::MAURITIUS, self::MAYOTTE, self::MOZAMBIQUE, self::REUNION, self::RWANDA, self::SEYCHELLES, + self::SOMALIA, self::SOUTH_SUDAN, self::TANZANIA_UNITED_REPUBLIC_OF, self::UGANDA, self::ZAMBIA, + self::ZIMBABWE, self::BENIN, self::BURKINA_FASO, self::CABO_VERDE, self::COTE_D_IVOIRE, self::GAMBIA, + self::GHANA, self::GUINEA, self::GUINEA_BISSAU, self::LIBERIA, self::MALI, self::MAURITANIA, self::NIGER, + self::NIGERIA, self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SENEGAL, self::SIERRA_LEONE, + self::TOGO + => Continent::AFRICA, + self::AMERICAN_SAMOA, self::COOK_ISLANDS, self::FRENCH_POLYNESIA, self::NIUE, self::PITCAIRN, self::SAMOA, + self::TOKELAU, self::TONGA, self::TUVALU, self::WALLIS_AND_FUTUNA, self::FIJI, self::NEW_CALEDONIA, + self::PAPUA_NEW_GUINEA, self::SOLOMON_ISLANDS, self::VANUATU, self::GUAM, self::KIRIBATI, + self::MARSHALL_ISLANDS, self::MICRONESIA_FEDERATED_STATES_OF, self::NAURU, + self::NORTHERN_MARIANA_ISLANDS, self::PALAU, self::UNITED_STATES_MINOR_OUTLYING_ISLANDS, + self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, + self::NEW_ZEALAND, self::NORFOLK_ISLAND + => Ocean::PACIFIC, + self::ANGUILLA, self::ANTIGUA_AND_BARBUDA, self::ARUBA, self::BAHAMAS, self::BARBADOS, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::CAYMAN_ISLANDS, self::CUBA, self::CURACAO, self::DOMINICA, + self::DOMINICAN_REPUBLIC, self::GRENADA, self::GUADELOUPE, self::HAITI, self::JAMAICA, self::MARTINIQUE, + self::MONTSERRAT, self::PUERTO_RICO, self::SAINT_BARTHELEMY, self::SAINT_KITTS_AND_NEVIS, self::SAINT_LUCIA, + self::SAINT_MARTIN_FRENCH_PART, self::SAINT_VINCENT_AND_THE_GRENADINES, self::SINT_MAARTEN_DUTCH_PART, + self::TRINIDAD_AND_TOBAGO, self::TURKS_AND_CAICOS_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, + self::VIRGIN_ISLANDS_US, self::BERMUDA, self::CANADA, self::GREENLAND, self::SAINT_PIERRE_AND_MIQUELON, + self::UNITED_STATES_OF_AMERICA, self::BELIZE, self::COSTA_RICA, self::EL_SALVADOR, self::GUATEMALA, + self::HONDURAS, self::MEXICO, self::NICARAGUA, self::PANAMA + => Continent::NORTH_AMERICA, + self::ANTARCTICA + => Continent::ANTARCTICA, + self::ARGENTINA, self::BOLIVIA_PLURINATIONAL_STATE_OF, self::BOUVET_ISLAND, self::BRAZIL, self::CHILE, + self::COLOMBIA, self::ECUADOR, self::FALKLAND_ISLANDS_MALVINAS, self::FRENCH_GUIANA, self::GUYANA, + self::PARAGUAY, self::PERU, self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SURINAME, + self::URUGUAY, self::VENEZUELA_BOLIVARIAN_REPUBLIC_OF + => Continent::SOUTH_AMERICA, + self::AUSTRALIA + => Continent::AUSTRALIA + }; + + } + + /** + * ### Checks if the country is independent or not + * @since 1.0.0 + * + * @return bool True if country is independent, false otherwise. + */ + public function independent ():bool { + + return match ($this) { + self::ALAND_ISLANDS, self::AMERICAN_SAMOA, self::ANGUILLA, self::ANTARCTICA, self::ARUBA, self::BERMUDA, + self::BONAIRE_SINT_EUSTATIUS_AND_SABA, self::BOUVET_ISLAND, self::BRITISH_INDIAN_OCEAN_TERRITORY, + self::CAYMAN_ISLANDS, self::CHRISTMAS_ISLAND, self::COCOS_KEELING_ISLANDS, self::COOK_ISLANDS, self::CURACAO, + self::FALKLAND_ISLANDS_MALVINAS, self::FAROE_ISLANDS, self::FRENCH_GUIANA, self::FRENCH_POLYNESIA, + self::FRENCH_SOUTHERN_TERRITORIES, self::GIBRALTAR, self::GREENLAND, self::GUADELOUPE, self::GUAM, + self::GUERNSEY, self::HEARD_ISLAND_AND_MCDONALD_ISLANDS, self::HONG_KONG, self::ISLE_OF_MAN, + self::JERSEY, self::KOSOVO, self::MACAO, self::MARTINIQUE, self::MAYOTTE, self::MONTSERRAT, + self::NEW_CALEDONIA, self::NIUE, self::NORFOLK_ISLAND, self::NORTHERN_MARIANA_ISLANDS, + self::PALESTINE_STATE_OF, self::PITCAIRN, self::PUERTO_RICO, self::REUNION, self::SAINT_BARTHELEMY, + self::SAINT_HELENA_ASCENSION_AND_TRISTAN_DA_CUNHA, self::SAINT_MARTIN_FRENCH_PART, + self::SAINT_PIERRE_AND_MIQUELON, self::SINT_MAARTEN_DUTCH_PART, + self::SOUTH_GEORGIA_AND_THE_SOUTH_SANDWICH_ISLANDS, self::SVALBARD_AND_JAN_MAYEN, + self::TAIWAN_PROVINCE_OF_CHINA, self::TOKELAU, self::TURKS_AND_CAICOS_ISLANDS, + self::UNITED_STATES_MINOR_OUTLYING_ISLANDS, self::VIRGIN_ISLANDS_BRITISH, self::VIRGIN_ISLANDS_US, + self::WALLIS_AND_FUTUNA, self::WESTERN_SAHARA => false, + default => true + }; + + } + + /** + * ### Check country's region + * @since 1.0.0 + * + * @uses \FireHub\Core\Boundary\Type\Geo\M49::parent() To get parent. + * + * @param \FireHub\Core\Boundary\Type\Geo\M49 $region+ * The region to check for. + *
+ * @param null|\FireHub\Core\Boundary\Type\Geo\M49 $current+ * Current region. + *
+ * + * @return bool True if country is a region type, false otherwise. + */ + private function check (M49 $region, ?M49 $current):bool { + + if ($current === null) return false; + + if ($current === $region) return true; + + return $this->check($region, $current->parent()); + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/IntermediateRegion.php b/src/Type/Geo/IntermediateRegion.php new file mode 100644 index 0000000..b0b53e9 --- /dev/null +++ b/src/Type/Geo/IntermediateRegion.php @@ -0,0 +1,99 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents an intermediate geographic region of the world + * + * The IntermediateRegion enum represents intermediate geographic regions within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries into more specific geographic areas within a + * broader subregion. + * @since 1.0.0 + */ +enum IntermediateRegion:string implements M49 { + + /** + * @since 1.0.0 + */ + case CARIBBEAN = 'Caribbean'; + + /** + * @since 1.0.0 + */ + case CENTRAL_AMERICA = 'Central America'; + + /** + * @since 1.0.0 + */ + case EASTERN_AFRICA = 'Eastern Africa'; + + /** + * @since 1.0.0 + */ + case MIDDLE_AFRICA = 'Middle Africa'; + + /** + * @since 1.0.0 + */ + case SOUTH_AMERICA = 'South America'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_AFRICA = 'Southern Africa'; + + /** + * @since 1.0.0 + */ + case WESTERN_AFRICA = 'Western Africa'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::CARIBBEAN => '029', + self::CENTRAL_AMERICA => '013', + self::EASTERN_AFRICA => '014', + self::MIDDLE_AFRICA => '017', + self::SOUTH_AMERICA => '005', + self::SOUTHERN_AFRICA => '018', + self::WESTERN_AFRICA => '011' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::CARIBBEAN, self::CENTRAL_AMERICA, self::SOUTH_AMERICA + => SubRegion::LATIN_AMERICA_AND_THE_CARIBBEAN, + self::EASTERN_AFRICA, self::MIDDLE_AFRICA, self::SOUTHERN_AFRICA, self::WESTERN_AFRICA + => SubRegion::SUB_SAHARAN_AFRICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/Ocean.php b/src/Type/Geo/Ocean.php new file mode 100644 index 0000000..d16577d --- /dev/null +++ b/src/Type/Geo/Ocean.php @@ -0,0 +1,51 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +/** + * ### Represents an ocean as a geographic value + * + * The Ocean enum represents the world's major oceans as geographic values within the FireHub Core type system. + * + * It provides stable geographic references for relationships and classifications involving the world's oceans. + * @since 1.0.0 + */ +enum Ocean:string { + + /** + * @since 1.0.0 + */ + case ARCTIC = 'Arctic'; + + /** + * @since 1.0.0 + */ + case ATLANTIC = 'Atlantic'; + + /** + * @since 1.0.0 + */ + case INDIAN = 'Indian'; + + /** + * @since 1.0.0 + */ + case PACIFIC = 'Pacific'; + + /** + * @since 1.0.0 + */ + case SOUTHERN = 'Southern'; + +} \ No newline at end of file diff --git a/src/Type/Geo/Region.php b/src/Type/Geo/Region.php new file mode 100644 index 0000000..8b08204 --- /dev/null +++ b/src/Type/Geo/Region.php @@ -0,0 +1,88 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents a major geographic region of the world + * + * The Region enum represents the major geographic regions of the world within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries and other geographic entities into broad world + * regions. + * @since 1.0.0 + */ +enum Region:string implements M49 { + + /** + * @since 1.0.0 + */ + case AFRICA = 'Africa'; + + /** + * @since 1.0.0 + */ + case AMERICAS = 'Americas'; + + /** + * @since 1.0.0 + */ + case ANTARCTICA = 'Antarctica'; + + /** + * @since 1.0.0 + */ + case ASIA = 'Asia'; + + /** + * @since 1.0.0 + */ + case EUROPE = 'Europe'; + + /** + * @since 1.0.0 + */ + case OCEANIA = 'Oceania'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AFRICA => '002', + self::AMERICAS => '119', + self::ANTARCTICA => '110', + self::ASIA => '142', + self::EUROPE => '150', + self::OCEANIA => '009' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return World::WORLD; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/SubRegion.php b/src/Type/Geo/SubRegion.php new file mode 100644 index 0000000..6707410 --- /dev/null +++ b/src/Type/Geo/SubRegion.php @@ -0,0 +1,165 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents a geographic subregion of the world + * + * The SubRegion enum represents the geographic subregions of the world within the FireHub Core type system. + * + * It provides stable geographic references for grouping countries into more specific regions within a broader + * geographic region. + * @since 1.0.0 + */ +enum SubRegion:string implements M49 { + + /** + * @since 1.0.0 + */ + case AUSTRALIA_AND_NEW_ZEALAND = 'Australia and New Zealand'; + + /** + * @since 1.0.0 + */ + case CENTRAL_ASIA = 'Central Asia'; + + /** + * @since 1.0.0 + */ + case EASTERN_ASIA = 'Eastern Asia'; + + /** + * @since 1.0.0 + */ + case EASTERN_EUROPE = 'Eastern Europe'; + + /** + * @since 1.0.0 + */ + case LATIN_AMERICA_AND_THE_CARIBBEAN = 'Latin America and the Caribbean'; + + /** + * @since 1.0.0 + */ + case MELANESIA = 'Melanesia'; + + /** + * @since 1.0.0 + */ + case MICRONESIA = 'Micronesia'; + + /** + * @since 1.0.0 + */ + case NORTHERN_AFRICA = 'Northern Africa'; + + /** + * @since 1.0.0 + */ + case NORTHERN_AMERICA = 'Northern America'; + + /** + * @since 1.0.0 + */ + case NORTHERN_EUROPE = 'Northern Europe'; + + /** + * @since 1.0.0 + */ + case POLYNESIA = 'Polynesia'; + + /** + * @since 1.0.0 + */ + case SOUTH_EASTERN_ASIA = 'South-Eastern Asia'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_ASIA = 'Southern Asia'; + + /** + * @since 1.0.0 + */ + case SOUTHERN_EUROPE = 'Southern Europe'; + + /** + * @since 1.0.0 + */ + case SUB_SAHARAN_AFRICA = 'Sub-Saharan Africa'; + + /** + * @since 1.0.0 + */ + case WESTERN_ASIA = 'Western Asia'; + + /** + * @since 1.0.0 + */ + case WESTERN_EUROPE = 'Western Europe'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::AUSTRALIA_AND_NEW_ZEALAND => '053', + self::CENTRAL_ASIA => '143', + self::EASTERN_ASIA => '030', + self::EASTERN_EUROPE => '051', + self::LATIN_AMERICA_AND_THE_CARIBBEAN => '419', + self::MELANESIA => '054', + self::MICRONESIA => '057', + self::NORTHERN_AFRICA => '015', + self::NORTHERN_AMERICA => '021', + self::NORTHERN_EUROPE => '154', + self::POLYNESIA => '061', + self::SOUTH_EASTERN_ASIA => '035', + self::SOUTHERN_ASIA => '034', + self::SOUTHERN_EUROPE => '039', + self::SUB_SAHARAN_AFRICA => '202', + self::WESTERN_ASIA => '145', + self::WESTERN_EUROPE => '155' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():M49 { + + return match ($this) { + self::AUSTRALIA_AND_NEW_ZEALAND, self::MELANESIA, self::MICRONESIA, self::POLYNESIA + => Region::OCEANIA, + self::CENTRAL_ASIA, self::EASTERN_ASIA, self::SOUTH_EASTERN_ASIA, self::SOUTHERN_ASIA, self::WESTERN_ASIA + => Region::ASIA, + self::EASTERN_EUROPE, self::NORTHERN_EUROPE, self::SOUTHERN_EUROPE, self::WESTERN_EUROPE + => Region::EUROPE, + self::LATIN_AMERICA_AND_THE_CARIBBEAN, self::NORTHERN_AMERICA + => Region::AMERICAS, + self::NORTHERN_AFRICA, self::SUB_SAHARAN_AFRICA + => Region::AFRICA + }; + + } + +} \ No newline at end of file diff --git a/src/Type/Geo/World.php b/src/Type/Geo/World.php new file mode 100644 index 0000000..38e7239 --- /dev/null +++ b/src/Type/Geo/World.php @@ -0,0 +1,58 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.1 + * @package Runtime + */ + +namespace FireHub\Core\Type\Geo; + +use FireHub\Core\Boundary\Type\Geo\M49; + +/** + * ### Represents the world as a geographic value + * + * The World enum represents the complete geographic world as a single value within the FireHub Core type system. + * + * It provides a stable geographic reference for operations and relationships that apply to the entire Earth rather than + * to a specific country, continent, landmass, or geographic region. + * @since 1.0.0 + */ +enum World:string implements M49 { + + /** + * @since 1.0.0 + */ + case WORLD = 'World'; + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function code ():string { + + return match ($this) { + self::WORLD => '001' + }; + + } + + /** + * @inheritDoc + * + * @since 1.0.0 + */ + public function parent ():?M49 { + + return null; + + } + +} \ No newline at end of file diff --git a/src/Type/Maybe.php b/src/Type/Maybe.php new file mode 100644 index 0000000..76a4c78 --- /dev/null +++ b/src/Type/Maybe.php @@ -0,0 +1,54 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.2 + * @package Core + */ + +namespace FireHub\Core\Type; + +/** + * ### Represents an optional value + * + * Maybe represents a value that may or may not exist. A Maybe instance is either a Some value containing a value + * or a None value representing the absence of a value. + * + * Maybe distinguishes between an existing value and the absence of a value without using `null` as an implicit + * absence marker. + * @since 1.0.0 + * + * @template TValue + */ +abstract readonly class Maybe { + + /** + * ### Determines whether a value exists + * @since 1.0.0 + * + * @return bool True if a value exists, false otherwise. + */ + abstract public function isSome ():bool; + + /** + * ### Determines whether a value does not exist + * @since 1.0.0 + * + * @return bool True if a value does not exist, false otherwise. + */ + abstract public function isNone ():bool; + + /** + * ### Returns the contained value + * @since 1.0.0 + * + * @return TValue The contained value. + */ + abstract public function value ():mixed; + +} \ No newline at end of file diff --git a/src/Type/Number.php b/src/Type/Number.php new file mode 100644 index 0000000..6679647 --- /dev/null +++ b/src/Type/Number.php @@ -0,0 +1,83 @@ + + * @copyright 2026-present The FireHub Project - All rights reserved + * @license https://opensource.org/license/Apache-2-0 Apache License, Version 2.0 + * + * @php-version >=8.2 + * @package Core + */ + +namespace FireHub\Core\Type; + +/** + * ### Defines the base numeric Value Object type within the FireHub ecosystem + * + * This abstract class represents the foundation for all numeric-based Value Objects. + * + * It provides immutable numeric value semantics while allowing concrete implementations to define specific numeric + * behavior for different numeric representations, such as integers and decimal values. + * + * The class keeps the Core layer focused on defining the numeric value contract, while concrete implementations belong + * to higher-level layers such as Foundation. + * @since 1.0.0 + * + * @template TValue of numeric|numeric-string + * + * @extends \FireHub\Core\Type\ValueObject@@ -61,7 +61,7 @@ abstract public function value ():mixed; final public function equals (self $other):bool { return $this->sameAs($other) - && $this->value() === $other->value(); + && $this->comparisonValue() === $other->comparisonValue(); } @@ -83,6 +83,20 @@ final public function sameAs (self $other):bool { } + /** + * ### Returns the value to be used for comparison operations + * @since 1.0.0 + * + * @uses \FireHub\Core\Type\ValueObject::value() To get the value. + * + * @return mixed The value to be compared. + */ + protected function comparisonValue ():mixed { + + return $this->value(); + + } + /** * ### Enforces an invariant condition for the Value Object * @since 1.0.0