https://github.com/bbengfort/sequence
Implements an AutoIncrement counter class similar to PostgreSQL's sequence.
https://github.com/bbengfort/sequence
go monotonicity sequence
Last synced: over 1 year ago
JSON representation
Implements an AutoIncrement counter class similar to PostgreSQL's sequence.
- Host: GitHub
- URL: https://github.com/bbengfort/sequence
- Owner: bbengfort
- License: apache-2.0
- Created: 2014-12-12T21:22:47.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2017-10-24T12:20:03.000Z (over 8 years ago)
- Last Synced: 2025-02-08T17:30:52.319Z (over 1 year ago)
- Topics: go, monotonicity, sequence
- Language: Go
- Homepage:
- Size: 23.4 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Go-Sequence
[](https://travis-ci.org/bbengfort/sequence)
[](https://coveralls.io/github/bbengfort/sequence?branch=master)
[](https://goreportcard.com/report/github.com/bbengfort/sequence)
[](https://godoc.org/github.com/bbengfort/sequence)
**Implements an AutoIncrement counter class similar to PostgreSQL's sequence.**
This library provides monotonically increasing and decreasing sequences similar to the autoincrement sequence objects that are available in databases like PostgreSQL. Unlike simple counter objects, `Sequence` objects are bred for safety, that is they expose the largest possible range of positive integers using the `uint64` data type and raise exceptions when that number overflows or when the increment function does something unexpected. Moreover, the internal state of a `Sequence` is not accessible by external libraries and therefore cannot be modified (except for a straight-up reset), giving developers confidence to use these objects in sequence-critical usage such as automatically incrementing IDs.
## Getting Started
To install the sequence library, simply `go get` it from GitHub:
```
$ go get github.com/bbengfort/sequence
```
For more specifics, please read the [API documentation](https://godoc.org/github.com/bbengfort/sequence).
### Basic Usage
The basic usage is to create a default, monotonically incrementing by 1 sequence that starts at 1 and goes until 18,446,744,073,709,551,614 (the largest possible `uint64` value).
```go
import github.com/bbengfort/sequence
seq := sequence.New()
idx, err := seq.Next()
```
A range can be specified using different arguments to New. For example, to specify a different maximal value:
```go
seq := sequence.New(1000)
```
Will produce a sequence from 1 to 1000 (inclusive) and will return errors when the state goes beyond 1000. A specifically bounded range:
```go
seq := sequence.New(10, 100)
```
Will provide a sequence on the integers from 10 to 100 (inclusive). Finally a step can be provided to determine how the sequence is incremented:
```go
seq := sequence.New(2, 500, 2)
```
Which will return all the even numbers from 2 to 500 (inclusive). Sequences can be reset, returning them to their original state as follows:
```go
err := seq.Reset()
```
Sequences can also be updated to a specific value, so long as the value doesn't violate the monotonically increasing or decreasing rule. If it does, the `Update()` function will return an error:
```go
err := seq.Update(42) // err == nil
seq.Next()
err = seq.Update(42) // err != nil
```
Note that the `Reset()` method is the only function that could violate the monotonicity of the `Sequence` object.
### Sequence State
To get the state of a sequence, you can use the following methods:
```go
seq.IsStarted() // Returns a boolean value if the Sequence is started.
// Get the current value of the sequence
idx, err := seq.Current()
// Print a string representation of the sequence state.
fmt.Println(seq.String())
```
You can also serialize and deserialize the Sequence to pass it across processes as follows:
```go
data, err := seq.Dump()
seq2 := &sequence.Sequence{}
err := seq2.Load(data)
```
This snippet of code will result in `seq2` having an identical state to `seq` at the moment that it was dumped.
## Development
Pull requests are more than welcome to help develop this project!
### Testing
To execute tests for this library:
```
$ make test
```