README.asciidoc.bak

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