Guava Preconditions

Preconditions

斷言，相同的還有Objects、Java assert key word、hamcrest。

使用

• 構造方法

構造私有，與Joiner、Splitter不同，Preconditions提供了大量的靜態方法，直接類名.方法名調用節課，不需要獲取Preconditions對象。

private Preconditions() {}

• 其他方法

checkArgument方法，檢查參數，如果參數爲false，拋出IllegalArgumentException。

public static void checkArgument(boolean expression) {
    if (!expression) {
        throw new IllegalArgumentException();
    }
}

checkState方法，檢查狀態，狀態爲false，拋出IllegalStateException。

public static void checkState(boolean expression, @Nullable Object errorMessage) {
    if (!expression) {
        throw new IllegalStateException(String.valueOf(errorMessage));
    }
}

checkNotNull方法，不能爲null，爲null拋出NullPointerException。

// 返回值可以忽略
@CanIgnoreReturnValue
public static <T> T checkNotNull(T reference) {
    if (reference == null) {
        throw new NullPointerException();
    }
    return reference;
}

checkElementIndex方法，檢查元素索引值是否有效，越界拋出IndexOutOfBoundsException。

@CanIgnoreReturnValue
public static int checkElementIndex(int index, int size) {
    return checkElementIndex(index, size, "index");
}
@CanIgnoreReturnValue
public static int checkElementIndex(int index, int size, @Nullable String desc) {
    // 越界
    if (index < 0 || index >= size) {
        throw new IndexOutOfBoundsException(badElementIndex(index, size, desc));
    }
    return index;
}


private static String badElementIndex(int index, int size, String desc) {
    if (index < 0) {// index爲負數，格式化index越界報錯信息
        return format("%s (%s) must not be negative", desc, index);
    } else if (size < 0) {// size爲負數，拋出size參數異常
        throw new IllegalArgumentException("negative size: " + size);
    } else { // index >= size，越界報錯信息
        return format("%s (%s) must be less than size (%s)", desc, index, size);
    }
}

checkPositionIndex方法，檢查下標索引值是否有效。

@CanIgnoreReturnValue
public static int checkPositionIndex(int index, int size) {
    return checkPositionIndex(index, size, "index");
}
@CanIgnoreReturnValue
public static int checkPositionIndex(int index, int size, @Nullable String desc) {
    // Carefully optimized for execution by hotspot (explanatory comment above)
    if (index < 0 || index > size) {
        throw new IndexOutOfBoundsException(badPositionIndex(index, size, desc));
    }
    return index;
}


private static String badPositionIndex(int index, int size, String desc) {
    if (index < 0) {
        return format("%s (%s) must not be negative", desc, index);
    } else if (size < 0) {
        throw new IllegalArgumentException("negative size: " + size);
    } else { // index > size
        return format("%s (%s) must not be greater than size (%s)", desc, index, size);
    }
}

format方法，將可變參數列表中的參數替換到template的佔位符%s中，如同System.out.println方法。

static String format(String template, @Nullable Object... args) {
    template = String.valueOf(template); // null -> "null"

    // 將變長參數替換到%s佔位符中
    StringBuilder builder = new StringBuilder(template.length() + 16 * args.length);
    int templateStart = 0;
    int i = 0;
    while (i < args.length) {
    	// 獲取佔位符"%s"的下標賦予placeholderStart
        int placeholderStart = template.indexOf("%s", templateStart);
      	// 無佔位符退出
      	if (placeholderStart == -1) {
            break;
        }
        // 將template追加到builder的[template, placeholderStart)序列中
      	builder.append(template, templateStart, placeholderStart);
      	// 追加參數
      	builder.append(args[i++]);
        templateStart = placeholderStart + 2;
    }
    builder.append(template, templateStart, template.length());

    // if we run out of placeholders, append the extra args in square braces
    if (i < args.length) {
        builder.append(" [");
        builder.append(args[i++]);
        while (i < args.length) {
        	builder.append(", ");
            builder.append(args[i++]);
        }
        builder.append(']');
    }

    return builder.toString();
}