0
# Data Size and Units
1

2
Data size management capabilities for handling sizes with SI and IEC prefix support, including human-readable parsing and unit conversion.
3

4
## DataSize Class
5

6
The `DataSize` class represents an immutable, thread-safe data size with support for various units and human-readable parsing.
7

8
### Static Factory Methods
9

10
Create DataSize instances using SI (decimal) prefixes:
11

12
```java { .api }
13
public static DataSize bytes(long count);
14
public static DataSize kilobytes(long count);
15
public static DataSize megabytes(long count);
16
public static DataSize gigabytes(long count);
17
public static DataSize terabytes(long count);
18
public static DataSize petabytes(long count);
19
```
20

21
Create DataSize instances using IEC (binary) prefixes:
22

23
```java { .api }
24
public static DataSize kibibytes(long count);
25
public static DataSize mebibytes(long count);
26
public static DataSize gibibytes(long count);
27
public static DataSize tebibytes(long count);
28
public static DataSize pebibytes(long count);
29
```
30

31
### Parsing Methods
32

33
Parse human-readable strings into DataSize objects:
34

35
```java { .api }
36
public static DataSize parse(CharSequence size);
37
public static DataSize parse(CharSequence size, DataSizeUnit defaultUnit);
38
```
39

40
**Parameters:**
41
- `size` - String representation like "128 MB", "5 GB", "1024 bytes"
42
- `defaultUnit` - Unit to use when no unit is specified in the string
43

44
**Supported Formats:**
45
- Numbers with units: "128 MB", "5 GB", "1024 KiB"
46
- Case-insensitive units: "mb", "MB", "Mb"
47
- Various unit spellings: "byte", "bytes", "kilobyte", "kilobytes"
48
- Both SI and IEC prefixes: "KB" (kilobytes), "KiB" (kibibytes)
49

50
**Throws:**
51
- `IllegalArgumentException` - If the input cannot be parsed or contains invalid units
52

53
### Instance Methods
54

55
```java { .api }
56
public long getQuantity();
57
public DataSizeUnit getUnit();
58
```
59

60
Convert to specific units:
61

62
```java { .api }
63
public long toBytes();
64
public long toKilobytes();
65
public long toMegabytes();
66
public long toGigabytes();
67
public long toTerabytes();
68
public long toPetabytes();
69
public long toKibibytes();
70
public long toMebibytes();
71
public long toGibibytes();
72
public long toTebibytes();
73
public long toPebibytes();
74
```
75

76
Standard object methods:
77

78
```java { .api }
79
public boolean equals(Object obj);
80
public int hashCode();
81
public String toString();
82
public int compareTo(DataSize other);
83
```
84

85
## DataSizeUnit Enum
86

87
Enumeration of data size units supporting both SI (decimal) and IEC (binary) prefixes.
88

89
### Enum Constants
90

91
SI (Decimal) Units:
92
```java { .api }
93
BYTES(8L)                                    // 8 bits
94
KILOBYTES(8L * 1000L)                       // 1000 bytes
95
MEGABYTES(8L * 1000L * 1000L)               // 1000 kilobytes
96
GIGABYTES(8L * 1000L * 1000L * 1000L)       // 1000 megabytes
97
TERABYTES(8L * 1000L * 1000L * 1000L * 1000L)       // 1000 gigabytes
98
PETABYTES(8L * 1000L * 1000L * 1000L * 1000L * 1000L) // 1000 terabytes
99
```
100

101
IEC (Binary) Units:
102
```java { .api }
103
KIBIBYTES(8L * 1024L)                       // 1024 bytes
104
MEBIBYTES(8L * 1024L * 1024L)               // 1024 kibibytes
105
GIBIBYTES(8L * 1024L * 1024L * 1024L)       // 1024 mebibytes
106
TEBIBYTES(8L * 1024L * 1024L * 1024L * 1024L)       // 1024 gibibytes
107
PEBIBYTES(8L * 1024L * 1024L * 1024L * 1024L * 1024L) // 1024 tebibytes
108
```
109

110
### Unit Conversion Methods
111

112
```java { .api }
113
public long convert(long size, DataSizeUnit unit);
114
```
115

116
**Parameters:**
117
- `size` - The magnitude of the size
118
- `unit` - The source unit to convert from
119

120
**Returns:** The converted size in the current unit
121

122
Convert to specific units:
123

124
```java { .api }
125
public long toBytes(long l);
126
public long toKilobytes(long l);
127
public long toMegabytes(long l);
128
public long toGigabytes(long l);
129
public long toTerabytes(long l);
130
public long toPetabytes(long l);
131
public long toKibibytes(long l);
132
public long toMebibytes(long l);
133
public long toGibibytes(long l);
134
public long toTebibytes(long l);
135
public long toPebibytes(long l);
136
```
137

138
## Usage Examples
139

140
### Basic Creation
141

142
```java
143
// Create using factory methods
144
DataSize oneGb = DataSize.gigabytes(1);
145
DataSize oneMb = DataSize.megabytes(1);
146
DataSize oneKib = DataSize.kibibytes(1024);
147

148
// Get quantity and unit
149
long quantity = oneGb.getQuantity(); // 1
150
DataSizeUnit unit = oneGb.getUnit(); // GIGABYTES
151
```
152

153
### Parsing Examples
154

155
```java
156
// Parse various formats
157
DataSize size1 = DataSize.parse("128 MB");
158
DataSize size2 = DataSize.parse("5 GB");
159
DataSize size3 = DataSize.parse("1024 KiB");
160
DataSize size4 = DataSize.parse("500"); // Uses default unit (bytes)
161
DataSize size5 = DataSize.parse("500", DataSizeUnit.KILOBYTES); // 500 KB
162

163
// Case insensitive and flexible spelling
164
DataSize flexible1 = DataSize.parse("128 mb");
165
DataSize flexible2 = DataSize.parse("5 gigabytes");
166
DataSize flexible3 = DataSize.parse("1024 kibibyte");
167
```
168

169
### Unit Conversion
170

171
```java
172
DataSize original = DataSize.parse("1 GB");
173

174
// Convert using DataSize methods
175
long bytes = original.toBytes();         // 1,000,000,000
176
long kilobytes = original.toKilobytes(); // 1,000,000
177
long megabytes = original.toMegabytes(); // 1,000
178

179
// Convert using DataSizeUnit methods
180
long convertedBytes = DataSizeUnit.BYTES.convert(1, DataSizeUnit.GIGABYTES);
181
long convertedKb = DataSizeUnit.KILOBYTES.convert(1, DataSizeUnit.GIGABYTES);
182
```
183

184
### Comparison and Sorting
185

186
```java
187
DataSize size1 = DataSize.megabytes(500);
188
DataSize size2 = DataSize.gigabytes(1);
189

190
// Comparison (compares based on byte values)
191
int comparison = size1.compareTo(size2); // negative (500 MB < 1 GB)
192

193
// Equality (compares quantity and unit exactly)
194
DataSize mb500a = DataSize.megabytes(500);
195
DataSize mb500b = DataSize.megabytes(500);
196
boolean equal = mb500a.equals(mb500b); // true
197

198
// Note: Different units with same byte value are NOT equal
199
DataSize bytes1000000 = DataSize.bytes(1000000);
200
DataSize megabyte1 = DataSize.megabytes(1);
201
boolean equalBytes = bytes1000000.equals(megabyte1); // false (different units)
202
boolean equalComparison = bytes1000000.compareTo(megabyte1) == 0; // true (same byte value)
203
```
204

205
### String Representation
206

207
```java
208
DataSize size = DataSize.gigabytes(2);
209
String str = size.toString(); // "2 gigabytes"
210

211
DataSize singleUnit = DataSize.gigabytes(1);
212
String singleStr = singleUnit.toString(); // "1 gigabyte" (singular)
213
```
214

215
## Error Handling
216

217
The parsing methods throw `IllegalArgumentException` for invalid input:
218

219
```java
220
try {
221
    DataSize.parse("invalid size"); // Throws IllegalArgumentException
222
} catch (IllegalArgumentException e) {
223
    // Handle parsing error
224
}
225

226
try {
227
    DataSize.parse("128 XB"); // Throws IllegalArgumentException (unknown unit)
228
} catch (IllegalArgumentException e) {
229
    // Handle unknown unit error
230
}
231
```