README.textile

   1 h1. Storage-Units !https://travis-ci.org/sebhoss/storage-units.png?branch=master!:https://travis-ci.org/sebhoss/storage-units "!https://www.ohloh.net/p/storage-units/widgets/project_thin_badge.gif!":https://www.ohloh.net/p/storage-units "!https://scan.coverity.com/projects/2658/badge.svg!":https://scan.coverity.com/projects/2658
   2
   3 p. Implementation of storage units according to "ISO IEC 80000-13:2008":http://en.wikipedia.org/wiki/ISO/IEC_80000.
   4
   5 h2. Available Units
   6
   7 p. Binary-based units:
   8
   9 |_. Name |_. Symbol |_. Exponential |_. Absolute |
  10 | Kibibyte | KiB | 2 ^10^ Byte | 1 024 Byte |
  11 | Mebibyte | MiB | 2 ^20^ Byte | 1 048 576 Byte |
  12 | Gibibyte | GiB | 2 ^30^ Byte | 1 073 741 824 Byte |
  13 | Tebibyte | TiB | 2 ^40^ Byte | 1 099 511 627 776 Byte |
  14 | Pebibyte | PiB | 2 ^50^ Byte | 1 125 899 906 842 624 Byte |
  15 | Exbibyte | EiB | 2 ^60^ Byte | 1 152 921 504 606 846 976 Byte |
  16 | Zebibyte | ZiB | 2 ^70^ Byte | 1 180 591 620 717 411 303 424 Byte |
  17 | Yobibyte | YiB | 2 ^80^ Byte | 1 208 925 819 614 629 174 706 176 Byte |
  18
  19 p. Metric-based units:
  20
  21 |_. Name |_. Symbol |_. Exponential |_. Absolute |
  22 | Kilobyte | kB | 10 ^3^ Byte | 1 000 Byte |
  23 | Megabyte | MB | 10 ^6^ Byte | 1 000 000 Byte |
  24 | Gigabyte | GB | 10 ^9^ Byte | 1 000 000 000 Byte |
  25 | Terabyte | TB | 10 ^12^ Byte | 1 000 000 000 000 Byte |
  26 | Petabyte | PB | 10 ^15^ Byte | 1 000 000 000 000 000 Byte |
  27 | Exabyte | EB | 10 ^18^ Byte | 1 000 000 000 000 000 000 Byte |
  28 | Zettabyte | ZB | 10 ^21^ Byte | 1 000 000 000 000 000 000 000 Byte |
  29 | Yottabyte | YB | 10 ^24^ Byte | 1 000 000 000 000 000 000 000 000 Byte |
  30
  31 h3. Factories
  32
  33 Each unit implements a Byte-based static factory method (@valueOf(long)@) that can be used to represent a given number of bytes in a specific unit.
  34
  35 bc.
  36   Kilobyte unit = Kilobyte.valueOf(2500)    // 2 500 Byte or "2.50 kB"
  37   Kibibyte unit = Kibibyte.valueOf(512)     // 512 Byte or "0.50 KiB"
  38   Megabyte unit = Megabyte.valueOf(1000000) // 1 000 000 Byte or "1.00 MB"
  39
  40 p. The @StorageUnits@ class offers two factory methods that automatically pick the best-matching unit for a given number of bytes.
  41
  42 bc.
  43   StorageUnit<?> unit = StorageUnits.binaryValueOf(256)       // Kibibyte (0.25 KiB)
  44   StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576)   // Mebibyte (1.00 MiB)
  45
  46 bc.
  47   StorageUnit<?> unit = StorageUnits.metricValueOf(120000)    // Kilobyte (120.00 kB)
  48   StorageUnit<?> unit = StorageUnits.metricValueOf(1000000)   // Megabyte (1.00 MB)
  49
  50 p. Additionally high-level factory methods are also available in the @StorageUnits@ class.
  51
  52 bc.
  53   Megabyte unit = StorageUnits.megabyte(1) // 1 000 000 Byte
  54   Kibibyte unit = StorageUnits.kibibyte(8) // 8 192 Byte
  55   Gigabyte unit = StorageUnits.gigabyte(2) // 2 000 000 000 Byte
  56
  57 h3. Add, Subtract, Multiply, Divide
  58
  59 p. Each unit implements the basic four math operations.
  60
  61 bc.
  62   kilobyte(4).add(kilobyte(8))        // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
  63   kibibyte(1).add(1024)               // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
  64   kibibyte(1).subtract(24)            // 1 024 Byte - 24 Byte = 1 000 Byte
  65   megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 500 000 Byte
  66   gigabyte(1).multiply(5)             // 1 Gigabyte times 5 = 5 Gigabyte
  67   terabyte(1).divide(5)               // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
  68
  69 h3. compareTo
  70
  71 p. Each unit is comparable to each other unit.
  72
  73 bc.
  74   kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
  75   kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
  76   petabyte(3).compareTo(terabyte(3000)) == 0 // true
  77
  78 h3. equals
  79
  80 p. Each unit can be checked against each other unit.
  81
  82 bc.
  83   megabyte(1000).equals(gigabyte(1)) // true
  84   megabyte(1024).equals(gigabyte(1)) // false
  85   terabyte(12).equals(tebibyte(10))  // false
  86
  87 h3. toString
  88
  89 p. 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.
  90
  91 bc.
  92   terabyte(2).toString()                         // "2.00 TB"
  93   gigabyte(1).add(megabyte(200)).toString()      // "1.20 GB"
  94   petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
  95
  96 h3. Conversions
  97
  98 p. Each unit can be converted to each other unit.
  99
 100 bc.
 101   Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
 102   Kilobyte unit = gigabyte(12).asKilobyte()   // "12000000.00 kB"
 103   Gigabyte unit = terabyte(1).asGigabyte()    // "1000.00 GB"
 104
 105 p. Each unit can be expressed as each other unit.
 106
 107 bc.
 108   BigDecimal kilobytes = megabyte(1).inKilobyte() // 1 000
 109   BigDecimal bytes = kibibyte(2).inByte()         // 2 048
 110   BigDecimal amount = gigabyte(15).inTerabyte()   // 0.015
 111
 112
 113 h2. Integration
 114
 115 h3. Maven
 116
 117 bc.
 118   <dependencies>
 119     <dependency>
 120       <groupId>com.github.sebhoss.units</groupId>
 121       <artifactId>storage-units</artifactId>
 122       <version>${version.storage-units}</version>
 123     </dependency>
 124   </dependencies>
 125
 126 p. Replace @${version.storage-units}@ with the "latest release":http://search.maven.org/#search%7Cga%7C1%7Cg%3Acom.github.sebhoss%20a%3Astorage-units
 127
 128 h2. Development
 129
 130 h3. License
 131
 132 p. This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See LICENSE or "http://www.wtfpl.net/":http://www.wtfpl.net/ for more details.
 133
 134 h3. Setup
 135
 136 p. This project is using "Java":http://www.oracle.com/technetwork/java/javase/downloads/index.html, "Maven":http://maven.apache.org/, "Eclipse":http://eclipse.org/ and "Git":http://git-scm.com/ as the main development tools. To build the project yourself just download & install at least Java 7 & Maven 3.0 and call *mvn install* inside the project folder. Maven should then proceed to clean, build, test, package and install this project.
 137
 138 p. Use the project import wizard from Eclipse to import this project. The integrated m2e-plugin will automatically setup the needed configuration files for Eclipse.
 139
 140 h3. Versioning
 141
 142 p. This project follows the "semantic versioning":http://semver.org/ guidelines.