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.