sirius.kernel.commons.Monoflop Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sirius-kernel Show documentation
Provides common core classes and the microkernel powering all Sirius applications
There is a newer version: 12.9.1
/*
 * Made with all the love in the world
 * by scireum in Remshalden, Germany
 *
 * Copyright by scireum GmbH
 * http://www.scireum.de - [email protected]
 */

package sirius.kernel.commons;

/**
 * Represents a boolean state variable, which can be toggled once from false to true.
 * 
 * All successive calls will not change the internal state, and return constantly true (or respectively).
 * 

 * This is particularly useful in loops where the first iteration must be handled differently. Therefore two more
 * functions are provided: {@link #firstCall()} and {@link #successiveCall()} which can be used like shown here:
 * 
 * {@code
 * Monoflop mono = Monoflop.create();
 * StringBuilder sb = new StringBuilder();
 * for(String value : somelist) {
 *     if (mono.successiveCall()) {
 *         sb.append(", ");
 *     }
 *     sb.append(value);
 * }
 * System.out.println(sb.toString());
 * }
 * 
 */
public class Monoflop {

    private boolean toggled = false;

    /*
     * Use the static constructor create()
     */
    private Monoflop() {
    }

    /**
     * Creates a new monoflop.
     *
     * @return a new monoflop which was not toggled yet.
     */
    public static Monoflop create() {
        return new Monoflop();
    }

    /**
     * Toggles the monoflop and returns its state before it was toggled.
     * 
     * If the monoflop is in its initial state, this will return false (and toggle the monoflop).
     * Therefore all successive class will return true.
     *
     * @return false if the monoflop was not toggled yet, true for all successive calls
     */
    public boolean toggle() {
        if (toggled) {
            return true;
        }
        toggled = true;
        return false;
    }

    /**
     * Toggles the monoflop and returns its state before it was toggled.
     * 

     * If the monoflop is in its initial state, this will return true (and toggle the monoflop).
     * Therefore all successive class will return false.
     *
     * @return true if the monoflop was not toggled yet, false for all successive calls
     */
    public boolean inverseToggle() {
        return !toggle();
    }

    /**
     * Reads and then toggles the monoflop.
     * 

     * If the monoflop is in its initial state, this will return true (and toggle the monoflop).
     * Therefore all successive class will return false.
     * 

     * This is just an alias for {@link #inverseToggle()}.
     *
     * @return true if the monoflop was not toggled yet, false for all successive calls
     */
    public boolean firstCall() {
        return inverseToggle();
    }

    /**
     * Reads and then toggles the monoflop.
     * 

     * If the monoflop is in its initial state, this will return false (and toggle the monoflop).
     * Therefore all successive class will return true.
     * 
     * This is just an alias for {@link #toggle()}.
     *
     * @return false if the monoflop was not toggled yet, true for all successive calls
     */
    public boolean successiveCall() {
        return toggle();
    }

    /**
     * Reads the internal state without toggling it.
     *
     * @return false if the monoflop is in its initial state, true otherwise
     */
    public boolean isToggled() {
        return toggled;
    }

    @Override
    public String toString() {
        return "Monoflop (Toggled: " + toggled + ")";
    }
}