Displayable.java

/*
 * Copyright (c) 2020, Stein Eldar Johnsen
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package net.morimekta.strings;

import java.time.Duration;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;
import java.time.ZonedDateTime;

/**
 * Interface for making objects displayable. This is handy when handling
 * "smart" char sequences, as a string telling what the sequence represents,
 * not just it's string content, or for exceptions that want more than just
 * a plain message but e.g. a multi-line explanation of the failure.
 */
public interface Displayable {
    /**
     * Get the displayable string for this instance.
     *
     * @return A displayable string value for the object. This is meant to
     * be printed e.g. to console output and interpreted by a human.
     * The output string may contain multiple lines, but should not
     * end with a newline.
     */
    String displayString();

    /**
     * Make a displayable string out of a duration. This string is meant to be
     * easy readable. Examples:
     * <ul>
     *   <li><code>null</code>
     *   <li><code>immediately</code>
     *   <li><code>123456 nano</code>
     *   <li><code>0.123 sec</code>
     *   <li><code>0.123456789 sec</code>
     *   <li><code>2 min 3.456 sec</code>
     *   <li><code>2 min 3.456789000 sec</code>
     *   <li><code>1 day 10 hr 17 min 36 sec</code>
     *   <li><code>-1 day 10 hr 17 min 36 sec</code>
     *   <li><code>142 days 21 hr 20 min</code>
     * </ul>
     *
     * @param duration The duration to make displayable string from.
     * @return A displayable duration string. E.g. "1 day 2 hr 3 min 4.567 sec"
     * or "null".
     */
    static String displayableDuration(Duration duration) {
        return DisplayableUtil.displayableDuration(duration);
    }

    /**
     * Get displayable string for local date time.
     *
     * @param localDateTime Date-Time object to make display string of.
     * @return The formatted local date string.
     */
    static String displayableDateTime(LocalDateTime localDateTime) {
        return DisplayableUtil.displayableDateTime(localDateTime);
    }

    /**
     * Get displayable string for offset date time.
     *
     * @param offsetDateTime Date-Time object to make display string of.
     * @return The formatted local date string.
     */
    static String displayableDateTime(OffsetDateTime offsetDateTime) {
        return DisplayableUtil.displayableDateTime(offsetDateTime);
    }

    /**
     * Get displayable string for zoned date time.
     *
     * @param zonedDateTime Date-Time object to make display string of.
     * @return The formatted local date string.
     */
    static String displayableDateTime(ZonedDateTime zonedDateTime) {
        return DisplayableUtil.displayableDateTime(zonedDateTime);
    }

    /**
     * Get displayable string for instant date time.
     *
     * @param instant Instant to make display string of.
     * @return The formatted instant string.
     */
    static String displayableInstant(Instant instant) {
        return DisplayableUtil.displayableInstant(instant);
    }
}