README.md

   1 <!--
   2 SPDX-FileCopyrightText: The Storage-Units Authors
   3 SPDX-License-Identifier: 0BSD
   4  -->
   5
   6 # Storage-Units [![Chat](https://img.shields.io/badge/matrix-%23talk.metio:matrix.org-brightgreen.svg?style=social&label=Matrix)](https://matrix.to/#/#talk.metio:matrix.org)
   7
   8 Storage units according to ISO IEC 80000-13:2008 implemented in Java.
   9
  10 ## Features
  11
  12 * Immutable, type- and thread-safe object model for storage units
  13 * Convenience factories to create units
  14 * Basic arithmetic operators
  15 * Comparisons and equality checks between units
  16 * Lossless conversion between all units
  17 * Human-readable text format, including custom formats
  18 * Compatible with any `java.lang.Number`
  19 * Custom serializers for Jackson, MongoDB, EclipseLink, and others
  20
  21 ### Available Units
  22
  23 | Name     | Symbol | Exponential          | Absolute                                       |
  24 |----------|--------|----------------------|------------------------------------------------|
  25 | Byte     | B      | 2<sup>0</sup> Byte   | 1 Byte                                         |
  26 | Kibibyte | KiB    | 2<sup>10</sup> Byte  | 1 024 Byte                                     |
  27 | Mebibyte | MiB    | 2<sup>20</sup> Byte  | 1 048 576 Byte                                 |
  28 | Gibibyte | GiB    | 2<sup>30</sup> Byte  | 1 073 741 824 Byte                             |
  29 | Tebibyte | TiB    | 2<sup>40</sup> Byte  | 1 099 511 627 776 Byte                         |
  30 | Pebibyte | PiB    | 2<sup>50</sup> Byte  | 1 125 899 906 842 624 Byte                     |
  31 | Exbibyte | EiB    | 2<sup>60</sup> Byte  | 1 152 921 504 606 846 976 Byte                 |
  32 | Zebibyte | ZiB    | 2<sup>70</sup> Byte  | 1 180 591 620 717 411 303 424 Byte             |
  33 | Yobibyte | YiB    | 2<sup>80</sup> Byte  | 1 208 925 819 614 629 174 706 176 Byte         |
  34 | Robibyte | RiB    | 2<sup>90</sup> Byte  | 1 237 940 039 285 380 274 899 124 224 Byte     |
  35 | Qubibyte | QiB    | 2<sup>100</sup> Byte | 1 267 650 600 228 229 401 496 703 205 376 Byte |
  36
  37 | Name       | Symbol | Exponential          | Absolute                                       |
  38 |------------|--------|----------------------|------------------------------------------------|
  39 | Byte       | B      | 10<sup>0</sup> Byte  | 1 Byte                                         |
  40 | Kilobyte   | KB     | 10<sup>3</sup> Byte  | 1 000 Byte                                     |
  41 | Megabyte   | MB     | 10<sup>6</sup> Byte  | 1 000 000 Byte                                 |
  42 | Gigabyte   | GB     | 10<sup>9</sup> Byte  | 1 000 000 000 Byte                             |
  43 | Terabyte   | TB     | 10<sup>12</sup> Byte | 1 000 000 000 000 Byte                         |
  44 | Petabyte   | PB     | 10<sup>15</sup> Byte | 1 000 000 000 000 000 Byte                     |
  45 | Exabyte    | EB     | 10<sup>18</sup> Byte | 1 000 000 000 000 000 000 Byte                 |
  46 | Zettabyte  | ZB     | 10<sup>21</sup> Byte | 1 000 000 000 000 000 000 000 Byte             |
  47 | Yottabyte  | YB     | 10<sup>24</sup> Byte | 1 000 000 000 000 000 000 000 000 Byte         |
  48 | Ronnabyte  | RB     | 10<sup>27</sup> Byte | 1 000 000 000 000 000 000 000 000 000 Byte     |
  49 | Quettabyte | QB     | 10<sup>30</sup> Byte | 1 000 000 000 000 000 000 000 000 000 000 Byte |
  50
  51 ## Usage
  52
  53 ### Factories
  54
  55 Each unit implements a Byte-based static factory method (`valueOf(BigInteger)` or `valueOf(long)`) that can be used to represent a given number of bytes in a specific unit. Note that `Long.MAX_VALUE == 8 Exabyte`, thus use `BigInteger` if you want to work with anything bigger than a eight Exabyte. When in doubt, always use `BigInteger`.
  56
  57 ```java
  58 // 'long' based
  59 Kilobyte unit = Kilobyte.valueOf(500)                           // 500 Byte or "0.50 kB"
  60 Kibibyte unit = Kibibyte.valueOf(512)                           // 512 Byte or "0.50 KiB"
  61
  62 Megabyte unit = Megabyte.valueOf(1_000_000)                     // 1 000 000 Byte or "1.00 MB"
  63 Mebibyte unit = Mebibyte.valueOf(1_048_576)                     // 1 048 576 Byte or "1.00 MiB"
  64
  65 // 'BigInteger' based
  66 Kilobyte unit = Kilobyte.valueOf(BigInteger.valueOf(500))       // 500 Byte or "0.50 kB"
  67 Kibibyte unit = Kibibyte.valueOf(BigInteger.valueOf(512))       // 512 Byte or "0.50 KiB"
  68
  69 Megabyte unit = Megabyte.valueOf(BigInteger.valueOf(1000000))   // 1 000 000 Byte or "1.00 MB"
  70 Mebibyte unit = Mebibyte.valueOf(BigInteger.valueOf(1_048_576)) // 1 048 576 Byte or "1.00 MB"
  71 ```
  72
  73 The `StorageUnits` class offers three factory methods that automatically pick the best-matching unit for a given number of bytes.
  74
  75 #### Binary Units
  76
  77 ```java
  78 // 'long' based
  79 StorageUnit<?> unit = StorageUnits.binaryValueOf(256)                         // Kibibyte (0.25 KiB)
  80 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)                     // Mebibyte (1.00 MiB)
  81
  82 // 'BigInteger' based
  83 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256))     // Kibibyte (0.25 MiB)
  84 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
  85 ```
  86
  87 #### Decimal Units
  88
  89 ```java
  90 // 'long' based
  91 StorageUnit<?> unit = StorageUnits.decimalValueOf(120000)                      // Kilobyte (120.00 kB)
  92 StorageUnit<?> unit = StorageUnits.decimalValueOf(1000000)                     // Megabyte (1.00 MB)
  93
  94 // 'BigInteger' based
  95 StorageUnit<?> unit = StorageUnits.decimalValueOf(BigInteger.valueOf(120000))  // Kilobyte (120.00 kB)
  96 StorageUnit<?> unit = StorageUnits.decimalValueOf(BigInteger.valueOf(1000000)) // Megabyte (1.00 MB)
  97 ```
  98
  99 Additionally high-level factory methods are also available in the `StorageUnits` class.
 100
 101 ```java
 102 import static wtf.metio.storageunits.model.StorageUnits.*;
 103
 104 Kibibyte unit = kibibyte(1)   // 1 024 Byte
 105 Mebibyte unit = mebibyte(1)   // 1 048 576 Byte
 106 Gibibyte unit = gibibyte(1)   // 1 073 741 824 Byte
 107 Tebibyte unit = tebibyte(1)   // 1 099 511 627 776 Byte
 108 Pebibyte unit = pebibyte(1)   // 1 125 899 906 842 624 Byte
 109 Exbibyte unit = exbibyte(1)   // 1 152 921 504 606 846 976 Byte
 110 Zebibyte unit = zebibyte(1)   // 1 180 591 620 717 411 303 424 Byte
 111 Yobibyte unit = yobibyte(1)   // 1 208 925 819 614 629 174 706 176 Byte
 112 Robibyte unit = robibyte(1)   // 1 237 940 039 285 380 274 899 124 224 Byte
 113 Qubibyte unit = qubibyte(1)   // 1 267 650 600 228 229 401 496 703 205 376 Byte
 114
 115 Kilobyte unit = kilobyte(1)     // 1 000 Byte
 116 Megabyte unit = megabyte(1)     // 1 000 000 Byte
 117 Gigabyte unit = gigabyte(1)     // 1 000 000 000 Byte
 118 Terabyte unit = terabyte(1)     // 1 000 000 000 000 Byte
 119 Petabyte unit = petabyte(1)     // 1 000 000 000 000 000 Byte
 120 Exabyte unit = exabyte(1)       // 1 000 000 000 000 000 000 Byte
 121 Zettabyte unit = zettabyte(1)   // 1 000 000 000 000 000 000 000 Byte
 122 Yottabyte unit = yottabyte(1)   // 1 000 000 000 000 000 000 000 000 Byte
 123 Ronnabyte unit = ronnabyte(1)   // 1 000 000 000 000 000 000 000 000 000 Byte
 124 Quettabyte unit = quettabyte(1) // 1 000 000 000 000 000 000 000 000 000 000 Byte
 125 ```
 126
 127 ### Add, Subtract, Multiply, Divide
 128
 129 Each unit implements the basic four math operations. All operations retain their original type, e.g. `[Kilobyte] + [Megabyte] = [Kilobyte]`
 130
 131 ```java
 132 import static wtf.metio.storageunits.model.StorageUnits.*;
 133
 134 kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
 135 kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
 136 kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
 137 megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
 138 gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
 139 terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
 140 ```
 141
 142 ### Comparison & Equality
 143
 144 Each unit is comparable to each other unit.
 145
 146 ```java
 147 import static wtf.metio.storageunits.model.StorageUnits.*;
 148
 149 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
 150 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
 151 petabyte(3).compareTo(terabyte(3000)) == 0 // true
 152
 153 megabyte(1000).equals(gigabyte(1))         // true
 154 megabyte(1024).equals(gigabyte(1))         // false
 155 terabyte(12).equals(gigabyte(12000))       // true
 156 ```
 157
 158 ### Formatting
 159
 160 Each unit prints a human-readable string, representing the amount of bytes in the given unit using the symbol specified in ISO IEC 80000-13:2008.
 161
 162 ```java
 163 import static wtf.metio.storageunits.model.StorageUnits.*;
 164
 165 // default pattern '0.00'
 166 terabyte(2).toString()                         // "2.00 TB"
 167 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 168 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 169
 170 // use custom pattern
 171 kilobyte(212345).toString("0.0")                                    // "212345.0 kB"
 172 gibibyte(2123458).asTebibyte().toString("#,###.000")                // "2,073.689 TiB"
 173 kilobyte(120).asMegabyte().add(gigabyte(1)).toString("#,##0.00000") // "1,000.12000 MB"
 174
 175 // use custom pattern with specific Locale
 176 kilobyte(212345).toString("0.0", Locale.GERMAN)                     // "212345,0 kB"
 177 gibibyte(2123458).asTebibyte().toString("#,###.000", Locale.GERMAN) // "2.073,689 TiB"
 178
 179 // use custom format
 180 Format customFormat = new DecimalFormat("#.00000");
 181 terabyte(4).asTebibyte().toString(customFormat) // "3.63798 TiB"
 182
 183 // without creating unit type first
 184 long numberOfBytes = 1_000_000_000_000_000L;
 185 formatAsPetabyte(numberOfBytes) // "1.00 PB"
 186 formatAsTerabyte(numberOfBytes) // "1000.00 TB"
 187 formatAsPebibyte(numberOfBytes) // "0.89 PiB"
 188
 189 // use custom pattern
 190 formatAsTerabyte(numberOfBytes, "#0.#####") // "1000 TB"
 191 formatAsPebibyte(numberOfBytes, "#0.#####") // "0.88818 PiB"
 192
 193 // use custom pattern with specific Locale
 194 formatAsTerabyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "1000 TB"
 195 formatAsPebibyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "0,88818 PiB"
 196
 197 // use custom format
 198 formatAsTerabyte(numberOfBytes, customFormat) // "1000.00000 TB"
 199 formatAsPebibyte(numberOfBytes, customFormat) // ".88818 PiB"
 200 ```
 201
 202 ### Conversions
 203
 204 Each unit can be converted to each other unit without loss of information.
 205
 206 ```java
 207 import static wtf.metio.storageunits.model.StorageUnits.*;
 208
 209 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 210 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 211 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 212
 213 // convert to best-match
 214 kilobyte(1100).asBestMatchingUnit()          // "1.10 MB"
 215 kilobyte(1100).asBestMatchingBinaryUnit()    // "1.05 MiB"
 216 kilobyte(1100).asBestMatchingDecimalUnit()   // "1.10 MB"
 217 ```
 218
 219 Each unit can be expressed as a fraction of another unit (precise up to 24 decimal places)
 220
 221 ```java
 222 import static wtf.metio.storageunits.model.StorageUnits.*;
 223
 224 BigDecimal kilobytes = megabyte(1).inKilobyte()  // 1 000
 225 BigInteger bytes = kibibyte(2).inByte()          // 2 048
 226 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
 227 ```
 228
 229 ### Serialization/Converters/Mappers
 230
 231 Multiple custom serializers, converters, and mappers are available for all storage units.
 232
 233 #### Dozer
 234
 235 Use a [Dozer](https://dozermapper.github.io/) converter like this:
 236
 237 ```java
 238 import static wtf.metio.storageunits.dozer.*;
 239
 240 DozerBeanMapperBuilder.create()
 241         .withCustomConverter(new BigIntegerBinaryStorageUnitConverter())
 242         .withCustomConverter(new BigIntegerDecimalStorageUnitConverter())
 243         .withCustomConverter(new LongBinaryStorageUnitConverter())
 244         .withCustomConverter(new LongDecimalStorageUnitConverter())
 245         .build();
 246 ```
 247
 248 #### EclipseLink
 249
 250 Use any of the three converters like this:
 251
 252 ```java
 253 import static wtf.metio.storageunits.eclipselink.*;
 254
 255 @Entity
 256 public class HardDisk implements Serializable {
 257
 258     @Basic
 259     @Converter (
 260         name="binaryConverter",
 261         converterClass=BinaryStorageUnitConverter.class
 262     )
 263     @Convert("binaryConverter")
 264     public StorageUnit<?> getFreeSize() {
 265         return freeSize;
 266     }
 267
 268     @Basic
 269     @Converter (
 270         name="decimalConverter",
 271         converterClass=DecimalyStorageUnitConverter.class
 272     )
 273     @Convert("decimalConverter")
 274     public StorageUnit<?> getTotalSize() {
 275         return totalSize;
 276     }
 277
 278 }
 279 ```
 280
 281 #### GSON
 282
 283 Use a [GSON](https://github.com/google/gson) serializer/deserializer like this:
 284
 285 ```java
 286 import static wtf.metio.storageunits.gson.*;
 287
 288 new GsonBuilder()
 289         .registerTypeHierarchyAdapter(StorageUnit.class, new StorageUnitSerializer())
 290         .registerTypeHierarchyAdapter(StorageUnit.class, new BinaryStorageUnitDeserializer())
 291         .registerTypeHierarchyAdapter(StorageUnit.class, new DecimalStorageUnitDeserializer())
 292         .create();
 293 ```
 294
 295 #### Jackson
 296
 297 Use the provided `StorageUnitModule` like this:
 298
 299 ```java
 300 import static wtf.metio.storageunits.jackson.*;
 301
 302 ObjectMapper objectMapper = new ObjectMapper();
 303 objectMapper.registerModule(new StorageUnitModule()); // defaults to binary units
 304 objectMapper.registerModule(new StorageUnitModule(StorageUnitModule.PreferredUnitType.BINARY));
 305 objectMapper.registerModule(new StorageUnitModule(StorageUnitModule.PreferredUnitType.DECIMAL));
 306 ```
 307
 308 #### Jakarta
 309
 310 Use the provided `AttributeConverter`s like this:
 311
 312 ```java
 313 import static wtf.metio.storageunits.jakarta.*;
 314
 315 @Entity
 316 public class HardDisk implements Serializable {
 317
 318     @Convert(converter = BinaryStorageUnitConverter.class)
 319     public StorageUnit<?> getFreeSize() {
 320         return freeSize;
 321     }
 322
 323     @Convert(converter = DecimalStorageUnitConverter.class)
 324     public StorageUnit<?> getTotalSize() {
 325         return totalSize;
 326     }
 327
 328 }
 329 ```
 330
 331 #### MapStruct
 332
 333 Use any of the available mappers like this:
 334
 335 ```java
 336 import static wtf.metio.storageunits.mapstruct.*;
 337
 338 @Mapper( uses = BigIntegerToBinaryUnitMapper.class )
 339 public interface MovieMapper {
 340
 341      DestinationType toDestination(SourceType sourceValue);
 342
 343 }
 344 ```
 345
 346 #### ModelMapper
 347
 348 Use any of the available converters like this:
 349
 350 ```java
 351 import static wtf.metio.storageunits.modelmapper.*;
 352
 353 modelMapper.addConverter(new BigIntegerToBinaryUnitConverter());
 354 modelMapper.addConverter(new BigIntegerToDecimalUnitConverter());
 355 modelMapper.addConverter(new LongToBinaryUnitConverter());
 356 modelMapper.addConverter(new LongToDecimalUnitConverter());
 357 modelMapper.addConverter(new StorageUnitToBigIntegerConverter());
 358 ```
 359
 360 #### MongoDB
 361
 362 Use any of the three codecs like this:
 363
 364 ```java
 365 import static wtf.metio.storageunits.mongodb.*;
 366
 367 CodecRegistry binaryRegistry = CodecRegistries.fromCodecs(new BinaryStorageUnitCodec(), ...);
 368 CodecRegistry decimalRegistry = CodecRegistries.fromCodecs(new DecimalStorageUnitCodec(), ...);
 369 ```
 370
 371 #### Orika
 372
 373 Use any of the provided converters like this:
 374
 375 ```java
 376 import static wtf.metio.storageunits.orika.*;
 377
 378 ConverterFactory converterFactory = mapperFactory.getConverterFactory();
 379 converterFactory.registerConverter(new BinaryStorageUnitConverter());
 380 converterFactory.registerConverter(new DecimalStorageUnitConverter());
 381 ```
 382
 383 ### Integration
 384
 385 To use this project just declare the following dependency inside your POM:
 386
 387 ```xml
 388 <dependencies>
 389     <dependency>
 390         <groupId>wtf.metio.storage-units</groupId>
 391         <artifactId>storage-units-model</artifactId>
 392         <version>${version.storage-units}</version>
 393     </dependency>
 394
 395     <!-- Dozer ONLY -->
 396     <dependency>
 397         <groupId>wtf.metio.storage-units</groupId>
 398         <artifactId>storage-units-dozer</artifactId>
 399         <version>${version.storage-units}</version>
 400     </dependency>
 401     <!-- Dozer ONLY -->
 402
 403     <!-- EclipseLink ONLY -->
 404     <dependency>
 405         <groupId>wtf.metio.storage-units</groupId>
 406         <artifactId>storage-units-eclipselink</artifactId>
 407         <version>${version.storage-units}</version>
 408     </dependency>
 409     <!-- EclipseLink ONLY -->
 410
 411     <!-- GSON ONLY -->
 412     <dependency>
 413         <groupId>wtf.metio.storage-units</groupId>
 414         <artifactId>storage-units-gson</artifactId>
 415         <version>${version.storage-units}</version>
 416     </dependency>
 417     <!-- GSON ONLY -->
 418
 419     <!-- Jackson ONLY -->
 420     <dependency>
 421         <groupId>wtf.metio.storage-units</groupId>
 422         <artifactId>storage-units-jackson</artifactId>
 423         <version>${version.storage-units}</version>
 424     </dependency>
 425     <!-- Jackson ONLY -->
 426
 427     <!-- Jakarta ONLY -->
 428     <dependency>
 429         <groupId>wtf.metio.storage-units</groupId>
 430         <artifactId>storage-units-jakarta</artifactId>
 431         <version>${version.storage-units}</version>
 432     </dependency>
 433     <!-- Jakarta ONLY -->
 434
 435     <!-- MapStruct ONLY -->
 436     <dependency>
 437         <groupId>wtf.metio.storage-units</groupId>
 438         <artifactId>storage-units-mapstruct</artifactId>
 439         <version>${version.storage-units}</version>
 440     </dependency>
 441     <!-- MapStruct ONLY -->
 442
 443     <!-- ModelMapper ONLY -->
 444     <dependency>
 445         <groupId>wtf.metio.storage-units</groupId>
 446         <artifactId>storage-units-modelmapper</artifactId>
 447         <version>${version.storage-units}</version>
 448     </dependency>
 449     <!-- ModelMapper ONLY -->
 450
 451     <!-- MongoDB ONLY -->
 452     <dependency>
 453         <groupId>wtf.metio.storage-units</groupId>
 454         <artifactId>storage-units-mongodb</artifactId>
 455         <version>${version.storage-units}</version>
 456     </dependency>
 457     <!-- MongoDB ONLY -->
 458
 459     <!-- Orika ONLY -->
 460     <dependency>
 461         <groupId>wtf.metio.storage-units</groupId>
 462         <artifactId>storage-units-orika</artifactId>
 463         <version>${version.storage-units}</version>
 464     </dependency>
 465     <!-- Orika ONLY -->
 466 </dependencies>
 467 ```
 468
 469 Replace `${version.storage-units}` with the [latest release](https://central.sonatype.com/namespace/wtf.metio.storage-units).
 470
 471 ## Reference
 472
 473 Originally inspired by [Twitters util](https://github.com/twitter/util#space) package.
 474
 475 ## Alternatives
 476
 477 * [Byte Units](https://github.com/JakeWharton/byteunits)
 478 * [triava](https://github.com/trivago/triava)