README.textile

   1 h1. Common-Units
   2
   3 p. This project contains common units. Currently only storage units according to "ISO IEC 80000-13:2008":http://en.wikipedia.org/wiki/ISO/IEC_80000 are implemented.
   4
   5 h2. Storage 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>common-units</artifactId>
 122       <version>1.0.0-SNAPSHOT</version>
 123     </dependency>
 124   </dependencies>
 125
 126 h3. Gradle
 127
 128 bc.
 129   dependencies {
 130     compile 'com.github.sebhoss.units:common-units:1.0.0-SNAPSHOT'
 131   }
 132
 133 h3. Buildr
 134
 135 bc.
 136   compile.with 'com.github.sebhoss.units:common-units:jar:1.0.0-SNAPSHOT'
 137
 138 h3. Ivy
 139
 140 bc.
 141   <dependencies>
 142     <dependency org="com.github.sebhoss.units" name="common-units" rev="1.0.0-SNAPSHOT"/>
 143   </dependencies>
 144
 145 h3. sbt
 146
 147 bc.
 148   libraryDependencies ++= Seq(
 149     "com.github.sebhoss.units" % "common-units" % "1.0.0-SNAPSHOT"
 150   )
 151
 152 h3. Grape
 153
 154 bc.
 155   @Grab(group='com.github.sebhoss.units', module='common-units', version='1.0.0-SNAPSHOT')
 156
 157 h2. Development
 158
 159 h3. License
 160
 161 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 "http://sam.zoy.org/wtfpl/COPYING":http://sam.zoy.org/wtfpl/COPYING for more details.
 162
 163 h3. Setup
 164
 165 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.
 166
 167 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. If you are using an old version of Eclipse run *mvn eclipse:eclipse* first and then import this project into Eclipse.
 168
 169 h3. Versioning
 170
 171 p. This project follows the "semantic versioning":http://semver.org/ guidelines.