package org.checkerframework.checker.signedness.qual;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.checkerframework.framework.qual.LiteralKind;
import org.checkerframework.framework.qual.QualifierForLiterals;
import org.checkerframework.framework.qual.SubtypeOf;

/**
 * Client code may interpret the value either as {@link Signed} or as {@link Unsigned}. This
 * primarily applies to values whose most significant bit is not set {@link SignedPositive}, and
 * thus the value has the same interpretation as signed or unsigned.
 *
 * <p>As a special case, the Signedness Checker also applies this annotation to manifest literals.
 * This permits a value like {@code -1} or {@code 255} or {@code 0xFF} to be used in both signed and
 * unsigned contexts. The Signedness Checker has no way of knowing how a programmer intended a
 * literal to be used, so it does not issue warnings for any uses of a literal. (An alternate design
 * would require the programmer to explicitly annotate every manifest literal whose most significant
 * bit is set. That might detect more errors, at the cost of much greater programmer annotation
 * effort.)
 *
 * <p>The programmer should not write this annotation. Instead, the programmer should write {@link
 * Signed} or {@link Unsigned} to indicate how the programmer intends the value to be interpreted.
 * For a value whose most significant bit is not set and different clients may treat it differently
 * (say, the return value of certain library routines, or certain constant fields), the programmer
 * should write {@code @}{@link SignedPositive} instead of {@code @SignednessGlb}.
 *
 * <p>The "Glb" in the name stands for "greatest lower bound", because this type is the greatest
 * lower bound of the types {@link Signed} and {@link Unsigned}; that is, this type is a subtype of
 * both of those types.
 *
 * @see SignedPositive
 * @checker_framework.manual #signedness-checker Signedness Checker
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})
@SubtypeOf({Unsigned.class, Signed.class})
@QualifierForLiterals({LiteralKind.INT, LiteralKind.LONG, LiteralKind.CHAR})
public @interface SignednessGlb {}