objectid 3.0.0 copy "objectid: ^3.0.0" to clipboard
objectid: ^3.0.0 copied to clipboard

Blazing fast, cross-platform ObjectId implementation for the dart language.

ObjectId #

Blazing fast, cross-platform ObjectId implementation for the dart language! #

Dart tests pub package License: MIT style: effective dart codecov

Why this package?

  • ๐Ÿš€ Fast.
  • ๐Ÿ“ฑ Cross-platform.
  • ๐Ÿงช Well tested.
  • ๐Ÿ“’ Fulfills bson ObjectId specification.
  • ๐Ÿ“ Documented.

Getting started. #

  1. Depend on it.
dependencies:
  objectid: 2.0.0
  1. Play with it!
final id = ObjectId(); // That's all ๐Ÿ”ฅ๐Ÿ˜ฎ!
print(id);   // it's working! => 5f52c805df41c9df948e6135

Documentation #

ObjectId() #

Creates ObjectId instance based on current timestamp, process unique and counter. For more information take a look at ObjectId specification.

/// Creates ObjectId instance.
final id = ObjectId();
print(id.hexString); // => 5f52c805df41c9df948e6135

ObjectId.fromHexString(String hexString) #

Creates ObjectId from hex string.

TIP ๐Ÿ’ก:
Can be helpful for mapping hex strings returned from API / mongodb.

/// Create ObjectId instance.
final id = ObjectId.fromHexString('5f52c805df41c9df948e6135');
print(id.hexString); // => 5f52c805df41c9df948e6135

final id2 = ObjectId.fromHexString(id.hexString);
print(id == id2); // => true

ObjectId.fromBytes(List

Creates ObjectId from bytes.

TIP ๐Ÿ’ก:
Sometimes we may want to save ObjectId representation to file, binary format is the best way to do so.

/// Create ObjectId instance.
final id = ObjectId.fromBytes([95, 82, 205, 121, 180, 195, 28, 88, 32, 47, 183, 78]);
print(id.hexString); // => 5f52cd79b4c31c58202fb74e

/// To retrive ObjectId bytes as [Uint8list] you can use `bytes` property.
print(id.bytes); // => [95, 82, 205, 121, 180, 195, 28, 88, 32, 47, 183, 78]

final id2 = ObjectId.fromBytes(id.bytes);
print(id == id2); // => true

ObjectId.fromValues(int millisecondsSinceEpoch, int processUnique, int counter) #

Creates an ObjectId from the provided integer values.

/// Create ObjectId instance.
/// `hexString = 000000000000000000000000`
final zeroed = ObjectId.fromValues(0, 0, 0);

/// `hexString = ffffffff0000000000000000`
final withTimestamp = ObjectId.fromValues(0x3e7fffffc18, 0, 0); 

/// `hexString = 00000000ffffffffff000000`
final withProcessUnique = ObjectId.fromValues(0, 0xffffffffff, 0); 

/// `hexString = 000000000000000000ffffff`
final withCounter = ObjectId.fromValues(0, 0, 0xffffff);

/// `hexString = ffffffffffffffffffffffff`
final filled = ObjectId.fromValues(0x3e7fffffc18, 0xffffffffff, 0xffffff);

ObjectId.fromTimestamp(DateTime timestamp) #

Creates ObjectId from provided timestamp.
Propably you do not want to use this constructor. It is mostly used for ObjectId comparisons or sorting.

Warning โš ๏ธ:
Only timestamp segment is set while the rest of the ObjectId is zeroed out.

/// Create ObjectId instance.
final id = ObjectId.fromTimestamp(DateTime.now());
print(id.hexString); // => 5f52d05e0000000000000000

bool operator == #

It is possible to compare ObjectIds instances by equality operator ==.
Comparison is based on ObjectId runtimeType and bytes.

int hashCode #

Hashcode is calculated by dart implementation of Austin Appleby, MurmurHash2 algorithm; wich is for ObjectId almost 2 times faster ๐Ÿš€ than the commonly used Jenkins algorithm.

Property value will be generated only once (with the first read) and cached, what's strongly improves performance.

String hexString #

Returns a 24-bit hex string representation of the ObjectId.

Property value will be generated only once (with the first read) and cached, what's strongly improves performance.

DateTime timestamp #

Returns an accurate up to the second ObjectId generation time (timestamp).

Property value will be generated only once (with the first read) and cached, what's strongly improves performance.

Uint8List bytes #

Returns a ObjectId bytes.


static bool isValid(String hexString) #

Helper method that checks whether the provided hexString is a valid ObjectId.


Benchmark: #

Benchmark hardware/software:
UNIT: MacBook Pro (13-inch, M2, 2022)
CPU: Apple M2, 16GB RAM
RAM: 16 GB
OS: macOS Monterey 12.6.1 (Build 21G217)
Dart SDK version: 3.0.5

Constructors:
ObjectId() โ†’ (RunTime): 0.29132956069161253 us.
ObjectId.fromHexString() โ†’ (RunTime): 0.75057425 us.
ObjectId.fromBytes() โ†’ (RunTime): 0.14730780908787755 us.
ObjectId.fromValues() โ†’ (RunTime): 0.07130824418248206 us.
ObjectId.fromTimestamp() โ†’ (RunTime): 0.044412125467054496 us.
Properties:
ObjectId.hexString โ†’ (RunTime): 0.039307475449695345 us.
ObjectId.timestamp โ†’ (RunTime): 0.050248475 us.
ObjectId.hashCode โ†’ (RunTime): 0.03570540247334531 us.
Operators:
ObjectId == ObjectId โ†’ (RunTime): 0.12478619550684174 us.

Benchmark is available in the example app.

30
likes
140
pub points
92%
popularity

Publisher

verified publisherklyta.it

Blazing fast, cross-platform ObjectId implementation for the dart language.

Repository (GitHub)
View/report issues

Documentation

API reference

License

MIT (LICENSE)

More

Packages that depend on objectid