Finished writing library API documentation for README.

2026-06-14 15:56:48 +03:00 · 2012-07-19 18:50:48 -05:00
parent 765b3fcf33
commit 13cc05ab36
2 changed files with 144 additions and 3 deletions
@@ -24,7 +24,6 @@ build a 64-bit version.

 ```php
 <?php
-
 use Rhumsaa\Uuid\Uuid;

 // Generate a version 1 (time-based) UUID
@@ -44,6 +43,148 @@ $uuid5 = Uuid::uuid5(Uuid::NAMESPACE_DNS, 'php.net');
 echo $uuid5 . "\n"; // c4a760a8-dbcf-5254-a0d9-6a4474bd1b62
 ```

+## Library API
+
+### Creation methods
+
+Each of the following methods are called statically to create Uuid objects. The
+class constructor cannot be used to create Uuid objects. That is, the use of
+`new Uuid()` is disabled.
+
+Uuid **Uuid::fromString($name)**  
+Creates a UUID from the string standard representation
+
+Example:
+
+    $uuid = Uuid::fromString('fa018870-d1f6-11e1-9b23-0800200c9a66');
+
+Uuid **Uuid::uuid1()**  
+Creates a time-based UUID (version 1)
+
+Uuid **Uuid::uuid3($namespace, $name)**  
+Creates a UUID (version 3) based on the MD5 hash of a namespace identifier and a name
+
+Uuid **Uuid::uuid4()**
+Creates a random UUID (version 4)
+
+Uuid **Uuid::uuid5($namespace, $name)**  
+Creates a UUID (version 5) based on the SHA-1 hash of a namespace identifier and a name
+
+### Instance methods
+
+Once you have a Uuid object, you may call the following methods on the object.
+
+int **compareTo(Uuid $uuid)**  
+Compares this UUID with the specified UUID. The first of two UUIDs is greater
+than the second if the most significant field in which the UUIDs differ is
+greater for the first UUID.
+
+Returns -1 if this UUID is less than the compared to UUID, 0 if it is equal to
+the compared to UUID, and 1 if it is greater than the compared to UUID.
+
+Example:
+
+    $uuid1 = Uuid::fromString('44cca71e-d13d-11e1-a959-c8bcc8a476f4');
+    $uuid2 = Uuid::fromString('44cca71e-d13d-11e2-a959-c8bcc8a476f4');
+    switch ($uuid1->$compareTo($uuid2)) {
+        case -1:
+            echo "$uuid1 is less than $uuid2";
+            break;
+        case 1:
+            echo "$uuid1 is greater than $uuid2";
+            break;
+        case 0:
+        default:
+            echo "$uuid1 is equal to $uuid2";
+    }
+
+bool **equals($obj)**  
+Compares this UUID to the specified object and returns `true` if they are equal.
+
+string **getBytes()**  
+Returns the UUID as a 16-byte string.
+
+int **getClockSeqHiAndReserved()**  
+Returns the high field of the clock sequence multiplexed with the variant
+(bits 65-72 of the UUID).
+
+int **getClockSeqLow()**  
+Returns the low field of the clock sequence (bits 73-80 of the UUID).
+
+int **getClockSequence()**  
+Returns the full clock sequence, including the high and low fields.
+
+\DateTime **getDateTime()**  
+For version 1 UUIDs, this returns a PHP DateTime object representing the date
+and time used to create the UUID.
+
+array **getFields()**  
+Returns an array of the fields of the UUID, with keys named according to the
+RFC 4122 names for the fields.
+
+| Field                      | Meaning                         |
+| -------------------------- | ------------------------------- |
+| time_low                   | the first 32 bits of the UUID   |
+| time_mid                   | the next 16 bits of the UUID    |
+| time_hi_and_version        | the next 16 bits of the UUID    |
+| clock_seq_hi_and_reserved  | the next 8 bits of the UUID     |
+| clock_seq_low              | the next 8 bits of the UUID     |
+| node                       | the last 48 bits of the UUID    |
+
+int **getLeastSignificantBits()**  
+Returns the least significant 64 bits of this UUID's 128 bit value.
+
+int **getMostSignificantBits()**  
+Returns the most significant 64 bits of this UUID's 128 bit value.
+
+int **getNode()**  
+Returns the node value associated with this UUID.
+
+int **getTimeHiAndVersion()**  
+Returns the high field of the timestamp multiplexed with the version number
+(bits 49-64 of the UUID).
+
+int **getTimeLow()**  
+Returns the low field of the timestamp (the first 32 bits of the UUID).
+
+int **getTimeMid()**  
+Returns the middle field of the timestamp (bits 33-48 of the UUID).
+
+int **getTimestamp()**  
+For version 1 UUIDs, this returns the 60 bit timestamp value used to create
+this UUID. The timestamp is measured in 100-nanosecond units since midnight,
+October 15, 1582, UTC. It is not a Unix timestamp.
+
+string **getUrn()**  
+Returns the string representation of the UUID as a URN.
+
+int **getVariant()**  
+Returns the variant number associated with this UUID.
+
+The variant number has the following meaning:
+
+* 0 - Reserved for NCS backward compatibility
+* 2 - The RFC 4122 variant (used by this class
+* 6 - Reserved, Microsoft Corporation backward compatibility
+* 7 - Reserved for future definition
+
+int **getVersion()**  
+The version number associated with this UUID. The version number describes how
+this UUID was generated.
+
+The version number has the following meaning:
+
+* 1 - Time-based UUID
+* 2 - DCE security UUID
+* 3 - Name-based UUID hashed with MD5
+* 4 - Randomly generated UUID
+* 5 - Name-based UUID hashed with SHA-1
+
+string **toString()**  
+Converts this UUID into a string representation. This class also implements
+__toString(), which will convert this object to a string when it is used in
+any string context.
+

 ## Installation

@@ -507,10 +507,10 @@ class UuidTest extends \PHPUnit_Framework_TestCase
        // The next three UUIDs are used for comparing msb and lsb in
        // the compareTo() method

-        // msb are greater than $uuid4, lsb are greater than $uuid5
+        // msb are less than $uuid4, lsb are greater than $uuid5
        $uuid3 = Uuid::fromString('44cca71e-d13d-11e1-a959-c8bcc8a476f4');

-        // msb are less than in $uuid3, lsb are equal to those in $uuid3
+        // msb are greater than $uuid3, lsb are equal to those in $uuid3
        $uuid4 = Uuid::fromString('44cca71e-d13d-11e2-a959-c8bcc8a476f4');

        // msb are equal to those in $uuid3, lsb are less than in $uuid3