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