Debian Codegraph @

vendor/ramsey/uuid/src/Rfc4122/FieldsInterface.php

raw
1 <?php
2
3 /**
4 * This file is part of the ramsey/uuid library
5 *
6 * For the full copyright and license information, please view the LICENSE
7 * file that was distributed with this source code.
8 *
9 * @copyright Copyright (c) Ben Ramsey <[email protected]>
10 * @license http://opensource.org/licenses/MIT MIT
11 */
12
13 declare(strict_types=1);
14
15 namespace Ramsey\Uuid\Rfc4122;
16
17 use Ramsey\Uuid\Fields\FieldsInterface as BaseFieldsInterface;
18 use Ramsey\Uuid\Type\Hexadecimal;
19
20 /**
21 * UUID fields, as defined by RFC 4122
22 *
23 * This interface defines the fields of an RFC 4122 variant UUID. Since RFC 9562 removed the concept of fields and
24 * instead defined layouts that are specific to a given version, this interface is a legacy artifact of the earlier, and
25 * now obsolete, RFC 4122.
26 *
27 * The fields of an RFC 4122 variant UUID are:
28 *
29 * * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
30 * * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
31 * * **time_hi_and_version**: The high field of the timestamp multiplexed with the version number, an unsigned 16-bit integer
32 * * **clock_seq_hi_and_reserved**: The high field of the clock sequence multiplexed with the variant, an unsigned 8-bit integer
33 * * **clock_seq_low**: The low field of the clock sequence, an unsigned 8-bit integer
34 * * **node**: The spatially unique node identifier, an unsigned 48-bit integer
35 *
36 * @link https://www.rfc-editor.org/rfc/rfc4122#section-4.1 RFC 4122, 4.1. Format
37 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4 RFC 9562, 4. UUID Format
38 *
39 * @immutable
40 */
41 interface FieldsInterface extends BaseFieldsInterface
42 {
43 /**
44 * Returns the full 16-bit clock sequence, with the variant bits (two most significant bits) masked out
45 */
46 public function getClockSeq(): Hexadecimal;
47
48 /**
49 * Returns the high field of the clock sequence multiplexed with the variant
50 */
51 public function getClockSeqHiAndReserved(): Hexadecimal;
52
53 /**
54 * Returns the low field of the clock sequence
55 */
56 public function getClockSeqLow(): Hexadecimal;
57
58 /**
59 * Returns the node field
60 */
61 public function getNode(): Hexadecimal;
62
63 /**
64 * Returns the high field of the timestamp multiplexed with the version
65 */
66 public function getTimeHiAndVersion(): Hexadecimal;
67
68 /**
69 * Returns the low field of the timestamp
70 */
71 public function getTimeLow(): Hexadecimal;
72
73 /**
74 * Returns the middle field of the timestamp
75 */
76 public function getTimeMid(): Hexadecimal;
77
78 /**
79 * Returns the full 60-bit timestamp, without the version
80 */
81 public function getTimestamp(): Hexadecimal;
82
83 /**
84 * Returns the variant
85 *
86 * The variant number describes the layout of the UUID. The variant number has the following meaning:
87 *
88 * - 0 - Reserved for NCS backward compatibility
89 * - 2 - The RFC 9562 (formerly RFC 4122) variant
90 * - 6 - Reserved, Microsoft Corporation backward compatibility
91 * - 7 - Reserved for future definition
92 *
93 * For RFC 9562 (formerly RFC 4122) variant UUIDs, this value should always be the integer `2`.
94 *
95 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.1 RFC 9562, 4.1. Variant Field
96 */
97 public function getVariant(): int;
98
99 /**
100 * Returns the UUID version
101 *
102 * The version number describes how the UUID was generated and has the following meaning:
103 *
104 * 1. Gregorian time UUID
105 * 2. DCE security UUID
106 * 3. Name-based UUID hashed with MD5
107 * 4. Randomly generated UUID
108 * 5. Name-based UUID hashed with SHA-1
109 * 6. Reordered Gregorian time UUID
110 * 7. Unix Epoch time UUID
111 * 8. Custom format UUID
112 *
113 * This returns `null` if the UUID is not an RFC 9562 (formerly RFC 4122) variant, since the version is only
114 * meaningful for this variant.
115 *
116 * @link https://www.rfc-editor.org/rfc/rfc9562#section-4.2 RFC 9562, 4.2. Version Field
117 *
118 * @pure
119 */
120 public function getVersion(): ?int;
121
122 /**
123 * Returns true if these fields represent a nil UUID
124 *
125 * The nil UUID is a special form of UUID that is specified to have all 128 bits set to zero.
126 *
127 * @pure
128 */
129 public function isNil(): bool;
130 }