Package org.spongepowered.asm.mixin.injection

## Annotation Type Constant

-     @Documented
      @Retention(RUNTIME)
      public @interface Constant

  The `Constant` annotation marks a single constant value which should be selected. This is used in accord with `ModifyConstant`, however the principles of this annotation are shared with `At.args()` when using the CONSTANT injection point.

  Declaring multiple constant values within a single `Constant` annotation will not work and will cause the mixin to not apply.

  Reminder: Micromixin-transformer (and any other transformer for that matter) can see which attributes of an annotation have been set and which have not. More specifically, the javac (TM) compiler does not include the default values of annotation attributes, which allows micromixin-transformer to infer that the absence of an attribute means that it has not been set (which in turn means that the attribute is ignored).

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element | Description
    --- | --- | ---
    `java.lang.Class<?>` | `classValue` | Defines the `Class` constant values to match.
    `double` | `doubleValue` | Specify a double constant value to match
    `float` | `floatValue` | Specify a float constant value to match
    `int` | `intValue` | Specify the integer constant value to match.
    `long` | `longValue` | Specify a long constant value to match
    `boolean` | `nullValue` | If true, null values are matched.
    `java.lang.String` | `slice` | The id of the `Slice` that should be passed to the injection point to narrow down the amount of resulting matched instructions.
    `java.lang.String` | `stringValue` | Defines the string constant values to match.

- - ### Element Detail

    - #### classValue

          java.lang.Class<?> classValue

      Defines the `Class` constant values to match.

      Matches the LDC opcode.

      Does not match GETSTATIC java/lang/Integer.TYPE or similar, which means that int.class or similar cannot be matched using this approach. This means that not primitive classes can be matched as "int.class" is represented using a GETSTATIC instruction in java bytecode. That being said, this behaviour could change in future versions of the spongeian mixin implementation or future versions of micromixin as this flaw is not directly documented in the spongeian documentation of this attribute.

      Returns:
        The `Class` constant to match.
      Default:
        void.class

  - - #### doubleValue

          double doubleValue

      Specify a double constant value to match

      Matches opcodes such as LDC or DCONST_0.

      Returns:
        The double constant to match
      Default:
        0.0

  - - #### floatValue

          float floatValue

      Specify a float constant value to match

      Matches opcodes such as LDC or FCONST_0.

      Returns:
        The float constant to match
      Default:
        0.0f

  - - #### intValue

          int intValue

      Specify the integer constant value to match.

      Matches opcodes such as LDC, BIPUSH or ICONST_0.

      Due to how types work in java bytecode, this can also match booleans, bytes, shorts and chars, which do not have their own types and are always represented as integers.

      The spongeian documentation does not explicitly guarantee matching booleans and chars - but the spongeian mixin implementation does permit it anyways and the current behaviour is unlikely to change.

      Be careful, directives such as `x == 0` or `x <= 0` and other comparisons with the constant value 0 are compiled to their own dedicated opcodes, which means that this attribute cannot match 0 on it's own. HOWEVER, the spongeian mixin implementation provides tools to capture such constants anyways, but micromixin-transformer does not yet support these facilities.

      Returns:
        The integer constant to match
      Default:
        0

  - - #### longValue

          long longValue

      Specify a long constant value to match

      Matches opcodes such as LDC or LCONST_0. `longValue()` does not support matching ints, shorts, bytes, etc.

      Returns:
        The long constant to match
      Default:
        0L

  - - #### nullValue

          boolean nullValue

      If true, null values are matched.

      Matches the ACONST_NULL opcode.

      Setting the attribute to false may result in undefined behaviour. It is rather recommended to plainly remove this attribute instead of defining it to false.

      Matching null values is rather brittle due to the frequency of the null values. Aside from that the type of a null value is not well defined and must be inferred. This means that micromixin-transformer accepts any object types when paired with `ModifyConstant`. However, accepting and returning an object of type `Object` is still the recommended approach when capturing null values. That being said, other mixin implementations may behave differently and this property is not well tested.

      Returns:
        True to match null values, false otherwise.
      Default:
        false

  - - #### slice

          java.lang.String slice

      The id of the `Slice` that should be passed to the injection point to narrow down the amount of resulting matched instructions. This should be the preferred way of selecting one specific instruction from a pool of otherwise similar instructions as this would be the least brittle option - provided the slices are not used carelessly.

      Note that micromixin-transformer as well as the accompanying documentation only partly implements `Slice.id()` as well as `slice()`; significant derivations are to be expected between micromixin-transformer's behaviour (as well as the documented behaviour) and the spongeian transformer behaviour (as well as it's documentation). As such, usage of these attributes ought to be avoided in environments where usage of micromixin-transformer is expected and the spongeian documentation should be consulted before making use of this attribute.

      Returns:
        The id of the `Slice` to use, as per `Slice.id()`.
      Default:
        ""

  - - #### stringValue

          java.lang.String stringValue

      Defines the string constant values to match.

      Matches the LDC opcode.

      The string value attribute must contain the entire string to match. Do note that smaller, more frequent, strings could be matched multiple times. If in doubt, you might want to make use of `slice()` to reduce the frequency in which a specific string is captured.

      Returns:
        The string constant to match
      Default:
        ""