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