Duration Utilities

/**
 * Minimum valid Duration: approximately -10,000 years
 */
public static final Duration MIN_VALUE;

/**
 * Maximum valid Duration: approximately +10,000 years  
 */
public static final Duration MAX_VALUE;

/**
 * Zero duration constant
 */
public static final Duration ZERO;

/**
 * Creates a Duration from number of days.
 * 
 * @param days Number of days
 * @return Duration representing the specified number of days
 */
public static Duration fromDays(long days);

/**
 * Creates a Duration from number of hours.
 * 
 * @param hours Number of hours
 * @return Duration representing the specified number of hours
 */
public static Duration fromHours(long hours);

/**
 * Creates a Duration from number of minutes.
 * 
 * @param minutes Number of minutes
 * @return Duration representing the specified number of minutes
 */
public static Duration fromMinutes(long minutes);

/**
 * Creates a Duration from number of seconds.
 * 
 * @param seconds Number of seconds
 * @return Duration representing the specified number of seconds
 */
public static Duration fromSeconds(long seconds);

/**
 * Creates a Duration from number of milliseconds.
 * 
 * @param milliseconds Number of milliseconds
 * @return Duration representing the specified number of milliseconds
 */
public static Duration fromMillis(long milliseconds);

/**
 * Creates a Duration from number of microseconds.
 * 
 * @param microseconds Number of microseconds
 * @return Duration representing the specified number of microseconds
 */
public static Duration fromMicros(long microseconds);

/**
 * Creates a Duration from number of nanoseconds.
 * 
 * @param nanoseconds Number of nanoseconds
 * @return Duration representing the specified number of nanoseconds
 */
public static Duration fromNanos(long nanoseconds);

/**
 * Converts Duration to number of days.
 * Result is rounded towards 0 to the nearest day.
 * 
 * @param duration Duration to convert
 * @return Number of days
 */
public static long toDays(Duration duration);

/**
 * Converts Duration to number of hours.
 * Result is rounded towards 0 to the nearest hour.
 * 
 * @param duration Duration to convert
 * @return Number of hours
 */
public static long toHours(Duration duration);

/**
 * Converts Duration to number of minutes.
 * Result is rounded towards 0 to the nearest minute.
 * 
 * @param duration Duration to convert
 * @return Number of minutes
 */
public static long toMinutes(Duration duration);

/**
 * Converts Duration to number of seconds.
 * Result is rounded towards 0 to the nearest second.
 * 
 * @param duration Duration to convert
 * @return Number of seconds
 */
public static long toSeconds(Duration duration);

/**
 * Converts Duration to number of seconds as double.
 * This method should be used for APIs that only accept double values.
 * May lose precision.
 * 
 * @param duration Duration to convert
 * @return Number of seconds as double with fractional component
 */
public static double toSecondsAsDouble(Duration duration);

/**
 * Converts Duration to number of milliseconds.
 * Result is rounded towards 0 to the nearest millisecond.
 * 
 * @param duration Duration to convert
 * @return Number of milliseconds
 */
public static long toMillis(Duration duration);

/**
 * Converts Duration to number of microseconds.
 * Result is rounded towards 0 to the nearest microsecond.
 * 
 * @param duration Duration to convert
 * @return Number of microseconds
 */
public static long toMicros(Duration duration);

/**
 * Converts Duration to number of nanoseconds.
 * 
 * @param duration Duration to convert
 * @return Number of nanoseconds
 */
public static long toNanos(Duration duration);

/**
 * Converts Duration to string format.
 * Uses 3, 6, or 9 fractional digits as needed for precision.
 * Examples: "1s", "1.010s", "1.000000100s", "-3.100s"
 * 
 * @param duration Duration to convert
 * @return String representation of duration
 * @throws IllegalArgumentException if duration is invalid
 */
public static String toString(Duration duration);

/**
 * Parses a string to produce a Duration.
 * 
 * @param value String in duration format (e.g., "1.5s", "-2.100s")
 * @return Duration parsed from string
 * @throws ParseException if string is not in valid duration format
 */
public static Duration parse(String value) throws ParseException;

/**
 * Parses a string to produce a Duration.
 * Same as parse() but throws IllegalArgumentException instead of ParseException.
 * 
 * @param value String in duration format
 * @return Duration parsed from string
 * @throws IllegalArgumentException if parsing fails
 */
public static Duration parseUnchecked(String value);

/**
 * Checks if the given Duration is valid.
 * Seconds must be in range [-315,576,000,000, +315,576,000,000].
 * Nanos must be in range [-999,999,999, +999,999,999].
 * Seconds and nanos must have the same sign for durations >= 1 second.
 * 
 * @param duration Duration to validate
 * @return true if duration is valid, false otherwise
 */
public static boolean isValid(Duration duration);

/**
 * Checks if the given seconds and nanos form a valid Duration.
 * 
 * @param seconds Seconds component
 * @param nanos Nanoseconds component
 * @return true if combination is valid, false otherwise
 */
public static boolean isValid(long seconds, int nanos);

/**
 * Validates a Duration and throws exception if invalid.
 * 
 * @param duration Duration to validate
 * @return The same duration if valid
 * @throws IllegalArgumentException if duration is invalid
 */
public static Duration checkValid(Duration duration);

/**
 * Builds and validates a Duration from builder.
 * 
 * @param durationBuilder Duration builder to build and validate
 * @return Valid built Duration
 * @throws IllegalArgumentException if resulting duration is invalid
 */
public static Duration checkValid(Duration.Builder durationBuilder);

/**
 * Checks if the given Duration is negative.
 * 
 * @param duration Duration to check
 * @return true if duration is negative, false otherwise
 * @throws IllegalArgumentException if duration is invalid
 */
public static boolean isNegative(Duration duration);

/**
 * Checks if the given Duration is positive.
 * 
 * @param duration Duration to check
 * @return true if duration is positive (not zero or negative), false otherwise
 * @throws IllegalArgumentException if duration is invalid
 */
public static boolean isPositive(Duration duration);

/**
 * Ensures the given Duration is not negative.
 * 
 * @param duration Duration to check
 * @return The same duration if not negative
 * @throws IllegalArgumentException if duration is negative or invalid
 * @throws NullPointerException if duration is null
 */
public static Duration checkNotNegative(Duration duration);

/**
 * Ensures the given Duration is positive.
 * 
 * @param duration Duration to check
 * @return The same duration if positive
 * @throws IllegalArgumentException if duration is negative, zero, or invalid
 * @throws NullPointerException if duration is null
 */
public static Duration checkPositive(Duration duration);

/**
 * Ensures the given Duration is not negative.
 * 
 * @param duration Duration to check
 * @return The same duration if not negative
 * @throws IllegalArgumentException if duration is negative or invalid
 * @throws NullPointerException if duration is null
 */
public static Duration checkNotNegative(Duration duration);

/**
 * Ensures the given Duration is positive.
 * 
 * @param duration Duration to check
 * @return The same duration if positive
 * @throws IllegalArgumentException if duration is negative, zero, or invalid
 * @throws NullPointerException if duration is null
 */
public static Duration checkPositive(Duration duration);

/**
 * Returns a Comparator for Durations in increasing chronological order.
 * The comparator is serializable and validates inputs.
 * 
 * @return Comparator for Duration objects
 */
public static Comparator<Duration> comparator();

/**
 * Compares two durations.
 * 
 * @param x First duration
 * @param y Second duration
 * @return 0 if equal, negative if x < y, positive if x > y
 * @throws IllegalArgumentException if either duration is invalid
 */
public static int compare(Duration x, Duration y);

/**
 * Adds two durations.
 * 
 * @param d1 First duration
 * @param d2 Second duration
 * @return Duration representing d1 + d2
 * @throws IllegalArgumentException if either duration is invalid
 */
public static Duration add(Duration d1, Duration d2);

/**
 * Subtracts one duration from another.
 * 
 * @param d1 Duration to subtract from
 * @param d2 Duration to subtract
 * @return Duration representing d1 - d2
 * @throws IllegalArgumentException if either duration is invalid
 */
public static Duration subtract(Duration d1, Duration d2);

import com.google.protobuf.util.Durations;
import com.google.protobuf.Duration;
import java.text.ParseException;

// Create durations from various time units
Duration oneDay = Durations.fromDays(1);
Duration twoHours = Durations.fromHours(2);
Duration thirtyMinutes = Durations.fromMinutes(30);
Duration fiveSeconds = Durations.fromSeconds(5);
Duration tenMillis = Durations.fromMillis(10);

// Convert to string format
String durationString = Durations.toString(twoHours);
System.out.println(durationString); // "7200s"

Duration precise = Durations.fromNanos(1500000000); // 1.5 seconds
System.out.println(Durations.toString(precise)); // "1.500s"

// Parse from string
try {
    Duration parsed = Durations.parse("2.5s");
    System.out.println("Parsed: " + Durations.toString(parsed));
} catch (ParseException e) {
    System.err.println("Parse error: " + e.getMessage());
}

// Validation and sign checking
if (Durations.isValid(oneDay)) {
    System.out.println("Duration is valid");
}

Duration negative = Durations.fromSeconds(-30);
if (Durations.isNegative(negative)) {
    System.out.println("Duration is negative");
}

// Comparison
Duration shorter = Durations.fromMinutes(10);
Duration longer = Durations.fromMinutes(20);
int comparison = Durations.compare(shorter, longer); // negative value

// Arithmetic operations
Duration total = Durations.add(twoHours, thirtyMinutes);
Duration difference = Durations.subtract(oneDay, twoHours);

System.out.println("Total: " + Durations.toString(total)); // "9000s"
System.out.println("Difference: " + Durations.toString(difference)); // "79200s"

// Convert to various time units
long totalSeconds = Durations.toSeconds(total);
long totalMinutes = Durations.toMinutes(total);
long totalHours = Durations.toHours(total);
double totalSecondsDouble = Durations.toSecondsAsDouble(total);

// Use constants
System.out.println("Zero: " + Durations.toString(Durations.ZERO));
System.out.println("Min: " + Durations.toString(Durations.MIN_VALUE));
System.out.println("Max: " + Durations.toString(Durations.MAX_VALUE));

// Validation with checks
try {
    Duration validated = Durations.checkPositive(twoHours);
    System.out.println("Duration is positive: " + Durations.toString(validated));
    
    Duration nonNegative = Durations.checkNotNegative(thirtyMinutes);
    System.out.println("Duration is not negative: " + Durations.toString(nonNegative));
} catch (IllegalArgumentException e) {
    System.err.println("Duration validation failed: " + e.getMessage());
}