README.asciidoc

   1 = Storage-Units image:https://img.shields.io/badge/email-%40metio-brightgreen.svg?style=social&label=mail["Discuss on Google Groups", link="https://groups.google.com/forum/#!forum/metio"] image:https://img.shields.io/badge/irc-%23metio.wtf-brightgreen.svg?style=social&label=IRC["Chat on IRC", link="http://webchat.freenode.net/?channels=metio.wtf"]
   2 Sebastian Hoß <https://github.com/sebhoss[@sebhoss]>
   3 :github-org: sebhoss
   4 :project-name: storage-units
   5 :project-group: de.xn--ho-hia.utils.storage_units
   6 :coverity-project: 2658
   7 :codacy-project: d3cfbbc415c14b79a661d573ac11e68c
   8 :toc:
   9 :toc-placement: preamble
  10
  11 image:https://img.shields.io/badge/license-cc%20zero-000000.svg?style=flat-square["CC Zero", link="http://creativecommons.org/publicdomain/zero/1.0/"]
  12 pass:[<span class="image"><a class="image" href="https://maven-badges.herokuapp.com/maven-central/de.xn--ho-hia.utils.storage_units/storage-units"><img src="https://img.shields.io/maven-central/v/de.xn--ho-hia.utils.storage_units/storage-units.svg?style=flat-square" alt="Maven Central"></a></span>]
  13 pass:[<span class="image"><a class="image" href="https://www.javadoc.io/doc/de.xn--ho-hia.utils.storage_units/storage-units"><img src="https://www.javadoc.io/badge/de.xn--ho-hia.utils.storage_units/storage-units.svg?style=flat-square&color=blue" alt="Read JavaDocs"></a></span>]
  14 image:https://reposs.herokuapp.com/?path={github-org}/{project-name}&style=flat-square["Repository size"]
  15 image:https://www.openhub.net/p/{project-name}/widgets/project_thin_badge.gif["Open Hub statistics", link="https://www.openhub.net/p/{project-name}"]
  16
  17 image:https://img.shields.io/travis/{github-org}/{project-name}/master.svg?style=flat-square["Build Status", link="https://travis-ci.org/{github-org}/{project-name}"]
  18 image:https://img.shields.io/coveralls/{github-org}/{project-name}/master.svg?style=flat-square["Code Coverage", link="https://coveralls.io/github/{github-org}/{project-name}"]
  19 image:https://img.shields.io/coverity/scan/{coverity-project}.svg?style=flat-square["Coverity Scan Result", link="https://scan.coverity.com/projects/{github-org}-{project-name}"]
  20 image:https://img.shields.io/codacy/grade/{codacy-project}.svg?style=flat-square["Codacy Code Quality", link="https://www.codacy.com/app/mail_7/{project-name}"]
  21 image:https://img.shields.io/badge/forkable-yes-brightgreen.svg?style=flat-square["Can this project be forked?", link="https://basicallydan.github.io/forkability/?u={github-org}&r={project-name}"]
  22 image:https://img.shields.io/maintenance/yes/2016.svg?style=flat-square["Is this thing still maintained?"]
  23 image:https://img.shields.io/bountysource/team/metio/activity.svg?style=flat-square["Bounties on open tickets", link="https://www.bountysource.com/teams/metio"]
  24
  25 https://www.java.com[Java] library for storage-/byte-units. All units defined in link:http://en.wikipedia.org/wiki/ISO/IEC_80000[ISO IEC 80000-13:2008] are supported, as well as other commonly found units, like 1 Kilobyte = 1024 Byte.
  26
  27 === Features
  28
  29 * Immutable, type- and thread-safe object model for storage units
  30 * Convenience factories to create units
  31 * Basic arithmetic operators
  32 * Comparisons and equality checks between units
  33 * Lossless conversion between all units
  34 * Human readable text format, including custom formats
  35 * Compatible with any `java.lang.Number`
  36
  37 ==== Available Units
  38
  39 .Binary-prefixed units
  40 |===
  41 | Name | Symbol | Exponential | Absolute | Class
  42
  43 | Byte
  44 | B
  45 | 2 ^0^ Byte
  46 | 1 Byte
  47 | `Byte`
  48
  49 | Kibibyte
  50 | KiB
  51 | 2 ^10^ Byte
  52 | 1 024 Byte
  53 | `Kibibyte`
  54
  55 | Mebibyte
  56 | MiB
  57 | 2 ^20^ Byte
  58 | 1 048 576 Byte
  59 | `Mebibyte`
  60
  61 | Gibibyte
  62 | GiB
  63 | 2 ^30^ Byte
  64 | 1 073 741 824 Byte
  65 | `Gibibyte`
  66
  67 | Tebibyte
  68 | TiB
  69 | 2 ^40^ Byte
  70 | 1 099 511 627 776 Byte
  71 | `Tebibyte`
  72
  73 | Pebibyte
  74 | PiB
  75 | 2 ^50^ Byte
  76 | 1 125 899 906 842 624 Byte
  77 | `Pebibyte`
  78
  79 | Exbibyte
  80 | EiB
  81 | 2 ^60^ Byte
  82 | 1 152 921 504 606 846 976 Byte
  83 | `Exbibyte`
  84
  85 | Zebibyte
  86 | ZiB
  87 | 2 ^70^ Byte
  88 | 1 180 591 620 717 411 303 424 Byte
  89 | `Zebibyte`
  90
  91 | Yobibyte
  92 | YiB
  93 | 2 ^80^ Byte
  94 | 1 208 925 819 614 629 174 706 176 Byte
  95 | `Yobibyte`
  96 |===
  97
  98 .Metric-prefixed units
  99 |===
 100 | Name | Symbol | Exponential | Absolute | Class
 101
 102 | Byte
 103 | kB
 104 | 10 ^0^ Byte
 105 | 1 Byte
 106 | `Byte`
 107
 108 | Kilobyte
 109 | kB
 110 | 10 ^3^ Byte
 111 | 1 000 Byte
 112 | `Kilobyte`
 113
 114 | Megabyte
 115 | MB
 116 | 10 ^6^ Byte
 117 | 1 000 000 Byte
 118 | `Megabyte`
 119
 120 | Gigabyte
 121 | GB
 122 | 10 ^9^ Byte
 123 | 1 000 000 000 Byte
 124 | `Gigabyte`
 125
 126 | Terabyte
 127 | TB
 128 | 10 ^12^ Byte
 129 | 1 000 000 000 000 Byte
 130 | `Terabyte`
 131
 132 | Petabyte
 133 | PB
 134 | 10 ^15^ Byte
 135 | 1 000 000 000 000 000 Byte
 136 | `Petabyte`
 137
 138 | Exabyte
 139 | EB
 140 | 10 ^18^ Byte
 141 | 1 000 000 000 000 000 000 Byte
 142 | `Exabyte`
 143
 144 | Zettabyte
 145 | ZB
 146 | 10 ^21^ Byte
 147 | 1 000 000 000 000 000 000 000 Byte
 148 | `Zettabyte`
 149
 150 | Yottabyte
 151 | YB
 152 | 10 ^24^ Byte
 153 | 1 000 000 000 000 000 000 000 000 Byte
 154 | `Yottabyte`
 155 |===
 156
 157 .Common units
 158 |===
 159 | Name | Symbol | Exponential | Absolute | Class
 160
 161 | Byte
 162 | kB
 163 | 2 ^0^ Byte
 164 | 1 Byte
 165 | `Byte`
 166
 167 | Kilobyte
 168 | kB
 169 | 2 ^10^ Byte
 170 | 1 024 Byte
 171 | `CommonKilobyte`
 172
 173 | Megabyte
 174 | MB
 175 | 2 ^20^ Byte
 176 | 1 048 576 Byte
 177 | `CommonMegabyte`
 178
 179 | Gigabyte
 180 | GB
 181 | 2 ^30^ Byte
 182 | 1 073 741 824 Byte
 183 | `CommonGigabyte`
 184
 185 | Terabyte
 186 | TB
 187 | 2 ^40^ Byte
 188 | 1 099 511 627 776 Byte
 189 | `CommonTerabyte`
 190
 191 | Petabyte
 192 | PB
 193 | 2 ^50^ Byte
 194 | 1 125 899 906 842 624 Byte
 195 | `CommonPetabyte`
 196
 197 | Exabyte
 198 | EB
 199 | 2 ^60^ Byte
 200 | 1 152 921 504 606 846 976 Byte
 201 | `CommonExabyte`
 202
 203 | Zettabyte
 204 | ZB
 205 | 2 ^70^ Byte
 206 | 1 180 591 620 717 411 303 424 Byte
 207 | `CommonZettabyte`
 208
 209 | Yottabyte
 210 | YB
 211 | 2 ^80^ Byte
 212 | 1 208 925 819 614 629 174 706 176 Byte
 213 | `CommonYottabyte`
 214 |===
 215
 216 === Development Status
 217
 218 All units according to ISO IEC 80000-13:2008 are implemented. There are some future ideas, take a look at the link:https://github.com/sebhoss/storage-units/issues[open tickets] in case you are interested. Apart from that, this project is in maintenance mode.
 219
 220
 221 == Usage
 222
 223 === Factories
 224
 225 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.
 226
 227 [source,java]
 228 ----
 229 // 'long' based
 230 Kilobyte unit = Kilobyte.valueOf(500)               // 500 Byte or "0.50 kB"
 231 Kibibyte unit = Kibibyte.valueOf(512)               // 512 Byte or "0.50 KiB"
 232 CommonKilobyte unit = CommonKilobyte.valueOf(512)   // 500 Byte or "0.50 kB"
 233
 234 Megabyte unit = Megabyte.valueOf(1_000_000)             // 1 000 000 Byte or "1.00 MB"
 235 Mebibyte unit = Mebibyte.valueOf(1_048_576)             // 1 048 576 Byte or "1.00 MiB"
 236 CommonMegabyte unit = CommonMegabyte.valueOf(1_048_576) // 1 048 576 Byte or "1.00 MB"
 237
 238 // 'BigInteger' based
 239 Kilobyte unit = Kilobyte.valueOf(BigInteger.valueOf(500))               // 500 Byte or "0.50 kB"
 240 Kibibyte unit = Kibibyte.valueOf(BigInteger.valueOf(512))               // 512 Byte or "0.50 KiB"
 241 CommonKilobyte unit = CommonKilobyte.valueOf(BigInteger.valueOf(512))   // 512 Byte or "0.50 KB"
 242
 243 Megabyte unit = Megabyte.valueOf(BigInteger.valueOf(1000000))               // 1 000 000 Byte or "1.00 MB"
 244 Mebibyte unit = Mebibyte.valueOf(BigInteger.valueOf(1_048_576))             // 1 048 576 Byte or "1.00 MB"
 245 CommonMegabyte unit = CommonMegabyte.valueOf(BigInteger.valueOf(1_048_576)) // 1 048 576 Byte or "1.00 MB"
 246 ----
 247
 248 The `StorageUnits` class offers two factory methods that automatically pick the best-matching unit for a given number of bytes.
 249
 250 ==== Binary-prefixed Units
 251
 252 [source,java]
 253 ----
 254 // 'long' based
 255 StorageUnit<?> unit = StorageUnits.binaryValueOf(256)       // Kibibyte (0.25 KiB)
 256 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)   // Mebibyte (1.00 MiB)
 257
 258 // 'BigInteger' based
 259 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256))     // Kibibyte (0.25 MiB)
 260 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
 261 ----
 262
 263 ==== Metric-prefixed Units
 264
 265 [source,java]
 266 ----
 267 // 'long' based
 268 StorageUnit<?> unit = StorageUnits.metricValueOf(120000)    // Kilobyte (120.00 kB)
 269 StorageUnit<?> unit = StorageUnits.metricValueOf(1000000)   // Megabyte (1.00 MB)
 270
 271 // 'BigInteger' based
 272 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(120000))    // Kilobyte (120.00 kB)
 273 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(1000000))   // Megabyte (1.00 MB)
 274 ----
 275
 276 ==== Common Units
 277
 278 [source,java]
 279 ----
 280 // 'long' based
 281 StorageUnit<?> unit = StorageUnits.commonValueOf(256)       // CommonKilobyte (0.25 kB)
 282 StorageUnit<?> unit = StorageUnits.commonValueOf(1048576)   // CommonMebibyte (1.00 MB)
 283
 284 // 'BigInteger' based
 285 StorageUnit<?> unit = StorageUnits.commonValueOf(BigInteger.valueOf(256))     // CommonKilobyte (0.25 kB)
 286 StorageUnit<?> unit = StorageUnits.commonValueOf(BigInteger.valueOf(1048576)) // CommonMebibyte (1.00 MB)
 287 ----
 288
 289 Additionally high-level factory methods are also available in the `StorageUnits` class.
 290
 291 [source,java]
 292 ----
 293 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 294
 295 Kibibyte unit = kibibyte(1)   // 1 024 Byte
 296 Mebibyte unit = mebibyte(1)   // 1 048 576 Byte
 297 Gibibyte unit = gibibyte(1)   // 1 073 741 824 Byte
 298 Tebibyte unit = tebibyte(1)   // 1 099 511 627 776 Byte
 299 Pebibyte unit = pebibyte(1)   // 1 125 899 906 842 624 Byte
 300 Exbibyte unit = exbibyte(1)   // 1 152 921 504 606 846 976 Byte
 301 Zebibyte unit = zebibyte(1)   // 1 180 591 620 717 411 303 424 Byte
 302 Yobibyte unit = yobibyte(1)   // 1 208 925 819 614 629 174 706 176 Byte
 303
 304 Kilobyte unit = kilobyte(1)   // 1 000 Byte
 305 Megabyte unit = megabyte(1)   // 1 000 000 Byte
 306 Gigabyte unit = gigabyte(1)   // 1 000 000 000 Byte
 307 Terabyte unit = terabyte(1)   // 1 000 000 000 000 Byte
 308 Petabyte unit = petabyte(1)   // 1 000 000 000 000 000 Byte
 309 Exabyte unit = exabyte(1)     // 1 000 000 000 000 000 000 Byte
 310 Zettabyte unit = zettabyte(1) // 1 000 000 000 000 000 000 000 Byte
 311 Yottabyte unit = yottabyte(1) // 1 000 000 000 000 000 000 000 000 Byte
 312
 313 CommonKilobyte unit = commonKilobyte(1)   // 1 024 Byte
 314 CommonMegabyte unit = commonMegabyte(1)   // 1 048 576 Byte
 315 CommonGigabyte unit = commonGigabyte(1)   // 1 073 741 824 Byte
 316 CommonTerabyte unit = commonTerabyte(1)   // 1 099 511 627 776 Byte
 317 CommonPetabyte unit = commonPetabyte(1)   // 1 125 899 906 842 624 Byte
 318 CommonExabyte unit = commonExabyte(1)     // 1 152 921 504 606 846 976 Byte
 319 CommonZettabyte unit = commonZettabyte(1) // 1 180 591 620 717 411 303 424 Byte
 320 CommonYottabyte unit = commonYottabyte(1) // 1 208 925 819 614 629 174 706 176 Byte
 321 ----
 322
 323 === Add, Subtract, Multiply, Divide
 324
 325 Each unit implements the basic four math operations. All operations retain their original type, e.g. `[Kilobyte] + [Megabyte] = [Kilobyte]`
 326
 327 [source,java]
 328 ----
 329 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 330
 331 kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
 332 kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
 333 kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
 334 megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
 335 gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
 336 terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
 337 ----
 338
 339 === Comparison & Equality
 340
 341 Each unit is comparable to each other unit.
 342
 343 [source,java]
 344 ----
 345 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 346
 347 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
 348 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
 349 petabyte(3).compareTo(terabyte(3000)) == 0 // true
 350
 351 megabyte(1000).equals(gigabyte(1))         // true
 352 megabyte(1024).equals(gigabyte(1))         // false
 353 terabyte(12).equals(gigabyte(12000))       // true
 354 ----
 355
 356 === Formatting
 357
 358 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.
 359
 360 [source,java]
 361 ----
 362 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 363
 364 // default pattern '0.00'
 365 terabyte(2).toString()                         // "2.00 TB"
 366 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 367 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 368
 369 // use custom pattern
 370 kilobyte(212345).toString("0.0")                                    // "212345.0 kB"
 371 gibibyte(2123458).asTebibyte().toString("#,###.000")                // "2,073.689 TiB"
 372 kilobyte(120).asMegabyte().add(gigabyte(1)).toString("#,##0.00000") // "1,000.12000 MB"
 373
 374 // use custom pattern with specific Locale
 375 kilobyte(212345).toString("0.0", Locale.GERMAN)                     // "212345,0 kB"
 376 gibibyte(2123458).asTebibyte().toString("#,###.000", Locale.GERMAN) // "2.073,689 TiB"
 377
 378 // use custom format
 379 Format customFormat = new DecimalFormat("#.00000");
 380 terabyte(4).asTebibyte().toString(customFormat) // "3.63798 TiB"
 381
 382 // without creating unit type first
 383 long numberOfBytes = 1_000_000_000_000_000L;
 384 formatAsPetabyte(numberOfBytes) // "1.00 PB"
 385 formatAsTerabyte(numberOfBytes) // "1000.00 TB"
 386 formatAsPebibyte(numberOfBytes) // "0.89 PiB"
 387
 388 // use custom pattern
 389 formatAsTerabyte(numberOfBytes, "#0.#####") // "1000 TB"
 390 formatAsPebibyte(numberOfBytes, "#0.#####") // "0.88818 PiB"
 391
 392 // use custom pattern with specific Locale
 393 formatAsTerabyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "1000 TB"
 394 formatAsPebibyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "0,88818 PiB"
 395
 396 // use custom format
 397 formatAsTerabyte(numberOfBytes, customFormat) // "1000.00000 TB"
 398 formatAsPebibyte(numberOfBytes, customFormat) // ".88818 PiB"
 399 ----
 400
 401 === Conversions
 402
 403 Each unit can be converted to each other unit without loss of information.
 404
 405 [source,java]
 406 ----
 407 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 408
 409 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 410 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 411 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 412
 413 // convert to best-match
 414 kilobyte(1100).asBestMatchingUnit()         // "1.10 MB"
 415 kilobyte(1100).asBestMatchingBinaryUnit()   // "1.05 MiB"
 416 kilobyte(1100).asBestMatchingMetricUnit()   // "1.10 MB"
 417 kilobyte(1100).asBestMatchingCommonUnit()   // "1.05 MB"
 418 ----
 419
 420 Each unit can be expressed as a fraction of another unit (precise up to 24 decimal places)
 421
 422 [source,java]
 423 ----
 424 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 425
 426 BigDecimal kilobytes = megabyte(1).inKilobyte()  // 1 000
 427 BigDecimal bytes = kibibyte(2).inByte()          // 2 048
 428 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
 429 ----
 430
 431 === Integration
 432
 433 To use this project just declare the following dependency inside your POM:
 434
 435 [source,xml,subs="attributes,verbatim"]
 436 ----
 437 <dependencies>
 438   <dependency>
 439     <groupId>{project-group}</groupId>
 440     <artifactId>{project-name}</artifactId>
 441     <version>${version.storage-units}</version>
 442   </dependency>
 443 </dependencies>
 444 ----
 445
 446 Replace `${version.storage-units}` with the link:++http://search.maven.org/#search%7Cga%7C1%7Cg%3Ade.xn--ho-hia.utils.storage_units%20a%3Astorage-units++[latest release]. This project follows the link:http://semver.org/[semantic versioning guidelines].
 447
 448 === Compatibility
 449
 450 This project is compatible with the following Java versions:
 451
 452 .Java compatibility
 453 |===
 454 | | 1.X.Y | 2.X.Y | 3.X.Y
 455
 456 | Java 8
 457 | ✓
 458 | ✓
 459 | ✓
 460
 461 | Java 7
 462 | ✓
 463 |
 464 |
 465 |===
 466
 467 == Reference
 468
 469 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
 470
 471 == Alternatives
 472
 473 * link:https://github.com/JakeWharton/byteunits[Byte Units]
 474
 475 == License
 476
 477 To the extent possible under law, the author(s) have dedicated all copyright
 478 and related and neighboring rights to this software to the public domain
 479 worldwide. This software is distributed without any warranty.
 480
 481 You should have received a copy of the CC0 Public Domain Dedication along
 482 with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 483
 484 == Mirrors
 485
 486 * https://github.com/sebhoss/{project-name}
 487 * https://bitbucket.org/sebhoss/{project-name}
 488 * https://gitlab.com/sebastian.hoss/{project-name}
 489 * http://v2.pikacode.com/sebhoss/{project-name}
 490 * http://repo.or.cz/{project-name}.git