Package space.arim.dazzleconf.backend

Class KeyPath

java.lang.Object
space.arim.dazzleconf.backend.KeyPath
All Implemented Interfaces:
Printable
Direct Known Subclasses:
KeyPath.Immut, KeyPath.Mut
public abstract class KeyPath extends Object implements Printable
A key path consists of an ordered sequence of strings.

Example: "my.brave.world" is a key path consisting of three strings. The front of the key path would be "my" and the back would be "enabled". A KeyPath stores the ordered sequence and can be expanded at the front or the back, but it cannot be shrunk (this class does not support shrinking).

Printing and display

This class implements Printable for display purposes. The dot-separated form will be the displayed product: 

     
     KeyPath myBraveWorld = new KeyPath("my", "brave", "world"); // var-args constructor
     assert "my.brave.world".equals(myBraveWorld.printString());

Mutability

Mutability of this class is not defined. Please use KeyPath.Mut or KeyPath.Immut if you need mutable or immutable versions, or see the package javadoc for more information on the mutability model we use.

Key mapping

A key path stores strings without distinction and does not handle key mapping. For convenience, users can apply a key mapper to edit existing path elements, via KeyPath.Mut.applyKeyMapper(KeyMapper).

  • Method Details

    • empty

      public static @NonNull KeyPath empty()
      Returns an empty key path.

      This method is provided for convenience and readability. Mutability of the returned value is not specified.

      Returns:
      an empty key path

    • isEmpty

      @Pure public boolean isEmpty()
      Whether this key path is empty
      Returns:
      true if empty

    • size

      @Pure public int size()
      Gets the number of key parts in the sequence
      Returns:
      the number of parts in this key path

    • getLeading

      public @Nullable CharSequence getLeading(@NonNull KeyPath.SequenceBoundary where)
      Regarding this key path as a sequence of strings, this function returns either the very first value (if using SequenceBoundary.FRONT) or the very last value (if SequenceBoundary.BACK).
      Parameters:
      where - the front or the back
      Returns:
      the leading value at that end, or null if this key path is empty

    • iterateFrom

      public void iterateFrom(@NonNull KeyPath.SequenceBoundary from, Consumer<? super @NonNull CharSequence> action)
      Runs an action for each key part in the sequence.

      Lets the caller pick from which end of the sequence to start from, and move in the opposite direction.

      Parameters:
      from - the edge to start from; this function will iterate from it toward the other end
      action - the action on each part

    • forEach

      @SideEffectFree public void forEach(@NonNull Consumer<? super @NonNull CharSequence> action)
      Runs an action for each key part in the sequence, starting from the front
      Parameters:
      action - the action on each part

    • intoMut

      @SideEffectFree public abstract @NonNull KeyPath.Mut intoMut()
      Gets this key path as a mutable one.

      If not mutable, the data is copied to a new key path which is returned. This copying may be performed lazily, such as by deferring to the first mutative operation on the returned object.

      Returns:
      this key path if mutable, or a mutable copy if needed

    • intoImmut

      @SideEffectFree public abstract @NonNull KeyPath.Immut intoImmut()
      Gets this key path as an immutable one.

      The data contained within this KeyPath is moved to an immutable instance. The old instance may still be used, but the implementation of this method may be optimized for the case that it is not.

      If this instance is already DataTree.Immut, then it may be returned without changes.

      Returns:
      an immutable key path

    • intoParts

      @SideEffectFree public @NonNull CharSequence @NonNull [] intoParts()
      Turns into key path parts.

      The returned array may be modified freely and will not mutate this key path.

      Returns:
      the key path's parts

    • intoPartsList

      @SideEffectFree public @NonNull List<@NonNull CharSequence> intoPartsList()
      Same as intoParts() but returns a list.

      The returned list may be modified freely and will not mutate this key path. However, there is no guarantee that the list has a non-fixed size, e.g. it might be Arrays.asList

      Returns:
      the key path parts

    • equals

      public final boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public @NonNull String toString()
      Description copied from interface: Printable
      Gets a string representation.

      Implementations are strongly encouraged (but not required) to return the same value as fo Printable.printString()

      Specified by:
      toString in interface Printable
      Overrides:
      toString in class Object
      Returns:
      a string representation of this object

    • printString

      public @NonNull String printString()
      Description copied from interface: Printable
      Gets the printed content as a string
      Specified by:
      printString in interface Printable
      Returns:
      printed string

    • printTo

      public void printTo(@NonNull Appendable output) throws IOException
      Description copied from interface: Printable
      Prints to the given appendable
      Specified by:
      printTo in interface Printable
      Parameters:
      output - where to place the message
      Throws:
      IOException - if the output threw this error, it is propagated

    • printTo

      public void printTo(@NonNull StringBuilder output)
      Description copied from interface: Printable
      Prints to the given builder
      Specified by:
      printTo in interface Printable
      Parameters:
      output - where to place the message