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 units according to link:http://en.wikipedia.org/wiki/ISO/IEC_80000[ISO IEC 80000-13:2008].
  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
  42
  43 | Byte
  44 | B
  45 | 2 ^0^ Byte
  46 | 1 Byte
  47
  48 | Kibibyte
  49 | KiB
  50 | 2 ^10^ Byte
  51 | 1 024 Byte
  52
  53 | Mebibyte
  54 | MiB
  55 | 2 ^20^ Byte
  56 | 1 048 576 Byte
  57
  58 | Gibibyte
  59 | GiB
  60 | 2 ^30^ Byte
  61 | 1 073 741 824 Byte
  62
  63 | Tebibyte
  64 | TiB
  65 | 2 ^40^ Byte
  66 | 1 099 511 627 776 Byte
  67
  68 | Pebibyte
  69 | PiB
  70 | 2 ^50^ Byte
  71 | 1 125 899 906 842 624 Byte
  72
  73 | Exbibyte
  74 | EiB
  75 | 2 ^60^ Byte
  76 | 1 152 921 504 606 846 976 Byte
  77
  78 | Zebibyte
  79 | ZiB
  80 | 2 ^70^ Byte
  81 | 1 180 591 620 717 411 303 424 Byte
  82
  83 | Yobibyte
  84 | YiB
  85 | 2 ^80^ Byte
  86 | 1 208 925 819 614 629 174 706 176 Byte
  87 |===
  88
  89 .Metric-prefixed units
  90 |===
  91 | Name | Symbol | Exponential | Absolute
  92
  93 | Byte
  94 | kB
  95 | 10 ^0^ Byte
  96 | 1 Byte
  97
  98 | Kilobyte
  99 | kB
 100 | 10 ^3^ Byte
 101 | 1 000 Byte
 102
 103 | Megabyte
 104 | MB
 105 | 10 ^6^ Byte
 106 | 1 000 000 Byte
 107
 108 | Gigabyte
 109 | GB
 110 | 10 ^9^ Byte
 111 | 1 000 000 000 Byte
 112
 113 | Terabyte
 114 | TB
 115 | 10 ^12^ Byte
 116 | 1 000 000 000 000 Byte
 117
 118 | Petabyte
 119 | PB
 120 | 10 ^15^ Byte
 121 | 1 000 000 000 000 000 Byte
 122
 123 | Exabyte
 124 | EB
 125 | 10 ^18^ Byte
 126 | 1 000 000 000 000 000 000 Byte
 127
 128 | Zettabyte
 129 | ZB
 130 | 10 ^21^ Byte
 131 | 1 000 000 000 000 000 000 000 Byte
 132
 133 | Yottabyte
 134 | YB
 135 | 10 ^24^ Byte
 136 | 1 000 000 000 000 000 000 000 000 Byte
 137 |===
 138
 139 === Development Status
 140
 141 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.
 142
 143
 144 == Usage
 145
 146 === Factories
 147
 148 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.
 149
 150 [source,java]
 151 ----
 152 // 'long' based
 153 Kilobyte unit = Kilobyte.valueOf(2500)    // 2 500 Byte or "2.50 kB"
 154 Kibibyte unit = Kibibyte.valueOf(512)     // 512 Byte or "0.50 KiB"
 155 Megabyte unit = Megabyte.valueOf(1000000) // 1 000 000 Byte or "1.00 MB"
 156
 157 // 'BigInteger' based
 158 Kilobyte unit = Kilobyte.valueOf(BigInteger.valueOf(2500))    // 2 500 Byte or "2.50 kB"
 159 Kibibyte unit = Kibibyte.valueOf(BigInteger.valueOf(512))     // 512 Byte or "0.50 KiB"
 160 Megabyte unit = Megabyte.valueOf(BigInteger.valueOf(1000000)) // 1 000 000 Byte or "1.00 MB"
 161 ----
 162
 163 The `StorageUnits` class offers two factory methods that automatically pick the best-matching unit for a given number of bytes.
 164
 165 ==== Binary Units
 166
 167 [source,java]
 168 ----
 169 // 'long' based
 170 StorageUnit<?> unit = StorageUnits.binaryValueOf(256)       // Kibibyte (0.25 KiB)
 171 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)   // Mebibyte (1.00 MiB)
 172
 173 // 'BigInteger' based
 174 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256))     // Kibibyte (0.25 MiB)
 175 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
 176 ----
 177
 178 ==== Metric Units
 179
 180 [source,java]
 181 ----
 182 // 'long' based
 183 StorageUnit<?> unit = StorageUnits.metricValueOf(120000)    // Kilobyte (120.00 kB)
 184 StorageUnit<?> unit = StorageUnits.metricValueOf(1000000)   // Megabyte (1.00 MB)
 185
 186 // 'BigInteger' based
 187 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(120000))    // Kilobyte (120.00 kB)
 188 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(1000000))   // Megabyte (1.00 MB)
 189 ----
 190
 191 Additionally high-level factory methods are also available in the `StorageUnits` class.
 192
 193 [source,java]
 194 ----
 195 Kibibyte unit = StorageUnits.kibibyte(1)   // 1 024 Byte
 196 Mebibyte unit = StorageUnits.mebibyte(1)   // 1 048 576 Byte
 197 Gibibyte unit = StorageUnits.gibibyte(1)   // 1 073 741 824 Byte
 198 Tebibyte unit = StorageUnits.tebibyte(1)   // 1 099 511 627 776 Byte
 199 Pebibyte unit = StorageUnits.pebibyte(1)   // 1 125 899 906 842 624 Byte
 200 Exbibyte unit = StorageUnits.exbibyte(1)   // 1 152 921 504 606 846 976 Byte
 201 Zebibyte unit = StorageUnits.zebibyte(1)   // 1 180 591 620 717 411 303 424 Byte
 202 Yobibyte unit = StorageUnits.yobibyte(1)   // 1 208 925 819 614 629 174 706 176 Byte
 203
 204 Kilobyte unit = StorageUnits.kilobyte(1)   // 1 000 Byte
 205 Megabyte unit = StorageUnits.megabyte(1)   // 1 000 000 Byte
 206 Gigabyte unit = StorageUnits.gigabyte(1)   // 1 000 000 000 Byte
 207 Terabyte unit = StorageUnits.terabyte(1)   // 1 000 000 000 000 Byte
 208 Petabyte unit = StorageUnits.petabyte(1)   // 1 000 000 000 000 000 Byte
 209 Exabyte unit = StorageUnits.exabyte(1)     // 1 000 000 000 000 000 000 Byte
 210 Zettabyte unit = StorageUnits.zettabyte(1) // 1 000 000 000 000 000 000 000 Byte
 211 Yottabyte unit = StorageUnits.yottabyte(1) // 1 000 000 000 000 000 000 000 000 Byte
 212 ----
 213
 214 === Add, Subtract, Multiply, Divide
 215
 216 Each unit implements the basic four math operations. All operations retain their original type, e.g. `[Kilobyte] + [Megabyte] = [Kilobyte]`
 217
 218 [source,java]
 219 ----
 220 kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
 221 kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
 222 kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
 223 megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
 224 gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
 225 terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
 226 ----
 227
 228 === Comparison & Equality
 229
 230 Each unit is comparable to each other unit.
 231
 232 [source,java]
 233 ----
 234 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
 235 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
 236 petabyte(3).compareTo(terabyte(3000)) == 0 // true
 237
 238 megabyte(1000).equals(gigabyte(1))         // true
 239 megabyte(1024).equals(gigabyte(1))         // false
 240 terabyte(12).equals(gigabyte(12000))       // true
 241 ----
 242
 243 === Formatting
 244
 245 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.
 246
 247 [source,java]
 248 ----
 249 import static de.xn__ho_hia.utils.storage_unit.StorageUnits.*;
 250
 251 // default pattern '0.00'
 252 terabyte(2).toString()                         // "2.00 TB"
 253 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 254 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 255
 256 // use custom pattern
 257 kilobyte(212345).toString("0.0")                                    // "212345.0 kB"
 258 gibibyte(2123458).asTebibyte().toString("#,###.000")                // "2,073.689 TiB"
 259 kilobyte(120).asMegabyte().add(gigabyte(1)).toString("#,##0.00000") // "1,000.12000 MB"
 260
 261 // use custom pattern with specific Locale
 262 kilobyte(212345).toString("0.0", Locale.GERMAN)                     // "212345,0 kB"
 263 gibibyte(2123458).asTebibyte().toString("#,###.000", Locale.GERMAN) // "2.073,689 TiB"
 264
 265 // use custom format
 266 Format customFormat = new DecimalFormat("#.00000");
 267 terabyte(4).asTebibyte().toString(customFormat) // "3.63798 TiB"
 268
 269 // without creating unit type first
 270 long numberOfBytes = 1_000_000_000_000_000L;
 271 formatAsPetabyte(numberOfBytes) // "1.00 PB"
 272 formatAsTerabyte(numberOfBytes) // "1000.00 TB"
 273 formatAsPebibyte(numberOfBytes) // "0.89 PiB"
 274
 275 // use custom pattern
 276 formatAsTerabyte(numberOfBytes, "#0.#####") // "1000 TB"
 277 formatAsPebibyte(numberOfBytes, "#0.#####") // "0.88818 PiB"
 278
 279 // use custom pattern with specific Locale
 280 formatAsTerabyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "1000 TB"
 281 formatAsPebibyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "0,88818 PiB"
 282
 283 // use custom format
 284 formatAsTerabyte(numberOfBytes, customFormat) // "1000.00000 TB"
 285 formatAsPebibyte(numberOfBytes, customFormat) // ".88818 PiB"
 286 ----
 287
 288 === Conversions
 289
 290 Each unit can be converted to each other unit without loss of information.
 291
 292 [source,java]
 293 ----
 294 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 295 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 296 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 297 ----
 298
 299 Each unit can be expressed as a fraction of another unit (precise up to 24 decimal places)
 300
 301 [source,java]
 302 ----
 303 BigDecimal kilobytes = megabyte(1).inKilobyte()  // 1 000
 304 BigDecimal bytes = kibibyte(2).inByte()          // 2 048
 305 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
 306 ----
 307
 308 === Integration
 309
 310 To use this project just declare the following dependency inside your POM:
 311
 312 [source,xml,subs="attributes,verbatim"]
 313 ----
 314 <dependencies>
 315   <dependency>
 316     <groupId>{project-group}</groupId>
 317     <artifactId>{project-name}</artifactId>
 318     <version>${version.storage-units}</version>
 319   </dependency>
 320 </dependencies>
 321 ----
 322
 323 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].
 324
 325 === Compatibility
 326
 327 This project is compatible with the following Java versions:
 328
 329 .Java compatibility
 330 |===
 331 | | 1.X.Y | 2.X.Y | 3.X.Y
 332
 333 | Java 8
 334 | ✓
 335 | ✓
 336 | ✓
 337
 338 | Java 7
 339 | ✓
 340 |
 341 |
 342 |===
 343
 344 == Reference
 345
 346 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
 347
 348 == License
 349
 350 To the extent possible under law, the author(s) have dedicated all copyright
 351 and related and neighboring rights to this software to the public domain
 352 worldwide. This software is distributed without any warranty.
 353
 354 You should have received a copy of the CC0 Public Domain Dedication along
 355 with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 356
 357 == Mirrors
 358
 359 * https://github.com/sebhoss/{project-name}
 360 * https://bitbucket.org/sebhoss/{project-name}
 361 * https://gitlab.com/sebastian.hoss/{project-name}
 362 * http://v2.pikacode.com/sebhoss/{project-name}
 363 * http://repo.or.cz/{project-name}.git