2 Sebastian Hoß <https://github.com/sebhoss[@sebhoss]>
4 :project-name: storage-units
5 :project-group: com.github.sebhoss
6 :coverity-project: 2658
8 :toc-placement: preamble
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}"]
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].
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
32 | Name | Symbol | Exponential | Absolute
52 | 1 099 511 627 776 Byte
57 | 1 125 899 906 842 624 Byte
62 | 1 152 921 504 606 846 976 Byte
67 | 1 180 591 620 717 411 303 424 Byte
72 | 1 208 925 819 614 629 174 706 176 Byte
77 | Name | Symbol | Exponential | Absolute
97 | 1 000 000 000 000 Byte
102 | 1 000 000 000 000 000 Byte
107 | 1 000 000 000 000 000 000 Byte
112 | 1 000 000 000 000 000 000 000 Byte
117 | 1 000 000 000 000 000 000 000 000 Byte
120 === Development Status
122 All units according to ISO IEC 80000-13:2008 are implemented. This project is in maintenance mode.
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.
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"
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"
144 The `StorageUnits` class offers two factory methods that automatically pick the best-matching unit for a given number of bytes.
149 StorageUnit<?> unit = StorageUnits.binaryValueOf(256) // Kibibyte (0.25 KiB)
150 StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576) // Mebibyte (1.00 MiB)
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)
160 StorageUnit<?> unit = StorageUnits.metricValueOf(120000) // Kilobyte (120.00 kB)
161 StorageUnit<?> unit = StorageUnits.metricValueOf(1000000) // Megabyte (1.00 MB)
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)
168 Additionally high-level factory methods are also available in the `StorageUnits` class.
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
177 === Add, Subtract, Multiply, Divide
179 Each unit implements the basic four math operations.
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
193 Each unit is comparable to each other unit.
197 kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
198 kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
199 petabyte(3).compareTo(terabyte(3000)) == 0 // true
204 Each unit can be checked against each other unit.
208 megabyte(1000).equals(gigabyte(1)) // true
209 megabyte(1024).equals(gigabyte(1)) // false
210 terabyte(12).equals(gigabyte(12000)) // false
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.
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"
226 Each unit can be converted to each other unit.
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"
235 Each unit can be expressed as a fraction of another unit.
239 BigDecimal kilobytes = megabyte(1).inKilobyte() // 1 000
240 BigDecimal bytes = kibibyte(2).inByte() // 2 048
241 BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
246 To use this project just declare the following dependency inside your POM:
248 [source,xml,subs="attributes,verbatim"]
252 <groupId>{project-group}</groupId>
253 <artifactId>{project-name}</artifactId>
254 <version>${version.storage-units}</version>
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].
263 This project is compatible with the following Java versions:
280 Originally inspired by link:https://github.com/twitter/util#space[Twitters util] package.
284 This project is licensed under the link:http://unlicense.org/[UNLICENSE]. See the link:UNLICENSE[UNLICENSE file] for more information.