diff --git a/README.md b/README.md index dfe47ac..127044b 100644 --- a/README.md +++ b/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 diff --git a/id.go b/id.go new file mode 100644 index 0000000..feb9d32 --- /dev/null +++ b/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 +} diff --git a/iid_marshaltext_test.go b/id_marshaltext_test.go similarity index 82% rename from iid_marshaltext_test.go rename to id_marshaltext_test.go index 5b93c8b..f45bffb 100644 --- a/iid_marshaltext_test.go +++ b/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 actual IID = newintid + var expected ID = id + var actual ID = newid if expected != actual { t.Errorf("For test #%d, the actual unmarshaled marshaled value is not what was expected.", testNumber) diff --git a/iid.go b/iid.go deleted file mode 100644 index 7c2f52d..0000000 --- a/iid.go +++ /dev/null @@ -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 -}