LazyStringList
Date: 2017-07-08

com.google.protobuf

## Interface LazyStringList

- All Superinterfaces:
    java.util.Collection<java.lang.String>, java.lang.Iterable<java.lang.String>, java.util.List<java.lang.String>, ProtocolStringList
  All Known Implementing Classes:
    LazyStringArrayList, UnmodifiableLazyStringList

      public interface LazyStringList
      extends ProtocolStringList

  An interface extending `List<String>` that also provides access to the items of the list as UTF8-encoded ByteString or byte[] objects. This is used by the protocol buffer implementation to support lazily converting bytes parsed over the wire to String objects until needed and also increases the efficiency of serialization if the String was never requested as the ByteString or byte[] is already cached. The ByteString methods are used in immutable API only and byte[] methods used in mutable API only for they use different representations for string/bytes fields.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(byte[] element)` Appends the specified element to the end of this list (optional operation).
    `void` | `add(ByteString element)` Appends the specified element to the end of this list (optional operation).
    `boolean` | `addAllByteArray(java.util.Collection<byte[]> c)` Appends all elements in the specified byte[] collection to the end of this list.
    `boolean` | `addAllByteString(java.util.Collection<? extends ByteString> c)` Appends all elements in the specified ByteString collection to the end of this list.
    `java.util.List<byte[]>` | `asByteArrayList()` Returns a mutable view of this list.
    `byte[]` | `getByteArray(int index)` Returns the element at the specified position in this list as byte[].
    `ByteString` | `getByteString(int index)` Returns the element at the specified position in this list as a ByteString.
    `java.lang.Object` | `getRaw(int index)` Returns the element at the specified position in this list as an Object that will either be a String or a ByteString.
    `java.util.List<?>` | `getUnderlyingElements()` Returns an unmodifiable List of the underlying elements, each of which is either a `String` or its equivalent UTF-8 encoded `ByteString` or byte[].
    `LazyStringList` | `getUnmodifiableView()` Returns an unmodifiable view of the list.
    `void` | `mergeFrom(LazyStringList other)` Merges all elements from another LazyStringList into this one.
    `void` | `set(int index, byte[] element)` Replaces the element at the specified position in this list with the specified element (optional operation).
    `void` | `set(int index, ByteString element)` Replaces the element at the specified position in this list with the specified element (optional operation).

    - ### Methods inherited from interface com.google.protobuf.ProtocolStringList

      `asByteStringList`

    - ### Methods inherited from interface java.util.List

      `add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, retainAll, set, size, subList, toArray, toArray`

- - ### Method Detail

    - #### getByteString

          ByteString getByteString(int index)

      Returns the element at the specified position in this list as a ByteString.
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### getRaw

          java.lang.Object getRaw(int index)

      Returns the element at the specified position in this list as an Object that will either be a String or a ByteString.
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### getByteArray

          byte[] getByteArray(int index)

      Returns the element at the specified position in this list as byte[].
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### add

          void add(ByteString element)

      Appends the specified element to the end of this list (optional operation).
      Parameters:
        `element` - element to be appended to this list
      Throws:
        `java.lang.UnsupportedOperationException` - if the `add` operation is not supported by this list

    - #### add

          void add(byte[] element)

      Appends the specified element to the end of this list (optional operation).
      Parameters:
        `element` - element to be appended to this list
      Throws:
        `java.lang.UnsupportedOperationException` - if the `add` operation is not supported by this list

    - #### set

          void set(int index,
                 ByteString element)

      Replaces the element at the specified position in this list with the specified element (optional operation).
      Parameters:
        `index` - index of the element to replace
        `element` - the element to be stored at the specified position
      Throws:
        `java.lang.UnsupportedOperationException` - if the `set` operation is not supported by this list IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`)

    - #### set

          void set(int index,
                 byte[] element)

      Replaces the element at the specified position in this list with the specified element (optional operation).
      Parameters:
        `index` - index of the element to replace
        `element` - the element to be stored at the specified position
      Throws:
        `java.lang.UnsupportedOperationException` - if the `set` operation is not supported by this list IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`)

    - #### addAllByteString

          boolean addAllByteString(java.util.Collection<? extends ByteString> c)

      Appends all elements in the specified ByteString collection to the end of this list.
      Parameters:
        `c` - collection whose elements are to be added to this list
      Returns:
        true if this list changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if the `addAllByteString` operation is not supported by this list

    - #### addAllByteArray

          boolean addAllByteArray(java.util.Collection<byte[]> c)

      Appends all elements in the specified byte[] collection to the end of this list.
      Parameters:
        `c` - collection whose elements are to be added to this list
      Returns:
        true if this list changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if the `addAllByteArray` operation is not supported by this list

    - #### getUnderlyingElements

          java.util.List<?> getUnderlyingElements()

      Returns an unmodifiable List of the underlying elements, each of which is either a `String` or its equivalent UTF-8 encoded `ByteString` or byte[]. It is an error for the caller to modify the returned List, and attempting to do so will result in an `UnsupportedOperationException`.

    - #### mergeFrom

          void mergeFrom(LazyStringList other)

      Merges all elements from another LazyStringList into this one. This method differs from `List.addAll(Collection)` on that underlying byte arrays are copied instead of reference shared. Immutable API doesn't need to use this method as byte[] is not used there at all.

    - #### asByteArrayList

          java.util.List<byte[]> asByteArrayList()

      Returns a mutable view of this list. Changes to the view will be made into the original list. This method is used in mutable API only.

    - #### getUnmodifiableView

          LazyStringList getUnmodifiableView()

      Returns an unmodifiable view of the list.