initial commits

README.md

@@ -2,7 +2,7 @@
 
 Package **xim** provides quazi‐ monotonically‐increasing unique‐identifiers.
 
-The serialized form of the **IID** is safe to use as a _file_ or _directory_ name.
+The serialized form of the **xim-id** is safe to use as a _file_ or _directory_ name.
 
 
 ## Documention
@@ -16,12 +16,12 @@ Online documentation, which includes examples, can be found at: http://godoc.org
 
 Here is an example of using `package xim`:
 ```go
-var id xim.IID = xim.Generate()
+var id xim.ID = xim.Generate()
 ```
 
 ## Representation
 
-Internally, the IID is compactly stored in an `uint64`. The anatomy of this is as follows:
+Internally, the xim-id is compactly stored in an `uint64`. The anatomy of this is as follows:
 ```
                    unix timestamp (39-bits)
        ▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼▼
@@ -30,11 +30,11 @@ Internally, the IID is compactly stored in an `uint64`. The anatomy of this is a
   always zero (1-bit)                                  chaos (20-bits)
 ```
 
-The `xim.IID.UnixTime()` method will give you that 39-bit _unix timestamp_.
+The `xim.ID.UnixTime()` method will give you that 39-bit _unix timestamp_.
 
-And the `xim.IID.Chaos()` method will give you that 24-bit _chaos_.
+And the `xim.ID.Chaos()` method will give you that 24-bit _chaos_.
 
-(The _chaos_ is just a randomness that helps make these IIDs unique, when multiple IIDs are being produced simultaneously.)
+(The _chaos_ is just a randomness that helps make these xim-ids unique, when multiple xim-ids are being produced simultaneously.)
 
 ## Temporal Ordering of Representation
 

id.go

@@ -0,0 +1,137 @@
+package xim
+
+// ID represents a xim-id.
+//
+// It is a scheme used to generate quazi‐monotonically‐increasing‐unique identifier.
+//
+// This can be used for anything that needs a unique-identifier. And its serialization should be safe to use as a file-name, or a directory-name.
+//
+// Example usage:
+//
+//	var id xim.ID = xim.Generate()
+//	
+//	fmt.Println("xim-id =", id)
+type ID struct {
+	value uint64
+	loaded bool
+}
+
+// ID is an option-type. Nothing returns the nothing value for the option-type.
+//
+// An example usage might be:
+//
+//	if xim.Nothing() == id {
+//		//@TODO
+//	}
+func Nothing() ID {
+	return ID{}
+}
+
+// ID is an option-type. something returns a something value for the option-type, that contains the value of the input variable ‘value’ inside of it.
+func something(value uint64) ID {
+	return ID{
+		value:value,
+		loaded:true,
+	}
+}
+
+// Generate returns a new xim-id.
+//
+// Example usage:
+//
+//	var id xim.ID = xim.Generate()
+//	
+//	fmt.Println("xim-id =", id)
+func Generate() ID {
+
+	var value uint64 = generate()
+
+	return something(value)
+}
+
+// Chaos returns the randomness that is embeddd in the xim-id.
+//
+// Example usage:
+//
+//	var id xim.ID = xim.Generate()
+//	
+//	chaos, successful := id.Chaos()
+//	if !successful {
+//		return errors.New("xim-id was not initialized")
+//	}
+//	
+//	fmt.Printf("chaos = %#020b \n", chaos)
+func (receiver ID) Chaos() (uint64, bool) {
+	if Nothing() == receiver {
+		return 0, false
+	}
+
+	_, value := decompile(receiver.value)
+
+	return value, true
+}
+
+// String makes xim.ID fit the fmt.Stringer interface.
+//
+// String also returns the serialized for of a xim-id, in xim-notation.
+func (receiver ID) String() string {
+	if Nothing() == receiver {
+		return ""
+	}
+
+	var serialized string = serialize(receiver.value)
+
+	return serialized
+}
+
+// UnmarshalText makes xim.ID fit the encoding.TextMarshaler interface.
+func (receiver ID) MarshalText() (text []byte, err error) {
+	if Nothing() == receiver {
+		return nil, errNothing
+	}
+
+	var serialized string = serialize(receiver.value)
+
+	return []byte(serialized), nil
+}
+
+// UnixTime returns the unix‐time that is embeddd in the xim-id.
+//
+// Example usage:
+//
+//	var id xim.ID = xim.Generate()
+//	
+//	unixtime, successful := id.UnixTime()
+//	if !successful {
+//		return errors.New("xim-id was not initialized")
+//	}
+//	
+//	var t time.Time = time.Unix(unixtime, 0)
+//	
+//	fmt.Println("xim-id was created on:", t)
+func (receiver ID) UnixTime() (int64, bool) {
+	if Nothing() == receiver {
+		return 0, false
+	}
+
+	value, _ := decompile(receiver.value)
+
+	return int64(value), true
+}
+
+// UnmarshalText makes xim.ID fit the encoding.TextUnmarshaler interface.
+func (receiver *ID) UnmarshalText(p []byte) error {
+	if nil == receiver {
+		return errNilReceiver
+	}
+
+	var serialized string = string(p)
+
+	value, successful := unserialize(serialized)
+	if !successful {
+		return  errBadRequest
+	}
+
+	*receiver = something(value)
+	return nil
+}

id_marshaltext_test.go

@@ -4,17 +4,17 @@ import (
 	"testing"
 )
 
-func TestIID_MarshalText(t *testing.T) {
+func TestID_MarshalText(t *testing.T) {
 
 	for testNumber, test := range stdtests {
 
-		var intid IID = something(test.Value)
+		var id ID = something(test.Value)
 
 		var marshaled []byte
 		{
 			var err error
 
-			marshaled, err = intid.MarshalText()
+			marshaled, err = id.MarshalText()
 			if nil != err {
 				t.Errorf("For test #%d, did not expect an error when mashaling, but actually got one.", testNumber)
 				t.Logf("VALUE: %064b", test.Value)
@@ -30,9 +30,9 @@ func TestIID_MarshalText(t *testing.T) {
 		}
 
 		{
-			var newintid IID
+			var newid ID
 
-			err := newintid.UnmarshalText(marshaled)
+			err := newid.UnmarshalText(marshaled)
 			if nil != err {
 				t.Errorf("For test #%d, did not expect an error when unmashaling, but actually got one.", testNumber)
 				t.Logf("VALUE: %064b", test.Value)
@@ -42,8 +42,8 @@ func TestIID_MarshalText(t *testing.T) {
 			}
 
 
-			var expected IID = intid
+			var expected ID = id
-			var actual   IID = newintid
+			var actual   ID = newid
 
 			if expected != actual {
 				t.Errorf("For test #%d, the actual unmarshaled marshaled value is not what was expected.", testNumber)

iid.go

@@ -1,86 +0,0 @@
-package xim
-
-// IID represents an interaction‐identifier — i.e., an interaction‐ID — i.e., an IID.
-//
-// It is a scheme used to generate quazi‐monotonically‐increasing‐unique.
-type IID struct {
-	value uint64
-	loaded bool
-}
-
-func Nothing() IID {
-	return IID{}
-}
-
-func something(value uint64) IID {
-	return IID{
-		value:value,
-		loaded:true,
-	}
-}
-
-// Generate creates a new interaction‐identifier — i.e., an interaction‐ID — i.e., an IID.
-func Generate() IID {
-
-	var value uint64 = generate()
-
-	return something(value)
-}
-
-// Chaos returns the randomness that is embeddd in the interaction‐identifier — i.e., an interaction‐ID — i.e., an IID.
-func (receiver IID) Chaos() (uint64, bool) {
-	if Nothing() == receiver {
-		return 0, false
-	}
-
-	_, value := decompile(receiver.value)
-
-	return value, true
-}
-
-func (receiver IID) String() string {
-	if Nothing() == receiver {
-		return ""
-	}
-
-	var serialized string = serialize(receiver.value)
-
-	return serialized
-}
-
-func (receiver IID) MarshalText() (text []byte, err error) {
-	if Nothing() == receiver {
-		return nil, errNothing
-	}
-
-	var serialized string = serialize(receiver.value)
-
-	return []byte(serialized), nil
-}
-
-// UnixTime returns the unix‐time that is embeddd in the interaction‐identifier — i.e., an interaction‐ID — i.e., an IID.
-func (receiver IID) UnixTime() (int64, bool) {
-	if Nothing() == receiver {
-		return 0, false
-	}
-
-	value, _ := decompile(receiver.value)
-
-	return int64(value), true
-}
-
-func (receiver *IID) UnmarshalText(p []byte) error {
-	if nil == receiver {
-		return errNilReceiver
-	}
-
-	var serialized string = string(p)
-
-	value, successful := unserialize(serialized)
-	if !successful {
-		return  errBadRequest
-	}
-
-	*receiver = something(value)
-	return nil
-}