ByteString (Rembulan Runtime 0.1-SNAPSHOT API)

java.lang.Object
- net.sandius.rembulan.ByteString

All Implemented Interfaces:

Comparable<ByteString>
```
public abstract class ByteString
extends Object
implements Comparable<ByteString>
```
Byte string, an immutable sequence of bytes.
The purpose of this class is to serve as a bridge between Java strings (with their characters corresponding to 16-bit code units in the Basic Multilingual Plane (BMP)) and Lua strings (raw 8-bit sequences).

Byte strings come in two flavours:
- one is a wrapper of java.lang.String with a given Charset — constructed using of(String);
- the other is a wrapper of a byte arrays — constructed using wrap(byte[]).
The ByteString class provides the functionality for treating both cases as sequences of bytes when they take part in Lua operations, and as Java strings when used by an outer Java application. However, these perspectives are as lazy as possible, in order to avoid doing unnecessary work.

This class provides a natural lexicographical ordering that is consistent with equals.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`InputStream`	`asInputStream()` Returns an input stream that reads the contents of this string.
`abstract byte`	`byteAt(int index)` Returns the byte at position `index`.
`abstract ByteIterator`	`byteIterator()` Returns an iterator over the bytes in this byte string.
`int`	`compareTo(ByteString that)` Compares this byte string lexicographically with `that`.
`ByteString`	`concat(ByteString other)` Returns a byte string formed by a concatenating this byte string with the byte string `other`.
`ByteString`	`concat(String other)` Returns a byte string formed by concatenating this byte string with the string `other`.
`static ByteString`	`constOf(String s)` Returns a byte string corresponding to the bytes in `s` as encoded by the default charset in a form suitable for use as a string constant.
`boolean`	`contains(byte b)` Returns `true` if the byte string contains the byte `b`.
`static ByteString`	`copyOf(byte[] bytes)` Returns a byte string containing a copy of the byte array `bytes`.
`static ByteString`	`copyOf(byte[] bytes, int offset, int length)` Returns a byte string containing a copy of a slice of the byte array `bytes` starting at the offset `offset` and consisting of `length` bytes.
`String`	`decode()` Returns a string represented by this byte string decoded using the default charset of the virtual machine.
`String`	`decode(Charset charset)` Returns a string representation of this byte string that uses the specified charset `charset` to decode characters from bytes.
`static ByteString`	`empty()` Returns an empty byte string.
`boolean`	`equals(Object o)` Returns `true` if `o` is a byte string containing the same bytes as this byte string.
`static ByteString`	`fromRaw(String s)` Returns a new byte string corresponding to bytes in `s` by taking the least significant byte of each character.
`abstract byte[]`	`getBytes()` Returns a new byte array containing the bytes of this byte string.
`abstract int`	`hashCode()` Returns the hash code of this byte string.
`abstract boolean`	`isEmpty()` Returns `true` iff this byte string is empty, i.e., if the number of bytes it contains is 0.
`abstract int`	`length()` Returns the length of this byte string, i.e., the number of bytes it contains.
`static ByteString`	`of(String s)` Returns a new byte string corresponding to the bytes in `s` as encoded by the default charset (`Charset.defaultCharset()`).
`static ByteString`	`of(String s, Charset charset)` Returns a new byte string corresponding to the bytes in `s` as encoded by the specified `charset`.
`abstract void`	`putTo(ByteBuffer buffer)` Puts the contents of this byte string to the specified `buffer`.
`ByteString`	`replace(ByteString target, ByteString replacement)` Replaces all occurrences of the byte string `target` in this byte string with the replacement `replacement`.
`abstract boolean`	`startsWith(byte b)` Returns `true` if the first byte of this byte string is `b`.
`abstract ByteString`	`substring(int start, int end)` Returns a substring of this byte string starting at position `start` (inclusive), ending at position `end` (exclusive).
`abstract String`	`toRawString()` Returns a string in which all characters are directly mapped to the bytes in this byte string by treating them as unsigned integers.
`abstract String`	`toString()` Returns the interpretation of this byte string as a Java string.
`abstract void`	`writeTo(OutputStream stream)` Writes the contents of this byte string to the specified `stream`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - of
```
public static ByteString of(String s,
                            Charset charset)
```
    Returns a new byte string corresponding to the bytes in s as encoded by the specified charset.
    
    Parameters:
    
    s - the string to take the byte view of, must not be null
    
    charset - the charset to use for decoding s into bytes, must not be null
    
    Returns:
    
    a byte string perspective of s using charset
    
    Throws:
    
    NullPointerException - if s or charset is null
    
    IllegalArgumentException - if charset does not provide encoding capability (see Charset.canEncode())
  - of
```
public static ByteString of(String s)
```
    Returns a new byte string corresponding to the bytes in s as encoded by the default charset (Charset.defaultCharset()).
    
    Parameters:
    
    s - the string to take the perspective of, must not be null
    
    Returns:
    
    a byte string perspective of s
    
    Throws:
    
    NullPointerException - if s is null
  - fromRaw
```
public static ByteString fromRaw(String s)
```
    Returns a new byte string corresponding to bytes in s by taking the least significant byte of each character.
    
    Parameters:
    
    s - the string to get bytes from, must not be null
    
    Returns:
    
    a byte string based on s by taking the least significant byte of each char
    
    Throws:
    
    NullPointerException - if s is null
  - constOf
```
public static ByteString constOf(String s)
```
    Returns a byte string corresponding to the bytes in s as encoded by the default charset in a form suitable for use as a string constant.
    This method differs from of(String) in that it may force the computation of lazily-evaluated properties of the resulting string at instantiation time and cache them for use at runtime.
    
    Parameters:
    
    s - the string to get bytes from, must not be null
    
    Returns:
    
    a byte string based on a byte perspective of s
  - copyOf
```
public static ByteString copyOf(byte[] bytes)
```
    Returns a byte string containing a copy of the byte array bytes.
    
    Parameters:
    
    bytes - the byte array to use as the byte string, must not be null
    
    Returns:
    
    a byte string containing a copy of bytes
    
    Throws:
    
    NullPointerException - if bytes is null
  - copyOf
```
public static ByteString copyOf(byte[] bytes,
                                int offset,
                                int length)
```
    Returns a byte string containing a copy of a slice of the byte array bytes starting at the offset offset and consisting of length bytes.
    
    Parameters:
    
    bytes - the byte array to use as the byte string, must not be null
    
    offset - offset in bytes to start reading from
    
    length - the number of bytes to copy from bytes
    
    Returns:
    
    a byte string containing a copy of bytes
    
    Throws:
    
    NullPointerException - if bytes is null
    
    IndexOutOfBoundsException - if offset or length are negative, or if (offset + length) is greater than bytes.length
  - empty
```
public static ByteString empty()
```
    Returns an empty byte string.
    
    Returns:
    
    an empty byte string
  - equals
```
public final boolean equals(Object o)
```
    Returns true if o is a byte string containing the same bytes as this byte string.
    Note: this method uses the strict interpretation of byte strings as byte sequences. It is therefore not necessarily true that for two byte strings a and b, the result of their comparison is the same as the result of comparing their images provided by toString():
```
     boolean byteEq = a.equals(b);
     boolean stringEq = a.toString().equals(b.toString());

     // may fail!
     assert (byteEq == stringEq);
 
```
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    o - object to evaluate for equality with, may be null
    
    Returns:
    
    true iff o is a byte string with equal contents to this
  - hashCode
```
public abstract int hashCode()
```
    Returns the hash code of this byte string. The hash code is computed using the same function as used by String.hashCode(), interpreting the byte string's bytes as unsigned integers.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code of this byte string
  - getBytes
```
public abstract byte[] getBytes()
```
    Returns a new byte array containing the bytes of this byte string.
    
    Returns:
    
    a new byte array
  - byteAt
```
public abstract byte byteAt(int index)
```
    Returns the byte at position index.
    
    Parameters:
    
    index - the position in the string
    
    Returns:
    
    the byte at position index
    
    Throws:
    
    IndexOutOfBoundsException - if index < 0 or index >= length()
  - byteIterator
```
public abstract ByteIterator byteIterator()
```
    Returns an iterator over the bytes in this byte string.
    
    Returns:
    
    an iterator over the bytes in this byte string
  - asInputStream
```
public InputStream asInputStream()
```
    Returns an input stream that reads the contents of this string.
    
    Returns:
    
    an input stream that reads the contents of this string
  - length
```
public abstract int length()
```
    Returns the length of this byte string, i.e., the number of bytes it contains.
    
    Returns:
    
    the length of this byte string
  - isEmpty
```
public abstract boolean isEmpty()
```
    Returns true iff this byte string is empty, i.e., if the number of bytes it contains is 0.
    
    Returns:
    
    true iff this byte string is empty
  - substring
```
public abstract ByteString substring(int start,
                                     int end)
```
    Returns a substring of this byte string starting at position start (inclusive), ending at position end (exclusive).
    The indices refer to the byte position in the byte string.
    
    Parameters:
    
    start - the first index to include in the new substring (inclusive)
    
    end - the smallest index immediately following the new substring in this byte string
    
    Returns:
    
    a substring of this byte string ranging from start (inclusive) to end (exclusive)
    
    Throws:
    
    IndexOutOfBoundsException - if start < 0, end > length() or start > end
  - putTo
```
public abstract void putTo(ByteBuffer buffer)
```
    Puts the contents of this byte string to the specified buffer.
    
    Parameters:
    
    buffer - the buffer to use, must not be null
    
    Throws:
    
    NullPointerException - if buffer is null
  - writeTo
```
public abstract void writeTo(OutputStream stream)
                      throws IOException
```
    Writes the contents of this byte string to the specified stream.
    
    Parameters:
    
    stream - the stream to use, must not be null
    
    Throws:
    
    IOException - when I/O error happens during the write
    
    NullPointerException - if stream is null
  - toString
```
public abstract String toString()
```
    Returns the interpretation of this byte string as a Java string.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the string represented by this byte string
  - decode
```
public String decode(Charset charset)
```
    Returns a string representation of this byte string that uses the specified charset charset to decode characters from bytes.
    
    Parameters:
    
    charset - the charset to use, must not be null
    
    Returns:
    
    this byte string decoded into a string using charset
    
    Throws:
    
    NullPointerException - if charset is null
  - decode
```
public String decode()
```
    Returns a string represented by this byte string decoded using the default charset of the virtual machine.
    This is effectively equivalent to decode(Charset) called with Charset.defaultCharset().
    
    Returns:
    
    a string decoded from this byte string using the platform's default charset
  - toRawString
```
public abstract String toRawString()
```
    Returns a string in which all characters are directly mapped to the bytes in this byte string by treating them as unsigned integers.
    This method is the complement of fromRaw(String).
    
    Returns:
    
    a raw string based on this byte string
  - compareTo
```
public int compareTo(ByteString that)
```
    Compares this byte string lexicographically with that. Returns a negative integer, zero, or a positive integer if this is lesser than, equal to or greater than that in this ordering.
    For the purposes of this ordering, bytes are interpreted as unsigned integers.
    
    Note: this method uses the strict interpretation of byte strings as byte sequences. It is therefore not necessarily true that for two byte strings a and b, the result of their comparison is the same as the result of comparing their images provided by toString():
```
     int byteCmp = a.compareTo(b);
     int stringCmp = a.toString().compareTo(b.toString());

     // may fail!
     assert(Integer.signum(byteCmp) == Integer.signum(stringCmp));
 
```
    This is done in order to ensure that the natural ordering provided by this compareTo() is consistent with equals.
    Specified by:
    
    compareTo in interface Comparable<ByteString>
    
    Parameters:
    
    that - byte string to compare to, must not be null
    
    Returns:
    
    a negative, zero, or positive integer if this is lexicographically lesser than, equal to or greater than that
    
    Throws:
    
    NullPointerException - if that is null
  - concat
```
public ByteString concat(ByteString other)
```
    Returns a byte string formed by a concatenating this byte string with the byte string other.
    Note: this method uses the non-strict interpretation and therefore may (but might not necessarily) preserve unmappable and malformed characters occurring in the two strings.
    
    Parameters:
    
    other - the byte string to concatenate this byte string with, must not be null
    
    Returns:
    
    this byte string concatenated with other
    
    Throws:
    
    NullPointerException - if other is null
  - concat
```
public ByteString concat(String other)
```
    Returns a byte string formed by concatenating this byte string with the string other.
    This is a convenience method equivalent to
```
     concat(ByteString.of(other))
 
```
    Parameters:
    
    other - the string to concatenate with, must not be null
    
    Returns:
    
    this byte string concatenated with other
    
    Throws:
    
    NullPointerException - if other is null
  - startsWith
```
public abstract boolean startsWith(byte b)
```
    Returns true if the first byte of this byte string is b.
    
    Parameters:
    
    b - the byte to compare the first byte of this byte string to
    
    Returns:
    
    true if this byte string starts with b
  - contains
```
public boolean contains(byte b)
```
    Returns true if the byte string contains the byte b.
    
    Parameters:
    
    b - the byte to search for in the byte string
    
    Returns:
    
    true if this byte string contains b
  - replace
```
public ByteString replace(ByteString target,
                          ByteString replacement)
```
    Replaces all occurrences of the byte string target in this byte string with the replacement replacement.
    
    Parameters:
    
    target - the substring to replace, must not be null
    
    replacement - the replacement, must not be null
    
    Returns:
    
    this byte string with all occurrences of target replaced by replacement
    
    Throws:
    
    NullPointerException - if target or replacement is null

Class ByteString

Method Summary

Methods inherited from class java.lang.Object

Method Detail

of

of

fromRaw

constOf

copyOf

copyOf

empty

equals

hashCode

getBytes

byteAt

byteIterator

asInputStream

length

isEmpty

substring

putTo

writeTo

toString

decode

decode

toRawString

compareTo

concat

concat

startsWith

contains

replace