com.intellectualcrafters.json

## Class Kim

- java.lang.Object
- - com.intellectualcrafters.json.Kim

-     public class Kim
      extends java.lang.Object

  Kim makes immutable eight bit Unicode strings. If the MSB of a byte is set, then the next byte is a continuation byte. The last byte of a character never has the MSB reset. Every byte that is not the last byte has the MSB set. Kim stands for "Keep it minimal". A Unicode character is never longer than 3 bytes. Every byte contributes 7 bits to the character. ASCII is unmodified.

  Kim UTF-8 one byte U+007F U+007F two bytes U+3FFF U+07FF three bytes U+10FFF U+FFFF four bytes U+10FFFF

  Characters in the ranges U+0800..U+3FFF and U+10000..U+10FFFF will be one byte smaller when encoded in Kim compared to UTF-8.

  Kim is beneficial when using scripts such as Old South Arabian, Aramaic, Avestan, Balinese, Batak, Bopomofo, Buginese, Buhid, Carian, Cherokee, Coptic, Cyrillic, Deseret, Egyptian Hieroglyphs, Ethiopic, Georgian, Glagolitic, Gothic, Hangul Jamo, Hanunoo, Hiragana, Kanbun, Kaithi, Kannada, Katakana, Kharoshthi, Khmer, Lao, Lepcha, Limbu, Lycian, Lydian, Malayalam, Mandaic, Meroitic, Miao, Mongolian, Myanmar, New Tai Lue, Ol Chiki, Old Turkic, Oriya, Osmanya, Pahlavi, Parthian, Phags-Pa, Phoenician, Samaritan, Sharada, Sinhala, Sora Sompeng, Tagalog, Tagbanwa, Takri, Tai Le, Tai Tham, Tamil, Telugu, Thai, Tibetan, Tifinagh, UCAS.

  A kim object can be constructed from an ordinary UTF-16 string, or from a byte array. A kim object can produce a UTF-16 string.

  As with UTF-8, it is possible to detect character boundaries within a byte sequence. UTF-8 is one of the world's great inventions. While Kim is more efficient, it is not clear that it is worth the expense of transition.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `length` The number of bytes in the kim.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Kim(byte[] bytes, int length)` Make a kim from a byte array.
    `Kim(byte[] bytes, int from, int thru)` Make a kim from a portion of a byte array.
    `Kim(Kim kim, int from, int thru)` Make a new kim from a substring of an existing kim.
    `Kim(java.lang.String string)` Make a kim from a string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `characterAt(int at)` Returns the character at the specified index.
    `static int` | `characterSize(int character)` Returns the number of bytes needed to contain the character in Kim format.
    `int` | `copy(byte[] bytes, int at)` Copy the contents of this kim to a byte array.
    `boolean` | `equals(java.lang.Object obj)` Two kim objects containing exactly the same bytes in the same order are equal to each other.
    `int` | `get(int at)` Get a byte from a kim.
    `int` | `hashCode()` Returns a hash code value for the kim.
    `java.lang.String` | `toString()` Produce a UTF-16 String from this kim.

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

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

- - ### Field Detail

    - #### length

          public int length

      The number of bytes in the kim. The number of bytes can be as much as three times the number of characters.

  - ### Constructor Detail

    - #### Kim

          public Kim(byte[] bytes,
             int from,
             int thru)

      Make a kim from a portion of a byte array.
      Parameters:
        `bytes` - A byte array.
        `from` - The index of the first byte.
        `thru` - The index of the last byte plus one.

    - #### Kim

          public Kim(byte[] bytes,
             int length)

      Make a kim from a byte array.
      Parameters:
        `bytes` - The byte array.
        `length` - The number of bytes.

    - #### Kim

          public Kim(Kim kim,
             int from,
             int thru)

      Make a new kim from a substring of an existing kim. The coordinates are in byte units, not character units.
      Parameters:
        `kim` - The source of bytes.
        `from` - The point at which to take bytes.
        `thru` - The point at which to stop taking bytes.

    - #### Kim

          public Kim(java.lang.String string)
              throws JSONException

      Make a kim from a string.
      Parameters:
        `string` - The string.
      Throws:
        `JSONException` - if surrogate pair mismatch.

  - ### Method Detail

    - #### characterSize

          public static int characterSize(int character)
                                   throws JSONException

      Returns the number of bytes needed to contain the character in Kim format.
      Parameters:
        `character` - a Unicode character between 0 and 0x10FFFF.
      Returns:
        1, 2, or 3
      Throws:
        `JSONException` - if the character is not representable in a kim.

    - #### characterAt

          public int characterAt(int at)
                          throws JSONException

      Returns the character at the specified index. The index refers to byte values and ranges from 0 to length - 1. The index of the next character is at index + Kim.characterSize(kim.characterAt(index)).
      Parameters:
        `at` - the index of the char value. The first character is at 0.
      Throws:
        `JSONException` - if at does not point to a valid character.

    - #### copy

          public int copy(byte[] bytes,
                 int at)

      Copy the contents of this kim to a byte array.
      Parameters:
        `bytes` - A byte array of sufficient size.
        `at` - The position within the byte array to take the byes.
      Returns:
        The position immediately after the copy.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Two kim objects containing exactly the same bytes in the same order are equal to each other.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the other kim with which to compare.

    - #### get

          public int get(int at)
                  throws JSONException

      Get a byte from a kim.
      Parameters:
        `at` - The position of the byte. The first byte is at 0.
      Returns:
        The byte.
      Throws:
        `JSONException` - if there is no byte at that position.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for the kim.
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()
                                    throws JSONException

      Produce a UTF-16 String from this kim. The number of codepoints in the string will not be greater than the number of bytes in the kim, although it could be less.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        The string. A kim memoizes its string representation.
      Throws:
        `JSONException` - if the kim is not valid.