Replacers

Since 1.0.0

Replacers do what you might expect, they replace some text with some other text on a string, they exist to be used as an easy way to replace text, normally on multiple strings without having to specify multiple times what replacements you want. Creating a Replacer is easy, but there are two pretty important rules, firstly, Replacers can only have a number of replacements that is divisible by two, let's take a look at how to create a Replacer and you will quickly understand why that's a requirement.

String str = "Value is: %val%";
Replacer valid = new Replacer("%val%", "Test");
Replacer invalid = new Replacer("%val%", "Test", "%ShouldNotBeHere%");

The first "valid" Replacer will work because "%val%" has a replacement, "Test". However, the second Replacer, "invalid", will throw an exception because "%ShouldNotBeHere%" doesn't have a replacement, pretty obvious right? Now let's see how to actually use a Replacer.

Replacer replacer = new Replacer("%val%", "Test");
String result = replacer.replaceAt("Value is: %val%");
// result will be "Value is: Test" 

Secondly, you can't really add two replacements for the same string as they will override each other in the order they were added, let's take a look at this.

Replacer replacer = new Replacer("%val%", "Test", "%val%", "Oops");
String result = replacer.replaceAt("Value is: %val%");
// result will be "Value is: Test" as %val% has already been replaced.

Also, there is no need to use '%' for the text to replace, but it is the common way to identify placeholders, so yeah, try to keep it that way, at least for placeholders that the end user may use. Anyways, Replacers can also be used on string lists and as many times as you want.

String str = "Value is: %val%";
List<String> list = Arrays.asList("%val%", "Another %val%");

Replacer replacer = new Replacer("%val%", "Test");
replacer.replaceAt(str); // "Value is: Test"
replacer.replaceAt(list); // ["Test", "Another Test"]

Numeric support

Numeric support is a feature that replaces different text depending on a numeric value, let's see a real example to understand how it works.

String str = "You have %points% <%points%:point:points>"
// Format is <number:singular:plural>

new Replacer("%points%", 1).replaceAt(str); // "You have 1 point"
new Replacer("%points%", -1).replaceAt(str); // "You have -1 point"
new Replacer("%points%", 42).replaceAt(str); // "You have 42 points"

If %points% gets replaced with either 1 or -1, the final string will be "You have 1 point", with any other number, for example 42, the final string will be "You have 42 points"

Player objects

Player objects are treated on a different way by replacers in order to make your code just a bit shorter, if you add a replacement with a player object, MCUtils assumes you want the player name.

Player target = Bukkit.getPlayer("xDec0de_");
Replacer replacer = new Replacer("%player%", target); // No need to use #getName!
target.sendMessage(replacer.replaceAt("Hello, %target%"); // "Hello, xDec0de_"

Modifying replacements

Of course, you can add new replacements to an existing Replacer

Replacer replacer = new Replacer("%placeholder%", "value");

// Just using strings
replacer.add("%anotherPlaceholder%", "anotherValue");

// Using another Replacer
Replacer anotherReplacer = new Replacer("%anotherPlaceholder%", "anotherValue");
replacer.add(anotherReplacer);

Replacement

The replacement interface just adds one method, the asReplacement method. Every object implementing this interface will be recognized by a Replacer, which will use its asReplacement method instead of toString in order to display it. Here is an example with a useless player class.

import me.xdec0de.mcutils.java.strings.replacers.Replacement;

public class TestPlayer implements Replacement {

    private final String name;

    public TestPlayer(String name) {
        this.name = name;    
    }

    public String asReplacement() {
        return name;
    }
}

This class could be used like this on a replacer

public void test() {
    Replacer replacer = new Replacer("%player%, new TestPlayer("xDec0de_"));
    String test = replacer.replaceAt("Hello %player%!"); // Hello xDec0de_!
}