reiver
/
go-xim
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

initial commits

master
Charles Iliya Krempeaux 2021-11-07 21:28:14 -08:00
parent 24c5dcecb1
commit 17718dcaba
4 changed files with 150 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@ -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

137
id.go 100644
View File

@ -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
}

14
iid_marshaltext_test.go → id_marshaltext_test.go
View File

@ -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)

86
iid.go
View File

@ -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
}