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 [source,java]
 147 ----
 148 // 'long' based
 149 StorageUnit<?> unit = StorageUnits.binaryValueOf(256)       // Kibibyte (0.25 KiB)
 150 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)   // Mebibyte (1.00 MiB)
 151
 152 // 'BigInteger' based
 153 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256))     // Kibibyte (1.00 MiB)
 154 StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
 155 ----
 156
 157 [source,java]
 158 ----
 159 // 'long' based
 160 StorageUnit<?> unit = StorageUnits.metricValueOf(120000)    // Kilobyte (120.00 kB)
 161 StorageUnit<?> unit = StorageUnits.metricValueOf(1000000)   // Megabyte (1.00 MB)
 162
 163 // 'BigInteger' based
 164 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(120000))    // Kilobyte (120.00 kB)
 165 StorageUnit<?> unit = StorageUnits.metricValueOf(BigInteger.valueOf(1000000))   // Megabyte (1.00 MB)
 166 ----
 167
 168 Additionally high-level factory methods are also available in the `StorageUnits` class.
 169
 170 [source,java]
 171 ----
 172 Megabyte unit = StorageUnits.megabyte(1) // 1 000 000 Byte
 173 Kibibyte unit = StorageUnits.kibibyte(8) // 8 192 Byte
 174 Gigabyte unit = StorageUnits.gigabyte(2) // 2 000 000 000 Byte
 175 ----
 176
 177 === Add, Subtract, Multiply, Divide
 178
 179 Each unit implements the basic four math operations.
 180
 181 [source,java]
 182 ----
 183 kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
 184 kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
 185 kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
 186 megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
 187 gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
 188 terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
 189 ----
 190
 191 === compareTo
 192
 193 Each unit is comparable to each other unit.
 194
 195 [source,java]
 196 ----
 197 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
 198 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
 199 petabyte(3).compareTo(terabyte(3000)) == 0 // true
 200 ----
 201
 202 === equals
 203
 204 Each unit can be checked against each other unit.
 205
 206 [source,java]
 207 ----
 208 megabyte(1000).equals(gigabyte(1)) // true
 209 megabyte(1024).equals(gigabyte(1)) // false
 210 terabyte(12).equals(gigabyte(12000))  // false
 211 ----
 212
 213 === toString
 214
 215 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.
 216
 217 [source,java]
 218 ----
 219 terabyte(2).toString()                         // "2.00 TB"
 220 gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
 221 petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
 222 ----
 223
 224 === Conversions
 225
 226 Each unit can be converted to each other unit.
 227
 228 [source,java]
 229 ----
 230 Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 231 Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 232 Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 233 ----
 234
 235 Each unit can be expressed as a fraction of another unit.
 236
 237 [source,java]
 238 ----
 239 BigDecimal kilobytes = megabyte(1).inKilobyte() // 1 000
 240 BigDecimal bytes = kibibyte(2).inByte()         // 2 048
 241 BigDecimal terabytes = gigabyte(15).inTerabyte()   // 0.015
 242 ----
 243
 244 === Integration
 245
 246 To use this project just declare the following dependency inside your POM:
 247
 248 [source,xml,subs="attributes,verbatim"]
 249 ----
 250 <dependencies>
 251   <dependency>
 252     <groupId>{project-group}</groupId>
 253     <artifactId>{project-name}</artifactId>
 254     <version>${version.storage-units}</version>
 255   </dependency>
 256 </dependencies>
 257 ----
 258
 259 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].
 260
 261 === Compatibility
 262
 263 This project is compatible with the following Java versions:
 264
 265 .Java compatibility
 266 |===
 267 | | 1.X.Y | 2.X.Y
 268
 269 | Java 8
 270 | ✓
 271 | ✓
 272
 273 | Java 7
 274 | ✓
 275 |
 276 |===
 277
 278 == Reference
 279
 280 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
 281
 282 == License
 283
 284 This project is licensed under the link:http://unlicense.org/[UNLICENSE]. See the link:UNLICENSE[UNLICENSE file] for more information.