README.asciidoc

   1 = Storage-Units
   2 Sebastian Hoß <https://github.com/sebhoss[@sebhoss]>
   3 :github-org: sebhoss
   4 :project-name: storage-units
   5 :project-group: com.github.sebhoss
   6 :coverity-project: 2658
   7 :toc:
   8 :toc-placement: preamble
   9
  10 image:https://img.shields.io/maven-central/v/{project-group}/{project-name}.svg?style=flat-square["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/{project-group}/{project-name}"]
  11 image:https://www.openhub.net/p/{project-name}/widgets/project_thin_badge.gif["Open Hub statistics", link="https://www.ohloh.net/p/{project-name}"]
  12 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}"]
  13 image:https://img.shields.io/coveralls/{github-org}/{project-name}/master.svg?style=flat-square["", link="https://coveralls.io/github/{github-org}/{project-name}"]
  14 image:https://scan.coverity.com/projects/{coverity-project}/badge.svg["Coverity Scan Result", link="https://scan.coverity.com/projects/{coverity-project}"]
  15 image:https://badges.gitter.im/Join%20Chat.svg["Gitter", link="https://gitter.im/{github-org}/{project-name}"]
  16
  17 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].
  18
  19 === Features
  20
  21 * Type safe object model for storage units
  22 * Factories to create those objects
  23 * Basic math operators
  24 * Comparisons and equality
  25 * Lossless conversion between all units
  26 * Human readable text format
  27
  28 ==== Available Units
  29
  30 .Binary-based units
  31 |===
  32 | Name | Symbol | Exponential | Absolute
  33
  34 | Kibibyte
  35 | KiB
  36 | 2 ^10^ Byte
  37 | 1 024 Byte
  38
  39 | Mebibyte
  40 | MiB
  41 | 2 ^20^ Byte
  42 | 1 048 576 Byte
  43
  44 | Gibibyte
  45 | GiB
  46 | 2 ^30^ Byte
  47 | 1 073 741 824 Byte
  48
  49 | Tebibyte
  50 | TiB
  51 | 2 ^40^ Byte
  52 | 1 099 511 627 776 Byte
  53
  54 | Pebibyte
  55 | PiB
  56 | 2 ^50^ Byte
  57 | 1 125 899 906 842 624 Byte
  58
  59 | Exbibyte
  60 | EiB
  61 | 2 ^60^ Byte
  62 | 1 152 921 504 606 846 976 Byte
  63
  64 | Zebibyte
  65 | ZiB
  66 | 2 ^70^ Byte
  67 | 1 180 591 620 717 411 303 424 Byte
  68
  69 | Yobibyte
  70 | YiB
  71 | 2 ^80^ Byte
  72 | 1 208 925 819 614 629 174 706 176 Byte
  73 |===
  74
  75 .Metric-based units
  76 |===
  77 | Name | Symbol | Exponential | Absolute
  78
  79 | Kilobyte
  80 | kB
  81 | 10 ^3^ Byte
  82 | 1 000 Byte
  83
  84 | Megabyte
  85 | MB
  86 | 10 ^6^ Byte
  87 | 1 000 000 Byte
  88
  89 | Gigabyte
  90 | GB
  91 | 10 ^9^ Byte
  92 | 1 000 000 000 Byte
  93
  94 | Terabyte
  95 | TB
  96 | 10 ^12^ Byte
  97 | 1 000 000 000 000 Byte
  98
  99 | Petabyte
 100 | PB
 101 | 10 ^15^ Byte
 102 | 1 000 000 000 000 000 Byte
 103
 104 | Exabyte
 105 | EB
 106 | 10 ^18^ Byte
 107 | 1 000 000 000 000 000 000 Byte
 108
 109 | Zettabyte
 110 | ZB
 111 | 10 ^21^ Byte
 112 | 1 000 000 000 000 000 000 000 Byte
 113
 114 | Yottabyte
 115 | YB
 116 | 10 ^24^ Byte
 117 | 1 000 000 000 000 000 000 000 000 Byte
 118 |===
 119
 120 === Development Status
 121
 122 All units according to ISO IEC 80000-13:2008 are implemented. This project is in maintenance mode.
 123
 124
 125 == Usage
 126
 127 === Factories
 128
 129 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.
 130
 131 [source,java]
 132 ----
 133 // 'long' based
 134 Kilobyte unit = Kilobyte.valueOf(2500)    // 2 500 Byte or "2.50 kB"
 135 Kibibyte unit = Kibibyte.valueOf(512)     // 512 Byte or "0.50 KiB"
 136 Megabyte unit = Megabyte.valueOf(1000000) // 1 000 000 Byte or "1.00 MB"
 137
 138 // 'BigInteger' based
 139 Kilobyte unit = Kilobyte.valueOf(BigInteger.valueOf(2500))    // 2 500 Byte or "2.50 kB"
 140 Kibibyte unit = Kibibyte.valueOf(BigInteger.valueOf(512))     // 512 Byte or "0.50 KiB"
 141 Megabyte unit = Megabyte.valueOf(BigInteger.valueOf(1000000)) // 1 000 000 Byte or "1.00 MB"
 142 ----
 143
 144 The `StorageUnits` class offers two factory methods that automatically pick the best-matching unit for a given number of bytes.
 145
 146 ==== binaryValueOf
 147
 148 [source,java]
 149 ----
 150 // 'long' based
 151 StorageUnit<?> unit = StorageUnits.binaryValueOf(256)       // Kibibyte (0.25 KiB)
 152 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)   // Mebibyte (1.00 MiB)
 153
 154 // 'BigInteger' based
 155 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256))     // Kibibyte (0.25 MiB)
 156 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
 157 ----
 158
 159 ==== metricValueOf
 160
 161 [source,java]
 162 ----
 163 // 'long' based
 164 StorageUnit<?> unit = StorageUnits.metricValueOf(120000)    // Kilobyte (120.00 kB)
 165 StorageUnit<?> unit = StorageUnits.metricValueOf(1000000)   // Megabyte (1.00 MB)
 166
 167 // 'BigInteger' based
 168 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(120000))    // Kilobyte (120.00 kB)
 169 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(1000000))   // Megabyte (1.00 MB)
 170 ----
 171
 172 Additionally high-level factory methods are also available in the `StorageUnits` class.
 173
 174 [source,java]
 175 ----
 176 Kibibyte unit = StorageUnits.kibibyte(1)   // 1 024 Byte
 177 Mebibyte unit = StorageUnits.mebibyte(1)   // 1 048 576 Byte
 178 Gibibyte unit = StorageUnits.gibibyte(1)   // 1 073 741 824 Byte
 179 Tebibyte unit = StorageUnits.tebibyte(1)   // 1 099 511 627 776 Byte
 180 Pebibyte unit = StorageUnits.pebibyte(1)   // 1 125 899 906 842 624 Byte
 181 Exbibyte unit = StorageUnits.exbibyte(1)   // 1 152 921 504 606 846 976 Byte
 182 Zebibyte unit = StorageUnits.zebibyte(1)   // 1 180 591 620 717 411 303 424 Byte
 183 Yobibyte unit = StorageUnits.yobibyte(1)   // 1 208 925 819 614 629 174 706 176 Byte
 184
 185 Kilobyte unit = StorageUnits.kilobyte(1)   // 1 000 Byte
 186 Megabyte unit = StorageUnits.megabyte(1)   // 1 000 000 Byte
 187 Gigabyte unit = StorageUnits.gigabyte(1)   // 1 000 000 000 Byte
 188 Terabyte unit = StorageUnits.terabyte(1)   // 1 000 000 000 000 Byte
 189 Petabyte unit = StorageUnits.petabyte(1)   // 1 000 000 000 000 000 Byte
 190 Exabyte unit = StorageUnits.exabyte(1)     // 1 000 000 000 000 000 000 Byte
 191 Zettabyte unit = StorageUnits.zettabyte(1) // 1 000 000 000 000 000 000 000 Byte
 192 Yottabyte unit = StorageUnits.yottabyte(1) // 1 000 000 000 000 000 000 000 000 Byte
 193 ----
 194
 195 === Add, Subtract, Multiply, Divide
 196
 197 Each unit implements the basic four math operations. All operations retain their original type, e.g. `[Kilobyte] + [Megabyte] = [Kilobyte]`
 198
 199 [source,java]
 200 ----
 201 kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
 202 kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
 203 kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
 204 megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
 205 gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
 206 terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
 207 ----
 208
 209 === compareTo
 210
 211 Each unit is comparable to each other unit.
 212
 213 [source,java]
 214 ----
 215 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
 216 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
 217 petabyte(3).compareTo(terabyte(3000)) == 0 // true
 218 ----
 219
 220 === equals
 221
 222 Each unit can be checked against each other unit.
 223
 224 [source,java]
 225 ----
 226 megabyte(1000).equals(gigabyte(1)) // true
 227 megabyte(1024).equals(gigabyte(1)) // false
 228 terabyte(12).equals(gigabyte(12000))  // false
 229 ----
 230
 231 === toString
 232
 233 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.
 234
 235 [source,java]
 236 ----
 237 terabyte(2).toString()                         // "2.00 TB"
 238 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 239 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 240 ----
 241
 242 === Conversions
 243
 244 Each unit can be converted to each other unit.
 245
 246 [source,java]
 247 ----
 248 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 249 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 250 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 251 ----
 252
 253 Each unit can be expressed as a fraction of another unit.
 254
 255 [source,java]
 256 ----
 257 BigDecimal kilobytes = megabyte(1).inKilobyte()  // 1 000
 258 BigDecimal bytes = kibibyte(2).inByte()          // 2 048
 259 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
 260 ----
 261
 262 === Integration
 263
 264 To use this project just declare the following dependency inside your POM:
 265
 266 [source,xml,subs="attributes,verbatim"]
 267 ----
 268 <dependencies>
 269   <dependency>
 270     <groupId>{project-group}</groupId>
 271     <artifactId>{project-name}</artifactId>
 272     <version>${version.storage-units}</version>
 273   </dependency>
 274 </dependencies>
 275 ----
 276
 277 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].
 278
 279 === Compatibility
 280
 281 This project is compatible with the following Java versions:
 282
 283 .Java compatibility
 284 |===
 285 | | 1.X.Y | 2.X.Y
 286
 287 | Java 8
 288 | ✓
 289 | ✓
 290
 291 | Java 7
 292 | ✓
 293 |
 294 |===
 295
 296 == Reference
 297
 298 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
 299
 300 == License
 301
 302 This project is licensed under the link:http://unlicense.org/[UNLICENSE]. See the link:UNLICENSE[UNLICENSE file] for more information.