Package net.automatalib.word

Class WordBuilder<I>

  • Type Parameters:
    I - symbol class.
    All Implemented Interfaces:
    Iterable<I>, Collection<I>, List<I>
    public final class WordBuilder<I>
extends AbstractList<I>
    A class for dynamically building Words.

    As Words are - like strings - immutable objects, constructing them by subsequent invocations of Word.concat(Word...) etc. is highly inefficient. This class provides an efficient means of construction by operating on an internal storage during construction, only creating a Word (and thus requiring to ensure immutability) when the method toWord() (or toWord(int, int)) is invoked.

    Note that due to the specifics of the underlying word implementation, even after an invocation of toWord() the storage does not have to be duplicated unless it either is required due to capacity adjustment or a non-appending change (such as setSymbol(int, Object) or truncate(int)) is made.

    Nearly all modification methods of this class return a this-reference, allowing constructs such as builder.append(foo).append(bar).append(baz).

    • Constructor Detail

      • WordBuilder

        public WordBuilder()
        Constructor. Initializes the builder with a default capacity.

      • WordBuilder

        public WordBuilder​(int initialCapacity)
        Constructor. Initializes the builder with the specified initial capacity.
        Parameters:
        initialCapacity - the initial capacity of the internal storage.

      • WordBuilder

        public WordBuilder​(I initSym,
                   int count)
        Constructor. Initializes the builder with a sequence of count times the specified symbol. Note that this constructor runs in constant time if initSym is null.
        Parameters:
        initSym - the initial symbol
        count - the initial symbol count

      • WordBuilder

        public WordBuilder​(int capacity,
                   I initSym,
                   int count)
        Constructor. Initializes the builder with a sequence of count times the specified symbol, while allocating the specified initial capacity.
        Parameters:
        capacity - the initial capacity of the internal storage.
        initSym - the initial symbol
        count - the initial symbol count

      • WordBuilder

        public WordBuilder​(Word<I> init)
        Constructor. Initializes the builder with a given word.
        Parameters:
        init - the word to initialize the builder with.

      • WordBuilder

        public WordBuilder​(int capacity,
                   Word<I> init)
        Constructor. Initializes the builder with a given word, while allocating the specified initial capacity.
        Parameters:
        capacity - the initial capacity to use.
        init - the initial word

    • Method Detail

      • append

        public WordBuilder<I> append​(I symbol)
        Appends a symbol to the contents of the internal storage.
        Parameters:
        symbol - the symbol to append
        Returns:
        this

      • append

        public WordBuilder<I> append​(Word<? extends I> word)
        Appends a word to the contents of the internal storage.
        Parameters:
        word - the word to append.
        Returns:
        this

      • append

        @SafeVarargs
public final WordBuilder<I> append​(Word<? extends I>... words)
        Appends several words to the contents of the internal storage.
        Parameters:
        words - the words to append
        Returns:
        this

      • append

        @SafeVarargs
public final WordBuilder<I> append​(I... symbols)
        Appends several symbols to the contents of the internal storage.
        Parameters:
        symbols - the symbols to append
        Returns:
        this

      • ensureAdditionalCapacity

        public void ensureAdditionalCapacity​(int add)
        Ensures that the internal storage has additionally the given capacity.
        Parameters:
        add - the additional capacity to ensure

      • ensureCapacity

        public void ensureCapacity​(int cap)
        Ensures that the internal storage has in total the given capacity.
        Parameters:
        cap - the minimum capacity to ensure

      • repeatAppend

        public WordBuilder<I> repeatAppend​(int num,
                                   Word<I> word)
        Appends num copies of the given word to the contents of the initial storage.
        Parameters:
        num - the number of copies
        word - the word
        Returns:
        this

      • repeatAppend

        public WordBuilder<I> repeatAppend​(int num,
                                   I symbol)
        Appends num copies of a symbol to the contents of the internal storage.
        Parameters:
        num - the number of copies
        symbol - the symbol
        Returns:
        this

      • truncate

        public WordBuilder<I> truncate​(int truncLen)
        Truncates the contents of the initial storage to the given length.
        Parameters:
        truncLen - the length to truncate to
        Returns:
        this

      • toWord

        public Word<I> toWord​(int fromIndex,
                      int toIndex)
        Creates a word from the given range of the contents of the internal storage. Note that the storage management mechanisms of this class guarantee that the returned word will not change regardless of what further operations are invoked on this WordBuilder.
        Parameters:
        fromIndex - the starting index, inclusive
        toIndex - the end index, exclusive
        Returns:
        the word for the specified subrange

      • toWord

        public Word<I> toWord()
        Creates a word from the contents of the internal storage. Note that the storage management mechanisms of this class guarantee that the returned word will not change regardless of what further operations are performed on this WordBuilder.
        Returns:
        the internal contents as a word

      • getSymbol

        public I getSymbol​(int index)
        Retrieves the symbol at the given index.
        Parameters:
        index - the index to retrieve
        Returns:
        the symbol at the given index

      • set

        public I set​(int index,
             I element)
        Specified by:
        set in interface List<I>
        Overrides:
        set in class AbstractList<I>

      • setSymbol

        public WordBuilder<I> setSymbol​(int index,
                                I symbol)
        Sets the symbol at the given index. Note that this index must exist.
        Parameters:
        index - the index to manipulate
        symbol - the symbol to set
        Returns:
        this

      • reverse

        public WordBuilder<I> reverse()
        Reverses the contents of the internal buffer.
        Returns:
        this