Uuid

[qurbonzoda]

This issue is for discussion of the proposed Uuid API. The full text of the proposal is here.

The API is already available in Kotlin 2.0.20-Beta2 and later, and is marked with @ExperimentalStdlibApi.

[axelfontaine]

As Uuid really is a base building block of data models, the package dependencies really matter. For the JVM, instead of having uuid depend on nio, it should really be the other way around!

[joffrey-bion]

I do like that, by default, Uuid.toString() and Uuid.parse() rely on the RFC hex-and-dash format.

However, toString is initially meant for human readability. From the Javadoc of Object.toString(): "The result should be a concise but informative representation that is easy for a person to read". For this reason, I generally don't trust toString() as a reliable and stable way to serialize data (for any class), because it's not part of its contract.

I would find it nice to have Uuid.toRfc9562() or Uuid.toRfc9562String() in the API for the purpose of actually serializing a UUID for program consumption (and not human). toString() would of course use that behind the scenes because the RFC format is also nice for humans. As a side note: we do have Duration.toIsoString() for Kotlin durations. (Admittedly, durations have a different "natural" representation for humans, which means toString() was already "taken", but it kinda proves the point).

[lukellmann]

As Uuid really is a base building block of data models, the package dependencies really matter. For the JVM, instead of having uuid depend on nio, it should really be the other way around!

If I understood this correctly, only the convenience extension functions for reading from / writing to ByteBuffers depend on NIO, not the Uuid class itself.

[joffrey-bion]

@axelfontaine also, what exactly do you mean by "package dependencies"? It's not like there is a maven dependency (nio is in the Java runtime). Are you talking about Java 9 modules and the kotlin.uuid package requiring things? What exact problem are you worried about?

[adam-enko]

I would prefer the name to be UUID over Uuid.

It is consistent with existing names Base64.UrlSafe and Base64.Mime names.

Mime and UUID are both abbreviations, but the former is an acronym, and the later is an initialism.

• 'Mime' is an acronym, and is pronounced as a single word. JSON is another acronym.
• 'UUID' is an initialism, because each letter is pronounced individually. So is URL.
  (Although maybe I'm wrong and people do say 'oooo-eye-dee' and 'uhrrrll'(!)).

I can see how UrlSafe could be a counterpoint (should it be URLSafe?), but it follows the official Kotlin naming conventions.

When using an acronym as part of a declaration name, capitalize it if it consists of two letters (IOStream); capitalize only the first letter if it is longer (XmlFormatter, HttpInputStream).

The visual difference between UUID/Uuid is confusing when looking at the Kotlin/Java converter helper:

public fun Uuid.toJavaUuid(): java.util.UUID

Shouldn't the extension fun Uuid.toJavaUuid() instead be named fun Uuid.toJavaUUID(), to match the Java naming scheme?

• It helps disambiguate whether the Java or Kotlin UUID type is being used without looking at imports.

This same confusion happens with other types (I've encountered this Random/Random). But those cases are exceedingly rare, and Kotlin provides tools to easily deal with them (named imports, or typealiases, or just using the FQN.)

Given that the confusion only happens in Kotlin/JVM, should other Kotlin targets have an unusual UUID name because of some other Kotlin target?

Maybe the confusion be helped by introducing official type aliases?

// kotlin-stdlib/src/jvmMain/kotlin/uuid/uuid-helpers.kt

typealias UuidKt = kotlin.uuid.UUID
typealias UuidJdk = java.util.UUID

[JakeWharton]

Mime and UUID are both abbreviations, but the former is an acronym, and the later is an initialism.

• 'Mime' is an acronym, and is pronounced as a single word. JSON is another acronym.

• 'UUID' is an initialism, because each letter is pronounced individually. So is URL.
  (Although maybe I'm wrong and people do say 'oooo-eye-dee' and 'uhrrrll'(!)).

I am definitely opposed to using pronunciation as a guiding principle on casing for a few reasons:

1. Initialisms are a subset of acronyms and not disjoint, so by eliminating their special casing (heh) we eliminate an extra rule to remember.
2. Many acronyms do not have universal agreement or canonical definition as whether they're initialisms or not (e.g., SQL is "S-Q-L" and "Sequel"). This also can vary as to whether English is your first language or not.
3. It is impossible to tool this differentiation for static analysis except by continually chasing an exhaustive list of initialisms.
4. Sibling and related acronyms may disagree on initialism, and thus would require different naming conventions (e.g., GUID is typically "goo-id" and so by your rules would be required to be named Guid despite both being rooted in "unique identifier").
5. Adjacent initialisms in a name offer no visual delineation between them creating confusion for those unfamiliar with one or both terms. Casing them like words eliminates this problem.

[OliverO2]

I suggest to replace

• Uuid.parse with Uuid.fromHexDashString,
• Uuid.parseHex with Uuid.fromHexString.

This would result in

• better discoverability in the IDE via UUID.from + completion,
• consistency with other functions and the coding conventions for functions returning a value.

Consistency example:

val uuid2 = Uuid.fromULongs(0x550E8400E29B41D4uL, 0xA716446655440000uL)
val uuid3 = Uuid.fromHexDashString("550e8400-e29b-41d4-a716-446655440000")

I'd also support replacing

• Uuid.toString with Uuid.toHexDashString

for the variant guaranteeing a specific format.

(Uuid.toString can still have the same implementation, just without the stability guarantees for machine readability.)

[joffrey-bion]

Admittedly I prefer toHexDashString() over my initial toRfc9562String() proposal 😆

[Amejonah1200]

I'm against using from for parsing strings, because UUIDs are 126bit long numbers which have a representation as a string (serialized as) which can be parsed later on.

[lppedd]

I was looking at the compiled JS code, and I think using Long is a pretty bad choice for the JS target, especially when performing bit operations. This is the code for fromByteArray, for example:

fromByteArray_d3r0u1_k$(byteArray) {
  if (!(byteArray.length === 16)) {
    var message = 'Expected exactly 16 bytes';
    throw IllegalArgumentException.new_kotlin_IllegalArgumentException_f8t9r5_k$(toString_1(message));
  }
  return this.fromLongs_uu1aj7_k$(toLong_1(byteArray, 0), toLong_1(byteArray, 8));
}

The toLong_1(byteArray, index) function, which corresponds to:

private fun ByteArray.toLong(startIndex: Int): Long {
    return ((this[startIndex + 0].toLong() and 0xFF) shl 56) or
            ((this[startIndex + 1].toLong() and 0xFF) shl 48) or
            ((this[startIndex + 2].toLong() and 0xFF) shl 40) or
            ((this[startIndex + 3].toLong() and 0xFF) shl 32) or
            ((this[startIndex + 4].toLong() and 0xFF) shl 24) or
            ((this[startIndex + 5].toLong() and 0xFF) shl 16) or
            ((this[startIndex + 6].toLong() and 0xFF) shl 8) or
            (this[startIndex + 7].toLong() and 0xFF)
}

will create more than 50 Long instances to perform those bit operations.
Not to mention the amount of function calls and those 50+ undefined checks because of the lazy initialization of the companion object and its properties.

[bcmedeiros]

Curiosity question, is there anything preventing Uuid to be a value class?

[CLOVIS-AI]

Curiosity question, is there anything preventing Uuid to be a value class?

Currently, value classes can only have a single field (see #340). Based on, what would its field be?

• No primitives in Kotlin are 128 bits long.
• Using a String would be wasteful of memory (36 bytes in hex-and-dash instead of the optimal 16 bytes)
• Using an array of longs will have higher overhead than a regular class with two fields

Also, with a value class, the representation must be exactly the same on all platforms and is part of the public API, whereas with regular classes, it can be kept as an implementation detail of each platform, and change if performance problems are found.

[JakeWharton]

Using an array of longs will have higher overhead than a regular class with two fields

A small nit: on the JVM, at least, this is not true. Let's assume a 64-bit JVM running with compressed OOPs (the default).

• An object with two long fields will have a 12-byte header plus two 8-byte fields for 28 bytes. This will be padded to 32 bytes total, as a multiple of 8 is required.
• A two-element long array will have a 16-byte header plus 2*8 bytes for the elements for 32 bytes.
• A sixteen-element byte array will have a 12-byte header 16 bytes for the elements for 28 bytes. This will be padded to 32 bytes total, as a multiple of 8 is required.

(I included a byte array version because you wouldn't want to use a long array in general due to its abysmal representation on JS)

So really no matter what you do you're allocating 32 bytes.

A value class, however, will require boxing at certain points (such as when used in a generic context) which will be a 16-byte allocation each time (12-byte header + 4-byte object reference).

You can validate all of this yourself using JOL.

Although having written all this maybe you were referring to runtime bounds checking on the array? There's usually ways to convince the JVM compilers and ART on Android to eliminate/minimize them, but for that I'd need to break out JMH and other tools. I don't think a value class is really being considered here, so I'm not going to bother right now.

[CLOVIS-AI]

I did mean runtime memory usage, but I forgot about padding, so you're completely right that it doesn't make a difference here. Thanks for reminding me!