Skip to content

Commit

Permalink
Clarifications about unsigned types use cases (#254)
Browse files Browse the repository at this point in the history
  • Loading branch information
ilya-g committed Jun 1, 2021
1 parent 52e66ce commit a8928fe
Showing 1 changed file with 23 additions and 4 deletions.
27 changes: 23 additions & 4 deletions proposals/unsigned-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ Provide support in the compiler and the standard library in order to introduce t

### Hexadecimal constants that do not fit in signed types

Currently it's hard or even impossible to use hexadecimal literal constants that result in overflow of the corresponding
signed types. That overflow causes the constant to become more wider than expected (e.g. `0xFFFF_FFFE` is `Long`)
Currently, it's hard or even impossible to use hexadecimal literal constants that result in overflow of the corresponding
signed types. That overflow causes the constant to become wider than expected (e.g. `0xFFFF_FFFE` is `Long`)
or even impossible to express in Kotlin: `0x8000_0000_0000_0000`

**Colors**
Expand All @@ -41,7 +41,7 @@ takesColor(0xFFCC00CCu)

**Byte arrays initialized in code**

Currently creating a byte array with content specified in code looks extremely verbose in Kotlin:
Currently, creating a byte array with content specified in code looks extremely verbose in Kotlin:

```kotlin
val byteOrderMarkUtf8 = byteArrayOf(0xEF.toByte(), 0xBB.toByte(), 0xBF.toByte())
Expand All @@ -60,7 +60,7 @@ unsigned arithmetic with signed integers (see [Unsigned int considered harmful f
but one has to be extremely careful when dealing with such tricks and remember which variable represents which type actually in code.

For an unsigned value represented by a signed integer special functions like
`divideUnsigned`, `remainderUnsigned`, `toUnsignedString` has to be called instead of the standard ones.
`divideUnsigned`, `remainderUnsigned`, `toUnsignedString` have to be called instead of the standard ones.
It is very fragile and error prone especially when signed and unsigned values both are used.


Expand All @@ -70,6 +70,25 @@ When one provides an external declaration for some native platform API (either C
that declaration can contain unsigned types natively. Unsigned types in Kotlin would allow to represent such declarations
without unwittingly altering their semantics by substituting unsigned integers with signed ones.

## Non-goals

### Non-negative integers

While unsigned integers can only represent positive numbers and zero, it's not a goal to use them
where non-negative integers are required by application domain, for example, as a type of collection size or collection index value.

First, even in these cases using signed integers helps to detect accidental overflows and signal error conditions,
such as `List.lastIndex` being -1 for an empty list or `List.indexOf` returning -1 when an element is not found in the list.

Second, unsigned integers cannot be treated as a range-limited version of signed ones because their range of values
is not a subset of the signed integers range, i.e. neither signed, nor unsigned integers are subtypes of each other.

To reiterate, the main use case of unsigned numbers is when you need to utilize the full bit range of an integer to
represent positive values.

That is also the reason why conversion from signed values to unsigned and vice-versa works by reinterpreting
the bit pattern of a number as unsigned, or as 2-complement signed respectively.

## Description

We propose to introduce 4 types to represent unsigned integers:
Expand Down

0 comments on commit a8928fe

Please sign in to comment.