metio / storage-units.
java Public
Code Issues Pull request s Act ions Securit y Insight s
main 2 branches 27 t ags Go to file Code About
Java library for st orage unit s
dependabot[bot] and github-actions[bot] Bump git hub/codeql-act ion from 2 t… … 244137e 3 days ago 283 commit s
# java # storage # storage-unit-converter
.git hub Bump git hub/codeql-act ion from 2 to 3 3 days ago
Readme
.idea add support for gson serializat ion last year 0BSD license
.reuse adjust project name & url last year Code of conduct
Securit y policy
LICENSES updat e project met a last year
Cit e t his repository
storage-unit s-dozer updat e to lat est parent (#35) 11 mont hs ago
Act ivit y
storage-unit s-eclipselink updat e to lat est parent (#35) 11 mont hs ago 13 st ars
2 wat ching
storage-unit s-gson updat e to lat est parent (#35) 11 mont hs ago
2 forks
storage-unit s-jackson updat e to lat est parent (#35) 11 mont hs ago
Report repository
storage-unit s-jakart a updat e to lat est parent (#35) 11 mont hs ago
storage-unit s-mapst ruct updat e to lat est parent (#35) 11 mont hs ago
Releases 19
storage-unit s-model updat e parent to automanage error-prone annot at ions (#51) last mont h
2023.12.5 Latest
storage-unit s-modelmapper updat e to lat est parent (#35) 11 mont hs ago 2 weeks ago
+ 18 releases
storage-unit s-mongodb updat e to lat est parent (#35) 11 mont hs ago
storage-unit s-orika updat e to lat est parent (#35) 11 mont hs ago
Contributors 3
storage-unit s-simple updat e to lat est parent (#35) 11 mont hs ago
.editorconfig updat e project met a last year sebhoss Sebast ian Hoß
.git at t ribut es updat e project met a last year dependabot[bot]
.git ignore updat e project met a last year github-actions[bot]
.mailmap updat e project met a last year
AUT HORS.md updat e project met a last year
Languages
CITAT ION.cff adjust project name & url last year
Java 99.6% Makefile 0.4%
CODE_ OF_ CONDUCT.md updat e project met a last year
CONT RIBUT ING.md updat e project met a last year
LICENSE updat e project met a last year
Makefile updat e project met a last year
README.md updat e project configurat ion (#34) last year
SECURIT Y.md updat e project met a last year
java.propert ies updat e project met a last year
pom.xml Updat e parent to lat est version 2 weeks ago
README.md
Storage-Units
St orage unit s according t o ISO IEC 80000-13:2008 implement ed in Java.
Features
Immut able, t ype- and t hread-safe object model for st orage unit s
Convenience fact ories t o creat e unit s
Basic arit hmet ic operat ors
Comparisons and equalit y checks bet ween unit s
Lossless conversion bet ween all unit s
Human-readable t ext format , including cust om format s
Compat ible wit h any java.lang.Number
Cust om serializers for Jackson, MongoDB, EclipseLink, and ot hers
Available Units
Name Symbol Exponential Absolute
Byt e B 20 Byt e 1 Byt e
Kibibyt e KiB 210 Byt e 1 024 Byt e
Mebibyt e MiB 220 Byt e 1 048 576 Byt e
Gibibyt e GiB 230 Byt e 1 073 741 824 Byt e
Tebibyt e TiB 240 Byt e 1 099 511 627 776 Byt e
Pebibyt e PiB 250 Byt e 1 125 899 906 842 624 Byt e
Exbibyt e EiB 260 Byt e 1 152 921 504 606 846 976 Byt e
Zebibyt e ZiB 270 Byt e 1 180 591 620 717 411 303 424 Byt e
Yobibyt e YiB 280 Byt e 1 208 925 819 614 629 174 706 176 Byt e
Robibyt e RiB 290 Byt e 1 237 940 039 285 380 274 899 124 224 Byt e
Qubibyt e QiB 2100 Byt e 1 267 650 600 228 229 401 496 703 205 376 Byt e
Name Symbol Exponential Absolute
Byt e B 100 Byt e 1 Byt e
Kilobyt e KB 103 Byt e 1 000 Byt e
Megabyt e MB 106 Byt e 1 000 000 Byt e
Gigabyt e GB 109 Byt e 1 000 000 000 Byt e
Terabyt e TB 1012 Byt e 1 000 000 000 000 Byt e
Pet abyt e PB 1015 Byt e 1 000 000 000 000 000 Byt e
Exabyt e EB 1018 Byt e 1 000 000 000 000 000 000 Byt e
Zet t abyt e ZB 1021 Byt e 1 000 000 000 000 000 000 000 Byt e
Yot t abyt e YB 1024 Byt e 1 000 000 000 000 000 000 000 000 Byt e
Ronnabyt e RB 1027 Byt e 1 000 000 000 000 000 000 000 000 000 Byt e
Quet t abyt e QB 1030 Byt e 1 000 000 000 000 000 000 000 000 000 000 Byt e
Usage
Factories
Each unit implement s a Byt e-based st at ic fact ory met hod ( valueOf(BigInteger) or valueOf(long) ) t hat can be
used t o represent a given number of byt es in a specific unit . Not e t hat Long.MAX_VALUE == 8 Exabyte , t hus use
BigInteger if you want t o work wit h anyt hing bigger t han a eight Exabyt e. When in doubt , always use BigInteger .
// 'long' based
Kilobyte unit = Kilobyte.valueOf(500) // 500 Byte or "0.50 kB"
Kibibyte unit = Kibibyte.valueOf(512) // 512 Byte or "0.50 KiB"
Megabyte unit = Megabyte.valueOf(1_000_000) // 1 000 000 Byte or "1.00 MB"
Mebibyte unit = Mebibyte.valueOf(1_048_576) // 1 048 576 Byte or "1.00 MiB"
// 'BigInteger' based
Kilobyte unit = Kilobyte.valueOf(BigInteger.valueOf(500)) // 500 Byte or "0.50 kB"
Kibibyte unit = Kibibyte.valueOf(BigInteger.valueOf(512)) // 512 Byte or "0.50 KiB"
Megabyte unit = Megabyte.valueOf(BigInteger.valueOf(1000000)) // 1 000 000 Byte or "1.00 MB"
Mebibyte unit = Mebibyte.valueOf(BigInteger.valueOf(1_048_576)) // 1 048 576 Byte or "1.00 MB"
The StorageUnits class offers t hree fact ory met hods t hat aut omat ically pick t he best -mat ching unit for a given
number of byt es.
Binary Units
// 'long' based
StorageUnit<?> unit = StorageUnits.binaryValueOf(256) // Kibibyte (0.25 KiB)
StorageUnit<?> unit = StorageUnits.binaryValueOf(1048576) // Mebibyte (1.00 MiB)
// 'BigInteger' based
StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(256)) // Kibibyte (0.25 MiB)
StorageUnit<?> unit = StorageUnits.binaryValueOf(BigInteger.valueOf(1048576)) // Mebibyte (1.00 MiB)
Decimal Units
// 'long' based
StorageUnit<?> unit = StorageUnits.decimalValueOf(120000) // Kilobyte (120.00 kB)
StorageUnit<?> unit = StorageUnits.decimalValueOf(1000000) // Megabyte (1.00 MB)
// 'BigInteger' based
StorageUnit<?> unit = StorageUnits.decimalValueOf(BigInteger.valueOf(120000)) // Kilobyte (120.00 kB)
StorageUnit<?> unit = StorageUnits.decimalValueOf(BigInteger.valueOf(1000000)) // Megabyte (1.00 MB)
Addit ionally high-level fact ory met hods are also available in t he StorageUnits class.
import static wtf.metio.storageunits.model.StorageUnits.*;
Kibibyte unit = kibibyte(1) // 1 024 Byte
Mebibyte unit = mebibyte(1) // 1 048 576 Byte
Gibibyte unit = gibibyte(1) // 1 073 741 824 Byte
Tebibyte unit = tebibyte(1) // 1 099 511 627 776 Byte
Pebibyte unit = pebibyte(1) // 1 125 899 906 842 624 Byte
Exbibyte unit = exbibyte(1) // 1 152 921 504 606 846 976 Byte
Zebibyte unit = zebibyte(1) // 1 180 591 620 717 411 303 424 Byte
Yobibyte unit = yobibyte(1) // 1 208 925 819 614 629 174 706 176 Byte
Robibyte unit = robibyte(1) // 1 237 940 039 285 380 274 899 124 224 Byte
Qubibyte unit = qubibyte(1) // 1 267 650 600 228 229 401 496 703 205 376 Byte
Kilobyte unit = kilobyte(1) // 1 000 Byte
Megabyte unit = megabyte(1) // 1 000 000 Byte
Gigabyte unit = gigabyte(1) // 1 000 000 000 Byte
Terabyte unit = terabyte(1) // 1 000 000 000 000 Byte
Petabyte unit = petabyte(1) // 1 000 000 000 000 000 Byte
Exabyte unit = exabyte(1) // 1 000 000 000 000 000 000 Byte
Zettabyte unit = zettabyte(1) // 1 000 000 000 000 000 000 000 Byte
Yottabyte unit = yottabyte(1) // 1 000 000 000 000 000 000 000 000 Byte
Ronnabyte unit = ronnabyte(1) // 1 000 000 000 000 000 000 000 000 000 Byte
Quettabyte unit = quettabyte(1) // 1 000 000 000 000 000 000 000 000 000 000 Byte
Add, Subtract, Multiply, Divide
Each unit implement s t he basic four mat h operat ions. All operat ions ret ain t heir original t ype, e.g. [Kilobyte] +
[Megabyte] = [Kilobyte]
import static wtf.metio.storageunits.model.StorageUnits.*;
kilobyte(4).add(kilobyte(8)) // 4 Kilobyte + 8 Kilobyte = 12 Kilobyte = 12 000 Byte
kibibyte(1).add(1024) // 1 Kibibyte + 1 024 Byte = 2 Kibibyte = 2 048 Byte
kibibyte(1).subtract(24) // 1 024 Byte - 24 Byte = 1 000 Byte
megabyte(5).subtract(kilobyte(500)) // 5 Megabyte - 500 Kilobyte = 4.5 Megabyte = 4 500 Kilobyte = 4 5
gigabyte(1).multiply(5) // 1 Gigabyte times 5 = 5 Gigabyte
terabyte(1).divide(5) // 1 Terabyte divided by 5 = 0.2 Terabyte = 200 Gigabyte
Comparison & Equality
Each unit is comparable t o each ot her unit .
import static wtf.metio.storageunits.model.StorageUnits.*;
kibibyte(1024).compareTo(mebibyte(1)) == 0 // true
kibibyte(1000).compareTo(mebibyte(1)) == 0 // false
petabyte(3).compareTo(terabyte(3000)) == 0 // true
megabyte(1000).equals(gigabyte(1)) // true
megabyte(1024).equals(gigabyte(1)) // false
terabyte(12).equals(gigabyte(12000)) // true
Formatting
Each unit print s a human-readable st ring, represent ing t he amount of byt es in t he given unit using t he symbol
specified in ISO IEC 80000-13:2008.
import static wtf.metio.storageunits.model.StorageUnits.*;
// default pattern '0.00'
terabyte(2).toString() // "2.00 TB"
gigabyte(1).add(megabyte(200)).toString() // "1.20 GB"
petabyte(1).subtract(terabyte(250)).toString() // "0.75 PB"
// use custom pattern
kilobyte(212345).toString("0.0") // "212345.0 kB"
gibibyte(2123458).asTebibyte().toString("#,###.000") // "2,073.689 TiB"
kilobyte(120).asMegabyte().add(gigabyte(1)).toString("#,##0.00000") // "1,000.12000 MB"
// use custom pattern with specific Locale
kilobyte(212345).toString("0.0", Locale.GERMAN) // "212345,0 kB"
gibibyte(2123458).asTebibyte().toString("#,###.000", Locale.GERMAN) // "2.073,689 TiB"
// use custom format
Format customFormat = new DecimalFormat("#.00000");
terabyte(4).asTebibyte().toString(customFormat) // "3.63798 TiB"
// without creating unit type first
long numberOfBytes = 1_000_000_000_000_000L;
formatAsPetabyte(numberOfBytes) // "1.00 PB"
formatAsTerabyte(numberOfBytes) // "1000.00 TB"
formatAsPebibyte(numberOfBytes) // "0.89 PiB"
// use custom pattern
formatAsTerabyte(numberOfBytes, "#0.#####") // "1000 TB"
formatAsPebibyte(numberOfBytes, "#0.#####") // "0.88818 PiB"
// use custom pattern with specific Locale
formatAsTerabyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "1000 TB"
formatAsPebibyte(numberOfBytes, "#0.#####", Locale.GERMAN) // "0,88818 PiB"
// use custom format
formatAsTerabyte(numberOfBytes, customFormat) // "1000.00000 TB"
formatAsPebibyte(numberOfBytes, customFormat) // ".88818 PiB"
Conversions
Each unit can be convert ed t o each ot her unit wit hout loss of informat ion.
import static wtf.metio.storageunits.model.StorageUnits.*;
Megabyte unit = kilobyte(1000).asMegabyte() // "1.00 MB"
Kilobyte unit = gigabyte(12).asKilobyte() // "12000000.00 kB"
Gigabyte unit = terabyte(1).asGigabyte() // "1000.00 GB"
// convert to best-match
kilobyte(1100).asBestMatchingUnit() // "1.10 MB"
kilobyte(1100).asBestMatchingBinaryUnit() // "1.05 MiB"
kilobyte(1100).asBestMatchingDecimalUnit() // "1.10 MB"
Each unit can be expressed as a fract ion of anot her unit (precise up t o 24 decimal places)
import static wtf.metio.storageunits.model.StorageUnits.*;
BigDecimal kilobytes = megabyte(1).inKilobyte() // 1 000
BigInteger bytes = kibibyte(2).inByte() // 2 048
BigDecimal terabytes = gigabyte(15).inTerabyte() // 0.015
Serialization/Converters/Mappers
Mult iple cust om serializers, convert ers, and mappers are available for all st orage unit s.
Dozer
Use a Dozer convert er like t his:
import static wtf.metio.storageunits.dozer.*;
DozerBeanMapperBuilder.create()
.withCustomConverter(new BigIntegerBinaryStorageUnitConverter())
.withCustomConverter(new BigIntegerDecimalStorageUnitConverter())
.withCustomConverter(new LongBinaryStorageUnitConverter())
.withCustomConverter(new LongDecimalStorageUnitConverter())
.build();
EclipseLink
Use any of t he t hree convert ers like t his:
import static wtf.metio.storageunits.eclipselink.*;
@Entity
public class HardDisk implements Serializable {
@Basic
@Converter (
name="binaryConverter",
converterClass=BinaryStorageUnitConverter.class
)
@Convert("binaryConverter")
public StorageUnit<?> getFreeSize() {
return freeSize;
}
@Basic
@Converter (
name="decimalConverter",
converterClass=DecimalyStorageUnitConverter.class
)
@Convert("decimalConverter")
public StorageUnit<?> getTotalSize() {
return totalSize;
}
GSON
Use a GSON serializer/deserializer like t his:
import static wtf.metio.storageunits.gson.*;
new GsonBuilder()
.registerTypeHierarchyAdapter(StorageUnit.class, new StorageUnitSerializer())
.registerTypeHierarchyAdapter(StorageUnit.class, new BinaryStorageUnitDeserializer())
.registerTypeHierarchyAdapter(StorageUnit.class, new DecimalStorageUnitDeserializer())
.create();
Jackson
Use t he provided StorageUnitModule like t his:
import static wtf.metio.storageunits.jackson.*;
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.registerModule(new StorageUnitModule()); // defaults to binary units
objectMapper.registerModule(new StorageUnitModule(StorageUnitModule.PreferredUnitType.BINARY));
objectMapper.registerModule(new StorageUnitModule(StorageUnitModule.PreferredUnitType.DECIMAL));
Jakarta
Use t he provided AttributeConverter s like t his:
import static wtf.metio.storageunits.jakarta.*;
@Entity
public class HardDisk implements Serializable {
@Convert(converter = BinaryStorageUnitConverter.class)
public StorageUnit<?> getFreeSize() {
return freeSize;
}
@Convert(converter = DecimalStorageUnitConverter.class)
public StorageUnit<?> getTotalSize() {
return totalSize;
}
MapStruct
Use any of t he available mappers like t his:
import static wtf.metio.storageunits.mapstruct.*;
@Mapper( uses = BigIntegerToBinaryUnitMapper.class )
public interface MovieMapper {
DestinationType toDestination(SourceType sourceValue);
ModelMapper
Use any of t he available convert ers like t his:
import static wtf.metio.storageunits.modelmapper.*;
modelMapper.addConverter(new BigIntegerToBinaryUnitConverter());
modelMapper.addConverter(new BigIntegerToDecimalUnitConverter());
modelMapper.addConverter(new LongToBinaryUnitConverter());
modelMapper.addConverter(new LongToDecimalUnitConverter());
modelMapper.addConverter(new StorageUnitToBigIntegerConverter());
MongoDB
Use any of t he t hree codecs like t his:
import static wtf.metio.storageunits.mongodb.*;
CodecRegistry binaryRegistry = CodecRegistries.fromCodecs(new BinaryStorageUnitCodec(), ...);
CodecRegistry decimalRegistry = CodecRegistries.fromCodecs(new DecimalStorageUnitCodec(), ...);
Orika
Use any of t he provided convert ers like t his:
import static wtf.metio.storageunits.orika.*;
ConverterFactory converterFactory = mapperFactory.getConverterFactory();
converterFactory.registerConverter(new BinaryStorageUnitConverter());
converterFactory.registerConverter(new DecimalStorageUnitConverter());
Integration
To use t his project just declare t he following dependency inside your POM:
<dependencies>
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-model</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- Dozer ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-dozer</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- Dozer ONLY -->
<!-- EclipseLink ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-eclipselink</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- EclipseLink ONLY -->
<!-- GSON ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-gson</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- GSON ONLY -->
<!-- Jackson ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-jackson</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- Jackson ONLY -->
<!-- Jakarta ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-jakarta</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- Jakarta ONLY -->
<!-- MapStruct ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-mapstruct</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- MapStruct ONLY -->
<!-- ModelMapper ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-modelmapper</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- ModelMapper ONLY -->
<!-- MongoDB ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-mongodb</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- MongoDB ONLY -->
<!-- Orika ONLY -->
<dependency>
<groupId>wtf.metio.storage-units</groupId>
<artifactId>storage-units-orika</artifactId>
<version>${version.storage-units}</version>
</dependency>
<!-- Orika ONLY -->
</dependencies>
Replace ${version.storage-units} wit h t he lat est release.
Reference
Originally inspired by Twit t ers ut il package.
Alternatives
Byt e Unit s
t riava
License
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
Mirrors
ht t ps://git hub.com/met io/st orage-unit s.java
ht t ps://git lab.com/met io.wt f/st orage-unit s.java
ht t ps://bit bucket .org/met io-wt f/st orage-unit s.java
ht t ps://codeberg.org/met io.wt f/st orage-unit s.java
