TextUnit.kt

/*
 * Copyright 2019 The Android Open Source Project
 *
 * Licensed 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.
 */
@file:Suppress("NOTHING_TO_INLINE")

package androidx.compose.ui.unit

import androidx.compose.runtime.Immutable
import androidx.compose.runtime.Stable
import androidx.compose.ui.util.lerp

/**
 * We encode the unit information and float value into the single 64-bit long integer.
 * The higher 32bit represents the metadata of this value and lower 32bit represents the bit
 * representation of the float value. Currently lower 8bits in the metadata bits are used for
 * unit information.
 *
 * Bits
 * |-------|-------|-------|-------|-------|-------|-------|-------|
 *                                  FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF: Float Value
 *                          UUUUUUUU                                : Unit Information
 *  XXXXXXXXXXXXXXXXXXXXXXXX                                        : Unused bits
 */
private const val UNIT_MASK = 0xFFL shl 32 // 0xFF_0000_0000
private const val UNIT_TYPE_UNSPECIFIED = 0x00L shl 32 // 0x00_0000_0000
private const val UNIT_TYPE_SP = 0x01L shl 32 // 0x01_0000_0000
private const val UNIT_TYPE_EM = 0x02L shl 32 // 0x2_0000_0000

/**
 * An enum class defining for type of [TextUnit].
 */
enum class TextUnitType(val value: Int) {
    @Deprecated(
        "Renamed to TextUnitType.Unspecified",
        replaceWith = ReplaceWith("TextUnitType.Unspecified", "androidx.compose.ui.unit")
    )
    Inherit(0),
    Unspecified(0),
    Sp(1),
    Em(2)
}

/**
 * The unit used for text related dimension value.
 *
 * This unit can hold either scaled pixels (SP), relative font size (em) and special unit for
 * indicating inheriting from other style.
 *
 * Note that do not store this value in your persistent storage or send to another process since
 * the internal representation may be changed in future.
 */
@Suppress("EXPERIMENTAL_FEATURE_WARNING")
@Immutable
inline class TextUnit(val packedValue: Long) {
    /**
     * Add two [TextUnit]s together.
     *
     * This operation works only if all the operands are the same unit type and not they are not
     * equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun plus(other: TextUnit): TextUnit {
        checkArithmetic(this, other)
        return pack(rawType, value + other.value)
    }

    /**
     * Subtract a [TextUnit] from another one.

     * This operation works only if all the operands are the same unit type and not they are not
     * equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun minus(other: TextUnit): TextUnit {
        checkArithmetic(this, other)
        return pack(rawType, value - other.value)
    }

    /**
     * This is the same as multiplying the [TextUnit] by -1.0.
     *
     * This operation works only if the operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun unaryMinus(): TextUnit {
        checkArithmetic(this)
        return pack(rawType, -value)
    }

    /**
     * Divide a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun div(other: Float): TextUnit {
        checkArithmetic(this)
        return pack(rawType, value / other)
    }

    /**
     * Divide a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun div(other: Double): TextUnit {
        checkArithmetic(this)
        return pack(rawType, (value / other).toFloat())
    }

    /**
     * Divide a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun div(other: Int): TextUnit {
        checkArithmetic(this)
        return pack(rawType, value / other)
    }

    /**
     * Divide by another [TextUnit] to get a scalar.
     *
     * This operation works only if all the operands are the same unit type and they are not
     * equal to [TextUnit.Unspecified].
     */
    inline operator fun div(other: TextUnit): Float {
        checkArithmetic(this, other)
        return value / other.value
    }

    /**
     * Multiply a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun times(other: Float): TextUnit {
        checkArithmetic(this)
        return pack(rawType, value * other)
    }

    /**
     * Multiply a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun times(other: Double): TextUnit {
        checkArithmetic(this)
        return pack(rawType, (value * other).toFloat())
    }

    /**
     * Multiply a [TextUnit] by a scalar.
     *
     * This operation works only if the left operand is not equal to [TextUnit.Unspecified].
     * The result of this operation is the same unit type of the given one.
     */
    inline operator fun times(other: Int): TextUnit {
        checkArithmetic(this)
        return pack(rawType, value * other)
    }

    /**
     * Support comparing Dimensions with comparison operators.
     */
    inline operator fun compareTo(other: TextUnit): Int {
        checkArithmetic(this, other)
        return value.compareTo(other.value)
    }

    @Suppress("DEPRECATION")
    override fun toString(): String {
        return when (type) {
            TextUnitType.Unspecified -> "Unspecified"
            TextUnitType.Inherit -> "Inherit"
            TextUnitType.Sp -> "$value.sp"
            TextUnitType.Em -> "$value.em"
        }
    }

    companion object {
        internal val TextUnitTypes =
            arrayOf(TextUnitType.Unspecified, TextUnitType.Sp, TextUnitType.Em)

        /**
         * Creates a SP unit [TextUnit].
         */
        fun Sp(value: Int) = pack(UNIT_TYPE_SP, value.toFloat())

        /**
         * Creates a SP unit [TextUnit].
         */
        fun Sp(value: Float) = pack(UNIT_TYPE_SP, value)

        /**
         * Creates a SP unit [TextUnit].
         */
        fun Sp(value: Double) = pack(UNIT_TYPE_SP, value.toFloat())

        /**
         * Creates an EM unit [TextUnit].
         */
        fun Em(value: Int) = pack(UNIT_TYPE_EM, value.toFloat())

        /**
         * Creates an EM unit [TextUnit].
         */
        fun Em(value: Float) = pack(UNIT_TYPE_EM, value)

        /**
         * Creates an EM unit [TextUnit].
         */
        fun Em(value: Double) = pack(UNIT_TYPE_EM, value.toFloat())

        /**
         * A special [TextUnit] instance for representing inheriting from parent value.
         */
        @Stable
        val Unspecified = pack(UNIT_TYPE_UNSPECIFIED, Float.NaN)

        /**
         * A special [TextUnit] instance for representing inheriting from parent value.
         */
        @Stable
        @Deprecated(
            "Renamed to TextUnit.Unspecified",
            replaceWith = ReplaceWith("TextUnit.Unspecified", "androidx.compose.ui.unit")
        )
        val Inherit = Unspecified
    }

    /**
     * A helper function for getting underlying type information in raw bits.
     *
     * Use [TextUnit.type] in public places.
     */
    @PublishedApi
    internal val rawType: Long get() = packedValue and UNIT_MASK

    /**
     * A type information of this TextUnit.
     *
     * @throws RuntimeException if unknown unknown unit type is appeared.
     */
    val type: TextUnitType get() = TextUnitTypes[(rawType ushr 32).toInt()]

    /**
     * True if this is [TextUnit.Unspecified], otherwise false.
     */
    @Deprecated(
        "Renamed to TextUnit.isUnspecified",
        replaceWith = ReplaceWith("isUnspecified", "androidx.compose.ui.unit")
    )
    val isInherit get() = isUnspecified

    /**
     * True if this is [TextUnit.Unspecified], otherwise false.
     */
    val isUnspecified get() = rawType == UNIT_TYPE_UNSPECIFIED

    /**
     * True if this is a SP unit type.
     */
    val isSp get() = rawType == UNIT_TYPE_SP

    /**
     * True if this is a EM unit type.
     */
    val isEm get() = rawType == UNIT_TYPE_EM

    /**
     * Returns the value
     */
    val value get() = Float.fromBits((packedValue and 0xFFFF_FFFFL).toInt())
}

/**
 * Creates a SP unit [TextUnit]
 */
@Stable
val Float.sp: TextUnit get() = pack(UNIT_TYPE_SP, this)

/**
 * Creates an EM unit [TextUnit]
 */
@Stable
val Float.em: TextUnit get() = pack(UNIT_TYPE_EM, this)

/**
 * Creates a SP unit [TextUnit]
 */
@Stable
val Double.sp: TextUnit get() = pack(UNIT_TYPE_SP, this.toFloat())

/**
 * Creates an EM unit [TextUnit]
 */
@Stable
val Double.em: TextUnit get() = pack(UNIT_TYPE_EM, this.toFloat())

/**
 * Creates a SP unit [TextUnit]
 */
@Stable
val Int.sp: TextUnit get() = pack(UNIT_TYPE_SP, this.toFloat())

/**
 * Creates an EM unit [TextUnit]
 */
@Stable
val Int.em: TextUnit get() = pack(UNIT_TYPE_EM, this.toFloat())

/**
 * Multiply a [TextUnit] by a scalar.
 *
 * This operation works only if the right operand is not equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 */
@Stable
inline operator fun Float.times(other: TextUnit): TextUnit {
    checkArithmetic(other)
    return pack(other.rawType, this * other.value)
}

/**
 * Multiply a [TextUnit] by a scalar.
 *
 * This operation works only if the right operand is not equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 */
@Stable
inline operator fun Double.times(other: TextUnit): TextUnit {
    checkArithmetic(other)
    return pack(other.rawType, this.toFloat() * other.value)
}

/**
 * Multiply a [TextUnit] by a scalar.
 *
 * This operation works only if the right operand is not equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 */
@Stable
inline operator fun Int.times(other: TextUnit): TextUnit {
    checkArithmetic(other)
    return pack(other.rawType, this * other.value)
}

/**
 * Returns the smaller value from the given values.
 *
 * This operation works only if all the operands are the same unit type and they are not
 * equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 */
@Stable
inline fun min(a: TextUnit, b: TextUnit): TextUnit {
    checkArithmetic(a, b)
    return if (a.value < b.value) a else b
}

/**
 * Returns the smaller value from the given values.
 *
 * This operation works only if all the operands are the same unit type and they are not
 * equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 */
@Stable
inline fun max(a: TextUnit, b: TextUnit): TextUnit {
    checkArithmetic(a, b)
    return if (a.value < b.value) b else a
}

/**
 * Ensures that the value of [TextUnit] lies in the specified range [minimumValue]..[maximumValue].
 *
 *
 * This operation works only if all the operands are the same unit type and they are not
 * equal to [TextUnit.Unspecified].
 * The result of this operation is the same unit type of the given one.
 *
 * @return this value if it's in the range, or [minimumValue] if this value is less than
 * [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
 */
@Stable
inline fun TextUnit.coerceIn(minimumValue: TextUnit, maximumValue: TextUnit): TextUnit {
    checkArithmetic(this, minimumValue, maximumValue)
    return pack(rawType, value.coerceIn(minimumValue.value, maximumValue.value))
}

/**
 * Ensures that the value of [TextUnit] is not less than the specified [minimumValue].
 *
 * @return this value if it's greater than or equal to the [minimumValue] or the
 * [minimumValue] otherwise.
 */
@Stable
inline fun TextUnit.coerceAtLeast(minimumValue: TextUnit): TextUnit {
    checkArithmetic(this, minimumValue)
    return pack(rawType, value.coerceAtLeast(minimumValue.value))
}

/**
 * Ensures that the value of [TextUnit] is not greater than the specified [maximumValue].
 *
 * @return this value if it's less than or equal to the [maximumValue] or the
 * [maximumValue] otherwise.
 */
@Stable
inline fun TextUnit.coerceAtMost(maximumValue: TextUnit): TextUnit {
    checkArithmetic(this, maximumValue)
    return pack(rawType, value.coerceAtMost(maximumValue.value))
}

@PublishedApi
internal inline fun pack(unitType: Long, v: Float): TextUnit =
    TextUnit(unitType or (v.toBits().toLong() and 0xFFFF_FFFFL))

@PublishedApi
internal fun checkArithmetic(a: TextUnit) {
    require(!a.isUnspecified) {
        "Cannot perform operation for Unspecified type."
    }
}

@PublishedApi
internal fun checkArithmetic(a: TextUnit, b: TextUnit) {
    require(!a.isUnspecified && !b.isUnspecified) {
        "Cannot perform operation for Unspecified type."
    }
    require(a.type == b.type) {
        "Cannot perform operation for ${a.type} and ${b.type}"
    }
}

@PublishedApi
internal fun checkArithmetic(a: TextUnit, b: TextUnit, c: TextUnit) {
    require(!a.isUnspecified && !b.isUnspecified && !c.isUnspecified) {
        "Cannot perform operation for Unspecified type."
    }
    require(a.type == b.type && b.type == c.type) {
        "Cannot perform operation for ${a.type} and ${b.type}"
    }
}

@Stable
fun lerp(a: TextUnit, b: TextUnit, t: Float): TextUnit {
    checkArithmetic(a, b)
    return pack(a.rawType, lerp(a.value, b.value, t))
}