Документация: NevelLibrary.Ulid
Ключевые особенности
Что даёт библиотека
выполнено 4 из 4
100%
⚑
Производительность: использует
Unsafe, Span<T> и SIMD (если доступно) для минимизации аллокаций памяти.⚑
Поддержка кириллицы: по умолчанию использует расширенный алфавит Base32, включающий кириллические символы (режим
UseCyrillic = true). Это позволяет генерировать ULID, содержащие буквы русского алфавита.Совместимость: реализует интерфейсы
IParsable<Ulid>, ISpanParsable<Ulid>, IEquatable<Ulid>, IComparable<Ulid>, а также конвертеры для JSON (System.Text.Json) и типов.Конвертация: поддерживает прямую конвертацию между
Ulid, Guid, byte[] и строковым представлением.Installation
Тип находится в пространстве имен NevelLibrary.Ulid. Убедитесь, что ваш проект ссылается на соответствующую библиотеку.
CSHARP
using NevelLibrary.Ulid;
Основные свойства
Строк
5
Колонок
3
Свойство
Тип
Описание
MinValueUlidМинимально возможное значение ULID (timestamp: 1970-01-01, randomness: 0).
MaxValueUlidМаксимально возможное значение ULID (timestamp: DateTimeOffset.MaxValue, randomness: 255).
EmptyUlidЗначение по умолчанию (все байты равны 0).
TimeDateTimeOffsetИзвлекает временную метку из ULID.
Randomnessbyte[]Возвращает массив из 10 байт случайной части.
Создание ULID
1. Генерация нового ULID
Метод NewUlid() создает уникальный идентификатор на основе текущего времени UTC и криптографически стойкого генератора случайных чисел (Xoshiro256).
CSHARP
Ulid myUlid = Ulid.NewUlid();
2. Генерация с фиксированной временной меткой
Если вам нужно создать ULID с конкретной датой (например, для тестирования или восстановления порядка):
CSHARP
DateTimeOffset specificTime = new DateTimeOffset(2023, 10, 1, 12, 0, 0, TimeSpan.Zero);
Ulid myUlid = Ulid.NewUlid(specificTime);
3. Генерация из Guid
ВниманиеВнимание
Преобразование
Guid → Ulid меняет порядок байт и не гарантирует сохранение временной сортируемости исходного GUID.Можно преобразовать существующий Guid в Ulid:
CSHARP
Guid guid = Guid.NewGuid();
Ulid ulid = (Ulid)guid; // Явное преобразование
Ulid ulidFromGuid = (Ulid)guid; // Через explicit operator
4. Создание из массива байт
CSHARP
byte[] bytes = new byte[16] { /* 16 байт данных */ };
Ulid ulid = (Ulid)bytes; // Явное преобразование
// Или
Ulid ulid = new Ulid(bytes);
Парсинг и преобразование в строку
Кириллический Base32
ULID в
NevelLibrary.Ulid сериализуется в строку Base32 с использованием русского алфавита.Парсинг из строки
CSHARP
string cyrillicString = "АБВГДЕЖЗИКЛМНПРСТУФХЦЧ...";
if (Ulid.TryParse(cyrillicString, out Ulid result))
{
Console.WriteLine($"Успешно распарсено: {result}");
}
else
{
Console.WriteLine("Ошибка парсинга");
}
Преобразование в строку
CSHARP
Ulid ulid = Ulid.NewUlid();
string str = ulid.ToString(); // Возвращает строку Base32 (кириллица)
Конвертация в другие форматы
В GUID
CSHARP
Ulid ulid = Ulid.NewUlid();
Guid guid = (Guid)ulid; // Явное преобразование
// Или
Guid guid = ulid.ToGuid();
В массив байт
CSHARP
Ulid ulid = Ulid.NewUlid();
byte[] bytes = ulid.ToByteArray();
// Или неявное преобразование
byte[] bytesImplicit = ulid;
В Base64
CSHARP
Ulid ulid = Ulid.NewUlid();
string base64 = ulid.ToBase64();
Сравнение и равенство
Ulid реализует IComparable<Ulid>, что позволяет сортировать ULID по времени создания (так как timestamp находится в старших битах).
Проверка равенства
CSHARP
Ulid ulid1 = Ulid.NewUlid();
Ulid ulid2 = ulid1;
bool isEqual = ulid1 == ulid2; // true
bool isNotEqual = ulid1 != ulid2; // false
Сравнение
CSHARP
Ulid ulidOld = Ulid.NewUlid(new DateTimeOffset(2020, 1, 1, 0, 0, 0, TimeSpan.Zero));
Ulid ulidNew = Ulid.NewUlid(new DateTimeOffset(2023, 1, 1, 0, 0, 0, TimeSpan.Zero));
int comparison = ulidOld.CompareTo(ulidNew);
// comparison < 0, так как ulidOld создан раньше
Интеграция с EF Core
Тип реализует интерфейс IParsable<Ulid>. Это позволяет Entity Framework Core автоматически преобразовывать строковые значения из базы данных (если столбец хранит ULID как строку) в тип Ulid.
Пример использования в модели:
CSHARP
public class MyEntity
{
public Ulid Id { get; set; } // EF Core будет использовать IParsable для чтения
public string Name { get; set; }
}
JSON сериализация
Тип содержит встроенный JsonConverter (UlidJsonConverter). При использовании System.Text.Json ULID будет сериализован в строку (Base32 формат) и десериализован обратно автоматически.
CSHARP
var ulid = Ulid.NewUlid();
var json = JsonSerializer.Serialize(ulid);
// Результат: "АБВГДЕЖЗИКЛМНПРСТУФХЦЧ..."
var parsedUlid = JsonSerializer.Deserialize<Ulid>(json);
Технические детали
Структура данных
Ulid имеет размер 16 байт и layout Explicit:
1.
Timestamp (48 bits): первые 6 байт. Представляет количество миллисекунд с эпохи Unix (1970-01-01).
2.
Randomness (80 bits): последние 10 байт. Генерируется с помощью
Xoshiro256.Алфавит Base32
По умолчанию используется следующий алфавит (кириллица):
TEXT
АБВГДЕЖЗИКЛМНПРСТУФХЦЧ + 0123456789
Производительность
Технические приёмы
выполнено 3 из 3
100%
Используется
ArrayPool<byte> для временных буферов при конвертации в Base64.Операции с памятью выполняются через
Unsafe и Span для избежания границ проверок и аллокаций.Поддержка
Vector128 (SIMD) для ускоренной конвертации между Guid и Ulid на поддерживаемых платформах.FAQ
Q:Почему мой ULID содержит русские буквы?
A: По умолчанию в коде
NevelLibrary.Ulid установлена константа UseCyrillic = true. Это уникальная особенность данной библиотеки.Q:Можно ли безопасно сравнивать ULID из разных систем?
A: Да, если они используют одинаковый алфавит Base32 и порядок байт. Однако если одна система использует кириллический алфавит, а другая — стандартный, строковые представления будут несовместимы, хотя бинарное представление (16 байт) может быть одинаковым для одного и того же ULID.
Q:Как получить timestamp из ULID?
A: Используйте свойство
Time:CSHARP
DateTimeOffset time = myUlid.Time;
> ПОДПИСЧИКИ: ЗАГРУЗКА...
История изменений
Нажмите для загрузки
ЖУРНАЛ_ОБСУЖДЕНИЙ: 1
01
JSON не разобран
Строка не распознана: ни JSON, ни base64-контейнер ASTB
ДОСТУП_ОГРАНИЧЕН
Требуется авторизация для передачи данных в канал.