Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions Project.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
name = "ULID"
uuid = "6c3f1218-4c8c-4ae5-8681-dbf78ac1ac05"
version = "1.0.0"
authors = ["Stephan Antholzer <stephan.antholzer@datalabhell.at>"]
version = "0.1.0"
authors = [
"Stephan Antholzer <stephan.antholzer@datalabhell.at>",
"Johannes Sappl <johannes.sappl@datalabhell.at>",
]

[deps]
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,27 @@

[![Build Status](https://github.com/DataLabHell/ULID.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/DataLabHell/ULID.jl/actions/workflows/CI.yml?query=branch%3Amain)

Unique Lexicographically Sortable Identifier [ULID](https://github.com/ulid/spec). Binary implementation in julia.
Unique Lexicographically Sortable Identifier [ULID](https://github.com/ulid/spec).

Unlike [ararslan/ULID.jl](https://github.com/ararslan/ULID.jl), which generates ULIDs as strings, this implementation stores them as compact `UInt128` binary values.

## Install

### Install
```julia
import Pkg
Pkg.add("https://github.com/DataLabHell/ULID.jl")
```

## Usage

### Usage
```julia
using ULID
# generate time sortable id
u = ulid() # ULID("01K8X9KNDDYVSTF4XBE6A250RB")
# parse binary representation of ULID from string
parse(Ulid, "01K8X9KNDDYVSTF4XBE6A250RB")
```

## Status & Docs

This plugin is **incubating**. APIs and defaults may change.
46 changes: 22 additions & 24 deletions src/ULID.jl
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
ULID

Unique Lexicographically Sortable Identifier [ULID](https://github.com/ulid/spec).
Binary implementation in julia.
Binary implementation in Julia.
"""
module ULID

Expand All @@ -34,35 +34,37 @@ Ulid(u::Ulid) = u

Base.UInt128(u::Ulid) = u.value

# Crockford's base-32 encoding
# Crockford's Base32 encoding
const _ENCODING = UInt8['0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'J',
'K', 'M', 'N', 'P', 'Q', 'R', 'S', 'T', 'V',
'W', 'X', 'Y', 'Z']

function _build_ulid(rng::AbstractRNG, timestamp::UInt128)
bytes = rand(rng, UInt128)
# make space for the timestamp
bytes >>= UInt128(48)

bytes |= timestamp << UInt128(80)
const _DECODING = fill(UInt8(255), 43)
for (index, value) in enumerate(_ENCODING)
_DECODING[value - 0x2f] = UInt8(index - 1)
end

return Ulid(bytes)
function _build_ulid(rng::AbstractRNG, timestamp::UInt128)
bits = rand(rng, UInt128)
bits >>= 48 # make space for 48 bit timestamp
bits |= timestamp << 80
return Ulid(bits)
end

"""
```
ulid([rng=Random.RandomDevice()])
```
Generate a ULID using the default rng for randomness and `Base.time` for reading the current time.
Generate a ULID using the default random number generator and `Base.time` for reading the current time.

```
ulid(rng)
```
Generate random part of the ULID with a user defined rng.
Generate a ULID with a user-defined random number generator.
"""
function ulid(rng::AbstractRNG=Random.RandomDevice())
# current time in ms, rounded to an Integer
# current time (Float64) in seconds, converted to milliseconds, rounded to an integer
timestamp = round(UInt128, time() * 1e3)
_build_ulid(rng, timestamp)
end
Expand All @@ -82,23 +84,19 @@ end
Base.print(io::IO, u::Ulid) = print(io, string(u))
Base.show(io::IO, u::Ulid) = print(io, ULID, "(\"", u, "\")")


function __convert_digit(c::UInt8)
x = findfirst(==(c), _ENCODING)
if isnothing(x)
return nothing
end
return UInt8(x - 1)
end

function Base.tryparse(::Type{Ulid}, s::AbstractString)
u = UInt128(0)
shift = 0
ncodeunits(s) != 26 && return nothing
for i in 26:-1:1
x = __convert_digit(codeunit(s, i))
isnothing(x) && return nothing
u |= UInt128(x) << shift
x = codeunit(s, i)
# not in 0-9, A-Z, a-z
(x < 0x30 || x > 0x7a) && return nothing
# lowercase to uppercase
x = x > 0x5a ? (x - 0x20) : x
d = _DECODING[x - 0x2f]
d == 0xff && return nothing
u |= UInt128(d) << shift
shift += 5
end
return Ulid(u)
Expand Down
28 changes: 28 additions & 0 deletions test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,31 @@ end
@test parse(Ulid, "0"^13 * "1"^13).value == UInt128(0x1084210842108421)
@test parse(Ulid, "Z"^26).value == typemax(UInt128)
end

@testset "ULID case insensitivity" begin
# Generate a canonical ULID
ulid_value = ulid()
ulid_str = string(ulid_value)

# Test various case combinations (Crockford Base32 is case-insensitive)
cases = [
uppercase(ulid_str),
lowercase(ulid_str),
# Mixed case example
ulid_str[1:13] * uppercase(ulid_str[14:20]) * lowercase(ulid_str[21:26]),
]

@testset "Case variant: $case" for case in cases
parsed = tryparse(Ulid, case)
@test parsed !== nothing
@test parsed == ulid_value
end

# Test invalid length still fails
@test tryparse(Ulid, uppercase(ulid_str[1:25])) === nothing

# Test invalid characters fail regardless of case
invalid = uppercase(ulid_str) * "X" # Extra invalid char
@test tryparse(Ulid, invalid) === nothing
end