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 | 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-prefixed 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 ==== Binary Units
 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 ==== Metric Units
 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 === Comparison & Equality
 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 megabyte(1000).equals(gigabyte(1))         // true
 228 megabyte(1024).equals(gigabyte(1))         // false
 229 terabyte(12).equals(gigabyte(12000))       // true
 230 ----
 231
 232 === Formatting
 233
 234 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.
 235
 236 [source,java]
 237 ----
 238 // default pattern '0.00'
 239 terabyte(2).toString()                         // "2.00 TB"
 240 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 241 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 242
 243 // use custom pattern
 244 kilobyte(212345).toString("0.0")                                    // "212345.0 kB"
 245 gibibyte(2123458).asTebibyte().toString("#,###.000")                // "2,073.689 TiB"
 246 kilobyte(120).asMegabyte().add(gigabyte(1)).toString("#,##0.00000") // "1,000.12000 MB"
 247
 248 // use custom format
 249 Format customFormat = new DecimalFormat("#.00000");
 250 terabyte(4).asTebibyte().toString(customFormat) // "3.63798 TiB"
 251 ----
 252
 253 === Conversions
 254
 255 Each unit can be converted to each other unit.
 256
 257 [source,java]
 258 ----
 259 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 260 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 261 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 262 ----
 263
 264 Each unit can be expressed as a fraction of another unit.
 265
 266 [source,java]
 267 ----
 268 BigDecimal kilobytes = megabyte(1).inKilobyte()  // 1 000
 269 BigDecimal bytes = kibibyte(2).inByte()          // 2 048
 270 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
 271 ----
 272
 273 === Integration
 274
 275 To use this project just declare the following dependency inside your POM:
 276
 277 [source,xml,subs="attributes,verbatim"]
 278 ----
 279 <dependencies>
 280   <dependency>
 281     <groupId>{project-group}</groupId>
 282     <artifactId>{project-name}</artifactId>
 283     <version>${version.storage-units}</version>
 284   </dependency>
 285 </dependencies>
 286 ----
 287
 288 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].
 289
 290 === Compatibility
 291
 292 This project is compatible with the following Java versions:
 293
 294 .Java compatibility
 295 |===
 296 | | 1.X.Y | 2.X.Y | 3.X.Y
 297
 298 | Java 8
 299 | ✓
 300 | ✓
 301 | ✓
 302
 303 | Java 7
 304 | ✓
 305 |
 306 |
 307 |===
 308
 309 == Reference
 310
 311 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
 312
 313 == License
 314
 315 To the extent possible under law, the author(s) have dedicated all copyright
 316 and related and neighboring rights to this software to the public domain
 317 worldwide. This software is distributed without any warranty.
 318
 319 You should have received a copy of the CC0 Public Domain Dedication along
 320 with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
 321
 322 == Mirrors
 323
 324 * https://github.com/sebhoss/{project-name}
 325 * https://bitbucket.org/sebhoss/{project-name}
 326 * https://gitlab.com/sebastian.hoss/{project-name}
 327 * http://v2.pikacode.com/sebhoss/{project-name}
 328 * http://repo.or.cz/{project-name}.git