001// Copyright (c) FIRST and other WPILib contributors.
002// Open Source Software; you can modify and/or share it under the terms of
003// the WPILib BSD license file in the root directory of this project.
004
005package org.wpilib.annotation;
006
007import java.lang.annotation.Documented;
008import java.lang.annotation.ElementType;
009import java.lang.annotation.Retention;
010import java.lang.annotation.RetentionPolicy;
011import java.lang.annotation.Target;
012
013/**
014 * Place on a method parameter of type String. Any string literals passed to that parameter will be
015 * checked at compile-time to be no longer than the maximum allowed length. Note that this cannot
016 * check dynamically generated string values - it is strongly recommended to pair this annotation
017 * with a runtime check to cover cases where dynamic values are used.
018 *
019 * <p>Errors generated by this annotation cannot be suppressed.
020 *
021 * <pre>{@code
022 * void acceptString(@MaxLength(5) String str) {
023 *   if (str.length() > 5) {
024 *     throw new IllegalArgumentException("String is too long");
025 *   }
026 *   // ...
027 * }
028 *
029 * acceptString("12345"); // OK - length is 5
030 * acceptString("123456"); // Compile-time error: length is 6
031 * acceptString("123" + "456"); // Compile-time error: length is 6
032 * acceptString(" ".repeat(16)); // Runtime error - string argument is not a literal
033 * }</pre>
034 */
035@Retention(RetentionPolicy.RUNTIME)
036@Target(ElementType.PARAMETER)
037@Documented
038public @interface MaxLength {
039  /**
040   * The maximum allowable length of string literals passed to the annotated parameter. Must be a
041   * positive integer.
042   *
043   * @return The maximum length of allowed strings.
044   */
045  int value();
046}