MFString (3.14.0 310 API)
Date: 2018-05-30

com.marketfactory.zerogc.api

## Class MFString

- java.lang.Object
- - com.marketfactory.zerogc.api.MFString

- All Implemented Interfaces:
    java.io.Serializable, java.lang.CharSequence, java.lang.Comparable

      public class MFString
      extends java.lang.Object
      implements java.lang.Comparable, java.lang.CharSequence, java.io.Serializable

  A mutable string to support zero gc applications. Its interface is modelled of of java.util.StringBuilder. These strings must contain strings that are part of the printable ASCII subset of Java's UTF-16 characters since whisperer strings are ASCII. It supports up to a max length of 1024 characters. Will throw an IndexOutOfBoundsException if there is an attempt to exceed the capacity.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `MAX_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MFString()` Default constructor.
    `MFString(java.lang.CharSequence str)` Initializes using the characters from a CharSequence.
    `MFString(int maxSize)` Creates an MFString with the specified maximum size.
    `MFString(MFString str)` Copy constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `MFString` | `append(char c)` Append a char at the end of the string.
    `MFString` | `append(char[] c)` Append a char array at the end of the string.
    `MFString` | `append(java.lang.CharSequence s)` Append the contents of a CharSequence to this string
    `MFString` | `append(java.lang.CharSequence s, int start, int end)` Append the CharSequence to this string within the given range.
    `MFString` | `append(int i)` Append an int representation of a string at the end of the string.
    `MFString` | `append(long l)` Append an int representation of a string at the end of the string.
    `MFString` | `append(MFString s)` Append the contents of a MFString to this string
    `char` | `charAt(int index)` Get the length of the string.
    `int` | `compareTo(java.lang.Object o)` Implements Comparable method compareTo.
    `void` | `deepCopy(MFString src)` Copies the state of the source MFString to this string.
    `boolean` | `equals(java.lang.Object o)`
    `void` | `freeze()` Freeze the state.
    `int` | `hashCode()` This is for the use case where the object needs to be in a pool (in order to avoid creating garbage) but also in a java collection, such as HashMap, which needs to have this in order to operate properly.
    `boolean` | `isEmpty()` Convenience method which exists in String.
    `int` | `length()` Get the length of the string.
    `void` | `reset()` Resets the string so a new string can be created.
    `void` | `setCharAt(int index, char ch)` Change the char at a specific index.
    `java.lang.CharSequence` | `subSequence(int start, int end)` Returns a new CharSequence that is a subsequence of this sequence.
    `java.lang.String` | `toString()` WARNING: Creates garbage.
    `void` | `unfreeze()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.lang.CharSequence

      `chars, codePoints`

- - ### Field Detail

    - #### MAX_SIZE

          public static final int MAX_SIZE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MFString

          public MFString()

      Default constructor. Creates an empty string.

    - #### MFString

          public MFString(int maxSize)

      Creates an MFString with the specified maximum size. This overrides the default provided by `MAX_SIZE`.
      Parameters:
        `maxSize` - max size of this MFString

    - #### MFString

          public MFString(MFString str)

      Copy constructor.
      Parameters:
        `str` - - the intial value of this string object.

    - #### MFString

          public MFString(java.lang.CharSequence str)

      Initializes using the characters from a CharSequence. WARNING: Be careful when using this constructor as java.lang.String is immutable and therefor can generate garbage easily. This method should be used sparingly for such cases as logging in and subscribing to markets, not for entering orders.
      Parameters:
        `str` - - the intial value of this string object.
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.

  - ### Method Detail

    - #### deepCopy

          public void deepCopy(MFString src)

      Copies the state of the source MFString to this string.
      Parameters:
        `src` - -- the rhs string
      Throws:
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(char c)

      Append a char at the end of the string.
      Parameters:
        `c` - the character to be appended
      Returns:
        the appended string
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(char[] c)

      Append a char array at the end of the string.
      Parameters:
        `c` - the string to be appended
      Returns:
        the appended string
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(MFString s)

      Append the contents of a MFString to this string
      Parameters:
        `s` - the string to be appended
      Returns:
        the appended string
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of sr is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(java.lang.CharSequence s)

      Append the contents of a CharSequence to this string
      Parameters:
        `s` - the string to be appended
      Returns:
        the appended string
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(java.lang.CharSequence s,
                                 int start,
                                 int end)

      Append the CharSequence to this string within the given range.
      Parameters:
        `s` - the string to be appended
        `start` - the start index
        `end` - the end index
      Returns:
        the appended string
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - if either index is not greater than zero and less than 1024 or start is greater than end or if end is greater than s.length();
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(int i)

      Append an int representation of a string at the end of the string.
      Parameters:
        `i` - the integer
      Returns:
        the appended string
      Throws:
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### append

          public MFString append(long l)

      Append an int representation of a string at the end of the string.
      Parameters:
        `l` - the long integer
      Returns:
        the appended string
      Throws:
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### charAt

          public char charAt(int index)

      Get the length of the string.
      Specified by:
        `charAt` in interface `java.lang.CharSequence`
      Throws:
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.

    - #### setCharAt

          public void setCharAt(int index,
                                char ch)

      Change the char at a specific index.
      Parameters:
        `index` - the idx
        `ch` - the character
      Throws:
        `java.lang.IllegalArgumentException` - - if any character is not printable ASCII.
        `java.lang.IndexOutOfBoundsException` - - The length of str is greater than 1024.
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### length

          public int length()

      Get the length of the string.
      Specified by:
        `length` in interface `java.lang.CharSequence`

    - #### isEmpty

          public boolean isEmpty()

      Convenience method which exists in String.
      Returns:
        is empty?

    - #### subSequence

          public java.lang.CharSequence subSequence(int start,
                                                    int end)

      Returns a new CharSequence that is a subsequence of this sequence. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1. The length (in chars) of the returned sequence is end - start, so if start == end then an empty sequence is returned.
      Specified by:
        `subSequence` in interface `java.lang.CharSequence`
      Throws:
        `java.lang.IndexOutOfBoundsException` - - if start or end are negative, if end is greater than length(), or if start is greater than end

    - #### reset

          public void reset()

      Resets the string so a new string can be created.
      Throws:
        `java.lang.IllegalStateException` - - If called when the string has been frozen.

    - #### freeze

          public void freeze()

      Freeze the state. This will cause an exception to be thrown if there is an attempt to mutate the string. This is most useful when using this in a collection.

    - #### unfreeze

          public void unfreeze()

    - #### toString

          public java.lang.String toString()

      WARNING: Creates garbage. For debug only!!! Creates a java.lang.String object.
      Specified by:
        `toString` in interface `java.lang.CharSequence`
      Overrides:
        `toString` in class `java.lang.Object`

    - #### compareTo

          public int compareTo(java.lang.Object o)
                        throws java.lang.ClassCastException

      Implements Comparable method compareTo. Same comparison as implemented for java.lang.String.
      Specified by:
        `compareTo` in interface `java.lang.Comparable`
      Throws:
        `java.lang.ClassCastException`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      This is for the use case where the object needs to be in a pool (in order to avoid creating garbage) but also in a java collection, such as HashMap, which needs to have this in order to operate properly. Care must be taken not to modify the MFString when used in a collection since collections assume the item will immutable.
      Overrides:
        `hashCode` in class `java.lang.Object`