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