Conversions (Rembulan Runtime 0.1-SNAPSHOT API)

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

```
public final class Conversions
extends Object
```
Static methods implementing Lua value conversions.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static Number`	`arithmeticValueOf(Object o)` Returns the arithmetic value of the object `o`, or `null` if `o` does not have an arithmetic value.
`static boolean`	`booleanValueOf(Object o)` Returns the boolean value of the object `o`.
`static Object`	`canonicalRepresentationOf(Object o)` Returns the value `o` to its canonical representation.
`static Object[]`	`copyAsCanonicalValues(Object[] values)` Returns a copy of the array `values` with all values converted to their canonical representation.
`static Object[]`	`copyAsJavaValues(Object[] values)` Returns a copy of the array `values` with all values converted to their Java representation.
`static Double`	`floatValueOf(Number n)` Returns the float value of the number `n`.
`static Double`	`floatValueOf(Object o)` Returns the float value of the object `o`, or `null` if `o` does not have a float value.
`static Long`	`integerValueOf(Number n)` Returns the integer value of the number `n`, or `null` if `n` does not have an integer value.
`static Long`	`integerValueOf(Object o)` Returns the integer value of the object `o`, or `null` if `o` does not have an integer value.
`static Object`	`javaRepresentationOf(Object o)` Returns the value `o` in its Java representation.
`static Number`	`normaliseKey(Number n)` Normalises the number `n` so that it may be used as a key in a Lua table.
`static Object`	`normaliseKey(Object o)` Normalises the argument `o` so that it may be used safely as a key in a Lua table.
`static Number`	`numericalValueOf(ByteString s)` Returns the numerical value of the string `s`, or `null` if `s` does not have a numerical value.
`static Number`	`numericalValueOf(Object o)` Returns the numerical value of the object `o`, or `null` if `o` does not have a numerical value.
`static ByteString`	`stringValueOf(Number n)` Returns the string value of the number `n`.
`static ByteString`	`stringValueOf(Object o)` Returns the string value of the object `o`, or `null` if `o` does not have a string value.
`static Number`	`toCanonicalNumber(Number n)` Returns the number `n` in its canonical representation, i.e.
`static void`	`toCanonicalValues(Object[] values)` Modifies the contents of the array `values` by converting all values to their canonical representations.
`static ByteString`	`toErrorMessage(Throwable t)` Converts a `Throwable` `t` to an error message (a byte string).
`static Object`	`toErrorObject(Throwable t)` Converts a `Throwable` `t` to an error object.
`static ByteString`	`toHumanReadableString(Object o)` Converts the object `o` to a human-readable string format.
`static long`	`toIntegerValue(Number n)` Returns the integer value of the number `n`, throwing a `NoIntegerRepresentationException` if `n` does not have an integer value.
`static long`	`toIntegerValue(Object o)` Returns the integer value of the object `o`, throwing a `NoIntegerRepresentationException` if `o` does not have an integer value.
`static void`	`toJavaValues(Object[] values)` Modifies the contents of the array `values` by converting all values to their Java representations.
`static Number`	`toNumericalValue(Object o, String name)` Returns the numerical value of `o`, throwing a `ConversionException` if `o` does not have a numerical value.

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

- Method Detail
  - numericalValueOf
```
public static Number numericalValueOf(ByteString s)
```
    Returns the numerical value of the string s, or null if s does not have a numerical value.
    If s is a valid Lua integer literal with optional sign, the numerical value is the corresponding integer; if s is a valid Lua float literal with optional sign, the numerical value is the corresponding float. Otherwise, the s does not have a numerical value.
    
    Leading and trailing whitespace in s is ignored by this method.
    
    Numbers returned by this method are in the canonical representation.
    
    Parameters:
    
    s - string to convert to numerical value, may be null
    
    Returns:
    
    a number representing the numerical value of s (in the canonical representation), or null if s does not have a numerical value
  - numericalValueOf
```
public static Number numericalValueOf(Object o)
```
    Returns the numerical value of the object o, or null if o does not have a numerical value.
    If o is already a number, returns o cast to number. If o is a string, returns its numerical value (see numericalValueOf(ByteString)). Otherwise, returns null.
    
    This method differs from arithmeticValueOf(Object) in that it preserves the numerical value representation of coerced strings. For use in arithmetic operations following Lua's argument conversion rules, use that method instead.
    
    Numbers returned by this method are not necessarily in the canonical representation.
    
    Parameters:
    
    o - object to convert to numerical value, may be null
    
    Returns:
    
    number representing the numerical value of o (not necessarily in the canonical representation), of null if o does not have a numerical value
    
    See Also:
    
    arithmeticValueOf(Object)
  - toNumericalValue
```
public static Number toNumericalValue(Object o,
                                      String name)
```
    Returns the numerical value of o, throwing a ConversionException if o does not have a numerical value.
    The conversion rules are those of numericalValueOf(Object); the only difference is that this method throws an exception rather than returning null to signal errors.
    
    Numbers returned by this method are not necessarily in the canonical representation.
    
    Parameters:
    
    o - object to convert to numerical value, may be null
    
    name - value name for error reporting, may be null
    
    Returns:
    
    number representing the numerical value of o (not necessarily in the canonical representation), guaranteed to be non-null
    
    Throws:
    
    ConversionException - if o is not a number or string convertible to number.
    
    See Also:
    
    numericalValueOf(Object)
  - toCanonicalNumber
```
public static Number toCanonicalNumber(Number n)
```
    Returns the number n in its canonical representation, i.e. a Long if n is a Lua integer, or a Double if n is a Lua float.
    
    Parameters:
    
    n - number to convert to canonical representation, must not be null
    
    Returns:
    
    an instance of Long if n is an integer, or an instance of Double if n is a float
    
    Throws:
    
    NullPointerException - if n is null
  - canonicalRepresentationOf
```
public static Object canonicalRepresentationOf(Object o)
```
    Returns the value o to its canonical representation.
    For numbers, this method is equivalent to toCanonicalNumber(Number). If o is a java.lang.String, it is wrapped into a byte string by ByteString.of(String). Otherwise, o is in canonical representation.
    
    This method is intended for use at the Java → Lua boundary, and whenever it is not certain that o is in a canonical representation when a canonical representation is required.
    
    Parameters:
    
    o - value to convert to canonical representation, may be null
    
    Returns:
    
    o converted to canonical representation
  - javaRepresentationOf
```
public static Object javaRepresentationOf(Object o)
```
    Returns the value o in its Java representation.
    If o is a ByteString, returns o as a java.lang.String (using ByteString.toString(). Otherwise, returns o.
    
    This method is intended for use at the Lua → Java boundary for interoperating with Java code unaware of (or not concerned with) the interpretation of Lua strings as sequences of bytes.
    
    Parameters:
    
    o - value to convert to Java representation, may be null
    
    Returns:
    
    o converted to a java.lang.String if o is a byte string, o otherwise
  - toCanonicalValues
```
public static void toCanonicalValues(Object[] values)
```
    Modifies the contents of the array values by converting all values to their canonical representations.
    
    Parameters:
    
    values - values to convert to their canonical representations, must not be null
    
    Throws:
    
    NullPointerException - if values is null
    
    See Also:
    
    canonicalRepresentationOf(Object)
  - toJavaValues
```
public static void toJavaValues(Object[] values)
```
    Modifies the contents of the array values by converting all values to their Java representations.
    This method is intended for use at the Lua → Java boundary for interoperating with Java code unaware of (or not concerned with) the interpretation of Lua strings as sequences of bytes.
    
    Parameters:
    
    values - values to convert to their Java representations, must not be null
    
    Throws:
    
    NullPointerException - if values is null
    
    See Also:
    
    javaRepresentationOf(Object)
  - copyAsCanonicalValues
```
public static Object[] copyAsCanonicalValues(Object[] values)
```
    Returns a copy of the array values with all values converted to their canonical representation.
    
    Parameters:
    
    values - values to convert to their canonical representation, must not be null
    
    Returns:
    
    a copy of values with all elements converted to canonical representation
    
    See Also:
    
    canonicalRepresentationOf(Object)
  - copyAsJavaValues
```
public static Object[] copyAsJavaValues(Object[] values)
```
    Returns a copy of the array values with all values converted to their Java representation.
    This method is intended for use at the Lua → Java boundary for interoperating with Java code unaware of (or not concerned with) the interpretation of Lua strings as sequences of bytes.
    
    Parameters:
    
    values - values to convert to their Java representation, must not be null
    
    Returns:
    
    a copy of values with all elements converted to their Java representation
    
    See Also:
    
    javaRepresentationOf(Object)
  - normaliseKey
```
public static Number normaliseKey(Number n)
```
    Normalises the number n so that it may be used as a key in a Lua table.
    If n has an integer value i, returns the canonical representation of i; otherwise, returns the canonical representation of n (see toCanonicalNumber(Number)).
    
    Parameters:
    
    n - number to normalise, must not be null
    
    Returns:
    
    an canonical integer if n has an integer value, the canonical representation of n otherwise
    
    Throws:
    
    NullPointerException - if n is null
  - normaliseKey
```
public static Object normaliseKey(Object o)
```
    Normalises the argument o so that it may be used safely as a key in a Lua table.
    If o is a number, returns the number normalised (see normaliseKey(Number). If o is a java.lang.String, returns o as a byte string using ByteString.of(String). Otherwise, returns o.
    
    Parameters:
    
    o - object to normalise, may be null
    
    Returns:
    
    normalised number if o is a number, o as byte string if o is a java.lang.String, o otherwise
  - arithmeticValueOf
```
public static Number arithmeticValueOf(Object o)
```
    Returns the arithmetic value of the object o, or null if o does not have an arithmetic value.
    If o is a number, then that number is its arithmetic value. If o is a string that has a numerical value (see numericalValueOf(ByteString)), its arithmetic value is the numerical value converted to a float. Otherwise, o does not have an arithmetic value.
    
    Note that this method differs from numericalValueOf(Object) in that it coerces strings convertible to numbers into into floats rather than preserving their numerical value representation, and also note that this conversion happens after the numerical value has been determined. Most significantly,
```
     Conversions.arithmeticValueOf("-0")
 
```
    yields 0.0 rather than 0 (as would be the case with numericalValueOf("-0")), or -0.0 (it would in the case if the string was parsed directly as a float).
    
    Numbers returned by this method are not necessarily in the canonical representation.
    Parameters:
    
    o - object to convert to arithmetic value, may be null
    
    Returns:
    
    number representing the arithmetic value of o (not necessarily in the canonical representation), or null if o does not have an arithmetic value
    
    See Also:
    
    numericalValueOf(Object)
  - integerValueOf
```
public static Long integerValueOf(Number n)
```
    Returns the integer value of the number n, or null if n does not have an integer value.
    n has an integer value if and only if the number it denotes can be represented as a signed 64-bit integer. That integer is then the integer value of n. In other words, if n is a float, it has an integer value if and only if it can be converted to a long without loss of precision.
    
    Parameters:
    
    n - number to convert to integer, must not be null
    
    Returns:
    
    a Long representing the integer value of n, or null if n does not have an integer value
    
    Throws:
    
    NullPointerException - if n is null
    
    See Also:
    
    LuaMathOperators.hasExactIntegerRepresentation(double)
  - toIntegerValue
```
public static long toIntegerValue(Number n)
```
    Returns the integer value of the number n, throwing a NoIntegerRepresentationException if n does not have an integer value.
    This is a variant of integerValueOf(Number); the difference is that this method throws an exception rather than returning null to signal that n does not have an integer value, and that this method returns the unboxed integer value of n (as a long).
    
    Parameters:
    
    n - object to be converted to integer, must not be null
    
    Returns:
    
    integer value of n
    
    Throws:
    
    NoIntegerRepresentationException - if n does not have an integer value
    
    NullPointerException - if n is null
  - integerValueOf
```
public static Long integerValueOf(Object o)
```
    Returns the integer value of the object o, or null if o does not have an integer value.
    The integer value of o is the integer value of its numerical value (see numericalValueOf(Object)), when it exists.
    
    Parameters:
    
    o - object to be converted to integer, may be null
    
    Returns:
    
    a Long representing the integer value of o, or null if o does not have a integer value
    
    See Also:
    
    integerValueOf(Number)
  - toIntegerValue
```
public static long toIntegerValue(Object o)
```
    Returns the integer value of the object o, throwing a NoIntegerRepresentationException if o does not have an integer value.
    This is a variant of integerValueOf(Object); the difference is that this method throws an exception rather than returning null to signal that o does not have an integer value, and that this method returns the unboxed integer value of o (as a long).
    
    Parameters:
    
    o - object to be converted to integer, may be null
    
    Returns:
    
    integer value of n
    
    Throws:
    
    NoIntegerRepresentationException - if o does not have an integer value
  - floatValueOf
```
public static Double floatValueOf(Number n)
```
    Returns the float value of the number n.
    The float value of n is its numerical value converted to a Lua float.
    
    Parameters:
    
    n - the number to convert to float, must not be null
    
    Returns:
    
    the float value of n, guaranteed to be non-null
    
    Throws:
    
    NullPointerException - if n is null
  - floatValueOf
```
public static Double floatValueOf(Object o)
```
    Returns the float value of the object o, or null if o does not have a float value.
    The float value of o is the float value of its numerical value (see numericalValueOf(Object)), when o has a numerical value.
    
    Parameters:
    
    o - the object to be converted to float, may be null
    
    Returns:
    
    a Double representing the float value of o, or null if o does not have a float value
  - booleanValueOf
```
public static boolean booleanValueOf(Object o)
```
    Returns the boolean value of the object o.
    The boolean value of o is false if and only if o is nil (i.e., null) or false (i.e., a Boolean b such that b.booleanValue() == false).
    
    Parameters:
    
    o - object to convert to boolean, may be null
    
    Returns:
    
    false if o is nil or false, true otherwise
  - stringValueOf
```
public static ByteString stringValueOf(Number n)
```
    Returns the string value of the number n.
    The string value of integers is the result of LuaFormat.toByteString(long) on their numerical value; similarly the string value of floats is the result of LuaFormat.toByteString(double) on their numerical value.
    
    Parameters:
    
    n - number to be converted to string, must not be null
    
    Returns:
    
    string value of n, guaranteed to be non-null
    
    Throws:
    
    NullPointerException - if n is null
  - stringValueOf
```
public static ByteString stringValueOf(Object o)
```
    Returns the string value of the object o, or null if o does not have a string value.
    If o is a string, that is the string value. If o is a number, returns the string value of that number (see stringValueOf(Number)). Otherwise, o does not have a string value.
    
    Parameters:
    
    o - object to be converted to string, may be null
    
    Returns:
    
    string value of o, or null if o does not have a string value
  - toHumanReadableString
```
public static ByteString toHumanReadableString(Object o)
```
    Converts the object o to a human-readable string format.
    The conversion rules are the following:
    - If o is a string or number, returns the string value of o;
    - if o is nil (i.e., null), returns "nil";
    - if o is a boolean, returns "true" if o is true or "false" if o is false;
    - otherwise, returns the string of the form "TYPE: 0xHASH", where TYPE is the Lua type of o, and HASH is the Object.hashCode() of o in hexadecimal format.
    Note that this method ignores the object's toString() method and its __tostring metamethod.
    Parameters:
    
    o - the object to be converted to string, may be null
    
    Returns:
    
    human-readable string representation of o
    
    See Also:
    
    stringValueOf(Object)
  - toErrorObject
```
public static Object toErrorObject(Throwable t)
```
    Converts a Throwable t to an error object.
    If t is a LuaRuntimeException, the result of this operation is the result of its LuaRuntimeException.getErrorObject(). Otherwise, the result is Throwable.getMessage().
    
    Parameters:
    
    t - throwable to convert to error object, must not be null
    
    Returns:
    
    error object represented by t
    
    Throws:
    
    NullPointerException - if t is null
  - toErrorMessage
```
public static ByteString toErrorMessage(Throwable t)
```
    Converts a Throwable t to an error message (a byte string).
    This is equivalent to converting the error object retrieved from t by toErrorObject(Throwable) to a byte string using stringValueOf(Object).
    
    If the error object does not have a string value, returns "(null)".
    
    Parameters:
    
    t - throwable to convert to error message, must not be null
    
    Returns:
    
    error message of t, or "(null)" if t does not have a string error message
    
    Throws:
    
    NullPointerException - if t is null

Class Conversions

Method Summary

Methods inherited from class java.lang.Object

Method Detail

numericalValueOf

numericalValueOf

toNumericalValue

toCanonicalNumber

canonicalRepresentationOf

javaRepresentationOf

toCanonicalValues

toJavaValues

copyAsCanonicalValues

copyAsJavaValues

normaliseKey

normaliseKey

arithmeticValueOf

integerValueOf

toIntegerValue

integerValueOf

toIntegerValue

floatValueOf

floatValueOf

booleanValueOf

stringValueOf

stringValueOf

toHumanReadableString

toErrorObject

toErrorMessage