DataSize

DataSize is an amount of data, such as an upload limit or a cache size, stored as a whole number of bytes.

Why use it

Configuration can say 10MB instead of 10485760, and code reads a typed value instead of guessing the unit. The default conversion service turns 10MB, 512KB, 100 (bytes) and plain ints (bytes) into a DataSize. Declare a @Value parameter or a @ConfigurationProperties field of this type and use the result.

Rules for the text form:

Use a plain int when the value is a count, not an amount of data.

Example

# lib/resources/application.properties
shop.upload.max-size=10MB

import 'package:spring_core_dart/spring_core_dart.dart';

@Service()
class UploadGuard {
  UploadGuard(@Value(r'${shop.upload.max-size:5MB}') this.maxSize);

  final DataSize maxSize;

  // Rejects bodies larger than the configured size.
  bool accepts(List<int> body) => body.length <= maxSize.toBytes();
}

In code:

DataSize.parse('10MB').toBytes(); // 10485760
DataSize.parse('2', unit: DataUnit.kilobytes).toBytes(); // 2048
DataSize.ofMegabytes(5).compareTo(DataSize.ofGigabytes(1)); // negative: smaller
DataSize.ofKilobytes(1536).toMegabytes(); // 1 (rounded toward zero)
DataSize.ofBytes(1024).toString(); // '1024B'

DataSize implements Comparable<DataSize> and ==. It has no < operator; compare with compareTo.

Members

Name Type Meaning
DataSize.ofBytes(int) constructor A size of exactly that many bytes.
DataSize.ofKilobytes(int), ofMegabytes, ofGigabytes, ofTerabytes constructor A size in that unit.
DataSize.of(int amount, DataUnit unit) constructor A size in a unit chosen at run time.
DataSize.parse(text, {unit}) DataSize Reads 10MB, 512kb, 100. A number without a unit is in unit (bytes unless given). Throws FormatException otherwise.
toBytes() int The size in bytes.
toKilobytes(), toMegabytes(), toGigabytes(), toTerabytes() int The size in whole units, rounded toward zero.
isNegative bool Whether the size is below zero.
toString() String The bytes with a B suffix (10485760B); parse reads it back.

DataUnit values: bytes (B), kilobytes (KB), megabytes (MB), gigabytes (GB), terabytes (TB). Each has a suffix and a byteCount.

In Spring (Java)

@ConfigurationProperties("shop.upload")
class UploadProperties {
  private DataSize maxSize = DataSize.ofMegabytes(5);
  // getter and setter
}

DataSize size = DataSize.parse("10MB");
long bytes = size.toBytes();

Differences that matter:

See also