Top Description Constructors Methods
org.jruby.api

public Class Convert

extends Object
Class Inheritance
Imports
org.jruby.RubyArray, .RubyBignum, .RubyBoolean, .RubyClass, .RubyFile, .RubyFixnum, .RubyFloat, .RubyHash, .RubyInteger, .RubyModule, .RubyNil, .RubyNumeric, .RubyProc, .RubyRange, .RubyRational, .RubyString, .RubySymbol, org.jruby.runtime.JavaSites, .ThreadContext, org.jruby.runtime.builtin.IRubyObject, org.jruby.util.ByteList, .TypeConverter, java.math.BigDecimal, .BigInteger

Conversion utilities.

There are 3 mechanisms for converting between types: *

For example, I have a RubyFixnum and I know I need a long I can just call `getValue()`. If I need an int and I know enough about it to not care about range I can call `asInt`. If I do need check range I can call `toInt(context, (RubyFixnum) value)` and it will make sure it is a valid int value. If I don't know for sure if it is even capable of being an int I will call `toInt(context, (IRubyObject) value)`.

The naming conventions will tend to be {resolvedType}?[As|To}{returnedType} where {resolvedType} is omitted when the convention is obvious (`long toLong(ThreadContext context, IRubyObject)`). Right now we have `RubyInteger toInteger(ThreadContext, IRubyObject)` which means making a Ruby Integer vs a Java boxed Integer. If we ever needed a Java Integer (narrator: we won't) we would have to break this convention and make `Integer toJavaInteger(ThreadContext, IRubyObject)`. There are no example of {resolvedType} in any conversion methods but this is reserved in case we have more naming conflicts due to overlapping names.

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public static RubyBoolean

Returns:

the Ruby Boolean
asBoolean
(ThreadContext
the current thread context
context
,
boolean
the boolean value
value
)

Create a Ruby Boolean from a java boolean.

public static RubyFixnum

Returns:

the Ruby Fixnum
asFixnum
(ThreadContext
the current thread context
context
,
long
the long value
value
)

Create a Ruby Fixnum from a java long.

public static RubyFixnum

Returns:

the Ruby Fixnum
asFixnum
(ThreadContext
the current thread context
context
,
int
the int value
value
)

Create a Ruby Fixnum from a java int.

public static RubyFloat

Returns:

the Ruby Float
asFloat
(ThreadContext
the current thread context
context
,
double
the double value
value
)

Create a Ruby Float from a java double.

public static RubyFloat

Returns:

the Ruby Float
asFloat
(ThreadContext
the current thread context
context
,
long
the long value
value
)

Create a Ruby Float from a java long.

public static RubyInteger

Returns:

the result
asInteger
(ThreadContext
the current thread context
context
,
double
the double value
value
)

Create some type of Ruby Integer from a java double

public static RubySymbol

Returns:

the new RubyString
asSymbol
(ThreadContext
the current thread context
context
,
String
the contents to become a symbol
string
)

Creates a new RubySymbol from the provided java String.

public static RubySymbol

Returns:

the new RubyString
asSymbol
(ThreadContext
the current thread context
context
,
ByteList
the contents to become a symbol
bytelist
)

Creates a new RubySymbol from the provided java String.

public static RubySymbol

Returns:

the new RubySymbol
asSymbol
(ThreadContext
the current thread context
context
,
RubyString
the contents to become a symbol
string
)

Creates a new RubySymbol from the provided java String.

public static RubyArray<T extends IRubyObject>

Returns:

the value as a RubyArray
castAsArray
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyArray with most basic typeError thrown if the value is not a RubyArray.

public static RubyArray<T extends IRubyObject>

Returns:

the value as a RubyArray
castAsArray
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyArray with most basic typeError thrown if the value is not a RubyArray.

public static RubyBignum

Returns:

the value as a RubyBignum
castAsBignum
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyBignum with most basic typeError thrown if the value is not a RubyBignum.

public static RubyClass

Returns:

the value as a RubyClass
castAsClass
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyClass with most basic typeError thrown if the value is not a RubyClass.

public static RubyFile

Returns:

the value as a RubyFile
castAsFile
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyFile with most basic typeError thrown if the value is not a RubyFile.

public static RubyFixnum

Returns:

the value as a RubyFixnum
castAsFixnum
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyFixnum with most basic typeError thrown if the value is not a RubyFixnum.

public static RubyFixnum

Returns:

the value as a RubyFixnum
castAsFixnum
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyFixnum with most basic typeError thrown if the value is not a RubyFixnum.

public static RubyHash

Returns:

the value as a RubyHash
castAsHash
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyHash with most basic typeError thrown if the value is not a RubyHash.

public static RubyHash

Returns:

the value as a RubyHash
castAsHash
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyHash with most basic typeError thrown if the value is not a RubyHash.

public static RubyInteger

Returns:

the value as a RubyInteger
castAsInteger
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyInteger with most basic typeError thrown if the value is not a RubyInteger.

public static RubyInteger

Returns:

the value as a RubyInteger
castAsInteger
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyInteger with most basic typeError thrown if the value is not a RubyInteger.

public static RubyModule

Returns:

the value as a RubyModule
castAsModule
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyModule with most basic typeError thrown if the value is not a RubyModule.

public static RubyModule

Returns:

the value as a RubyModule
castAsModule
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyModule with most basic typeError thrown if the value is not a RubyModule.

public static RubyNumeric

Returns:

the value as a RubyNumeric
castAsNumeric
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyNumeric with most basic typeError thrown if the value is not a RubyNumeric.

public static RubyProc

Returns:

the value as a RubyProc
castAsProc
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyProc with most basic typeError thrown if the value is not a RubyProc.

public static RubyProc

Returns:

the value as a RubyProc
castAsProc
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
,
String
the message to include in the type error
message
)

Cast the given value to a RubyProc with most basic typeError thrown if the value is not a RubyProc.

public static RubyRange

Returns:

the value as a RubyRange
castAsRange
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyRange with most basic typeError thrown if the value is not a RubyRange.

public static RubyString

Returns:

the value as a RubyString
castAsString
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubyString with most basic typeError thrown if the value is not a RubyString.

public static RubySymbol

Returns:

the value as a RubySymbol
castAsSymbol
(ThreadContext
the current thread context
context
,
IRubyObject
the value to cast
newValue
)

Cast the given value to a RubySymbol with most basic typeError thrown if the value is not a RubySymbol.

public static int

Returns:

the int value
checkInt
(ThreadContext
the current thread context
context
,
long
the long to check
num
)

Check to make sure the long num given will fit into an int.

public static IRubyObject

Returns:

the integer value or nil if the object or conversion is not an Integer.
checkToInteger
(ThreadContext
the current thread context
context
,
IRubyObject
the object to be converted
obj
)

Check whether the given object is an Integer or can be converted to an Integer using #to_int.

public static IRubyObject

Returns:

a Rational based on the object, or nil if it could not be converted
checkToRational
(ThreadContext
the current thread context
context
,
IRubyObject
the object to convert
obj
)

Convert the given argument to a Rational, or return nil if it cannot be converted.

public static IRubyObject

Returns:

the String value or nil if the object or conversion is not a String.
checkToString
(ThreadContext
the current thread context
context
,
IRubyObject
the object to be converted
obj
)

Check whether the given object is a String or can be converted to a String using #to_str.

public static byte
public static double

Returns:

the value
toDouble
(ThreadContext
the current thread context
context
,
IRubyObject
the Object to convert
arg
)

Safely convert a Ruby Numeric into a java double value.

public static int

Returns:

the int value
toInt
(ThreadContext
the current thread context
context
,
IRubyObject
the RubyNumeric to convert
arg
)

Safely convert a Ruby Numeric into a java long value.

public static long
toInt(ThreadContext context, RubyFloat value)

public static int
public static RubyInteger

Returns:

the int value
toInteger
(ThreadContext
the current thread context
context
,
IRubyObject
the RubyNumeric to convert
arg
)

Safely convert a Ruby Numeric into a java long value.

private static long
public static long

Returns:

the value
toLong
(ThreadContext
the current thread context
context
,
IRubyObject
the RubyNumeric to convert
arg
)

Safely convert a Ruby Numeric into a java long value.

public static long
public static long
toLong(ThreadContext context, RubyFloat value)

private static long
public static RubySymbol

Returns:

the new RubySymbol
toSymbol
(ThreadContext
the current thread context
context
,
IRubyObject
the object to convert to a symbol
arg
)

Convert the given object to a Symbol, possibly calling to_str in the process.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Convertback to summary
public Convert()

Method Detail

asBooleanback to summary
public static RubyBoolean asBoolean(ThreadContext context, boolean value)

Create a Ruby Boolean from a java boolean.

Parameters
context:ThreadContext

the current thread context

value:boolean

the boolean value

Returns:RubyBoolean

the Ruby Boolean

asFixnumback to summary
public static RubyFixnum asFixnum(ThreadContext context, long value)

Create a Ruby Fixnum from a java long.

Parameters
context:ThreadContext

the current thread context

value:long

the long value

Returns:RubyFixnum

the Ruby Fixnum

asFixnumback to summary
public static RubyFixnum asFixnum(ThreadContext context, int value)

Create a Ruby Fixnum from a java int.

Parameters
context:ThreadContext

the current thread context

value:int

the int value

Returns:RubyFixnum

the Ruby Fixnum

asFloatback to summary
public static RubyFloat asFloat(ThreadContext context, double value)

Create a Ruby Float from a java double.

Parameters
context:ThreadContext

the current thread context

value:double

the double value

Returns:RubyFloat

the Ruby Float

asFloatback to summary
public static RubyFloat asFloat(ThreadContext context, long value)

Create a Ruby Float from a java long.

Parameters
context:ThreadContext

the current thread context

value:long

the long value

Returns:RubyFloat

the Ruby Float

asIntegerback to summary
public static RubyInteger asInteger(ThreadContext context, double value)

Create some type of Ruby Integer from a java double

Parameters
context:ThreadContext

the current thread context

value:double

the double value

Returns:RubyInteger

the result

asSymbolback to summary
public static RubySymbol asSymbol(ThreadContext context, String string)

Creates a new RubySymbol from the provided java String.

Parameters
context:ThreadContext

the current thread context

string:String

the contents to become a symbol

Returns:RubySymbol

the new RubyString

asSymbolback to summary
public static RubySymbol asSymbol(ThreadContext context, ByteList bytelist)

Creates a new RubySymbol from the provided java String.

Parameters
context:ThreadContext

the current thread context

bytelist:ByteList

the contents to become a symbol

Returns:RubySymbol

the new RubyString

asSymbolback to summary
public static RubySymbol asSymbol(ThreadContext context, RubyString string)

Creates a new RubySymbol from the provided java String.

Parameters
context:ThreadContext

the current thread context

string:RubyString

the contents to become a symbol

Returns:RubySymbol

the new RubySymbol

castAsArrayback to summary
public static RubyArray<T extends IRubyObject> castAsArray(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyArray with most basic typeError thrown if the value is not a RubyArray.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyArray<T extends IRubyObject>

the value as a RubyArray

castAsArrayback to summary
public static RubyArray<T extends IRubyObject> castAsArray(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyArray with most basic typeError thrown if the value is not a RubyArray.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyArray<T extends IRubyObject>

the value as a RubyArray

castAsBignumback to summary
public static RubyBignum castAsBignum(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyBignum with most basic typeError thrown if the value is not a RubyBignum.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyBignum

the value as a RubyBignum

castAsClassback to summary
public static RubyClass castAsClass(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyClass with most basic typeError thrown if the value is not a RubyClass.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyClass

the value as a RubyClass

castAsFileback to summary
public static RubyFile castAsFile(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyFile with most basic typeError thrown if the value is not a RubyFile.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyFile

the value as a RubyFile

castAsFixnumback to summary
public static RubyFixnum castAsFixnum(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyFixnum with most basic typeError thrown if the value is not a RubyFixnum.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyFixnum

the value as a RubyFixnum

castAsFixnumback to summary
public static RubyFixnum castAsFixnum(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyFixnum with most basic typeError thrown if the value is not a RubyFixnum.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyFixnum

the value as a RubyFixnum

castAsHashback to summary
public static RubyHash castAsHash(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyHash with most basic typeError thrown if the value is not a RubyHash.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyHash

the value as a RubyHash

castAsHashback to summary
public static RubyHash castAsHash(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyHash with most basic typeError thrown if the value is not a RubyHash.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyHash

the value as a RubyHash

castAsIntegerback to summary
public static RubyInteger castAsInteger(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyInteger with most basic typeError thrown if the value is not a RubyInteger.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyInteger

the value as a RubyInteger

castAsIntegerback to summary
public static RubyInteger castAsInteger(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyInteger with most basic typeError thrown if the value is not a RubyInteger.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyInteger

the value as a RubyInteger

castAsModuleback to summary
public static RubyModule castAsModule(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyModule with most basic typeError thrown if the value is not a RubyModule.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyModule

the value as a RubyModule

castAsModuleback to summary
public static RubyModule castAsModule(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyModule with most basic typeError thrown if the value is not a RubyModule.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyModule

the value as a RubyModule

castAsNumericback to summary
public static RubyNumeric castAsNumeric(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyNumeric with most basic typeError thrown if the value is not a RubyNumeric.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyNumeric

the value as a RubyNumeric

castAsProcback to summary
public static RubyProc castAsProc(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyProc with most basic typeError thrown if the value is not a RubyProc.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyProc

the value as a RubyProc

castAsProcback to summary
public static RubyProc castAsProc(ThreadContext context, IRubyObject newValue, String message)

Cast the given value to a RubyProc with most basic typeError thrown if the value is not a RubyProc.

Note

if message is constructed you will pay that contruction cost. Manually cast to avoid that overhead in that case.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

message:String

the message to include in the type error

Returns:RubyProc

the value as a RubyProc

castAsRangeback to summary
public static RubyRange castAsRange(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyRange with most basic typeError thrown if the value is not a RubyRange.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyRange

the value as a RubyRange

castAsStringback to summary
public static RubyString castAsString(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubyString with most basic typeError thrown if the value is not a RubyString.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubyString

the value as a RubyString

castAsSymbolback to summary
public static RubySymbol castAsSymbol(ThreadContext context, IRubyObject newValue)

Cast the given value to a RubySymbol with most basic typeError thrown if the value is not a RubySymbol.

Parameters
context:ThreadContext

the current thread context

newValue:IRubyObject

the value to cast

Returns:RubySymbol

the value as a RubySymbol

checkIntback to summary
public static int checkInt(ThreadContext context, long num)

Check to make sure the long num given will fit into an int.

Parameters
context:ThreadContext

the current thread context

num:long

the long to check

Returns:int

the int value

checkToIntegerback to summary
public static IRubyObject checkToInteger(ThreadContext context, IRubyObject obj)

Check whether the given object is an Integer or can be converted to an Integer using #to_int.

Parameters
context:ThreadContext

the current thread context

obj:IRubyObject

the object to be converted

Returns:IRubyObject

the integer value or nil if the object or conversion is not an Integer.

checkToRationalback to summary
public static IRubyObject checkToRational(ThreadContext context, IRubyObject obj)

Convert the given argument to a Rational, or return nil if it cannot be converted.

Parameters
context:ThreadContext

the current thread context

obj:IRubyObject

the object to convert

Returns:IRubyObject

a Rational based on the object, or nil if it could not be converted

checkToStringback to summary
public static IRubyObject checkToString(ThreadContext context, IRubyObject obj)

Check whether the given object is a String or can be converted to a String using #to_str.

Parameters
context:ThreadContext

the current thread context

obj:IRubyObject

the object to be converted

Returns:IRubyObject

the String value or nil if the object or conversion is not a String.

toByteback to summary
public static byte toByte(ThreadContext context, IRubyObject arg)
toDoubleback to summary
public static double toDouble(ThreadContext context, IRubyObject arg)

Safely convert a Ruby Numeric into a java double value. Raising if the value will not fit.

Parameters
context:ThreadContext

the current thread context

arg:IRubyObject

the Object to convert

Returns:double

the value

toIntback to summary
public static int toInt(ThreadContext context, IRubyObject arg)

Safely convert a Ruby Numeric into a java long value. Raising if the value will not fit.

Parameters
context:ThreadContext

the current thread context

arg:IRubyObject

the RubyNumeric to convert

Returns:int

the int value

toIntback to summary
public static long toInt(ThreadContext context, RubyFloat value)
toIntback to summary
public static int toInt(ThreadContext context, RubyFixnum arg)
toIntegerback to summary
public static RubyInteger toInteger(ThreadContext context, IRubyObject arg)

Safely convert a Ruby Numeric into a java long value. Raising if the value will not fit.

Parameters
context:ThreadContext

the current thread context

arg:IRubyObject

the RubyNumeric to convert

Returns:RubyInteger

the int value

toIntOtherback to summary
private static long toIntOther(ThreadContext context, IRubyObject arg)
toLongback to summary
public static long toLong(ThreadContext context, IRubyObject arg)

Safely convert a Ruby Numeric into a java long value. Raising if the value will not fit.

Parameters
context:ThreadContext

the current thread context

arg:IRubyObject

the RubyNumeric to convert

Returns:long

the value

toLongback to summary
public static long toLong(ThreadContext context, RubyBignum value)
toLongback to summary
public static long toLong(ThreadContext context, RubyFloat value)
toLongOtherback to summary
private static long toLongOther(ThreadContext context, IRubyObject arg)
toSymbolback to summary
public static RubySymbol toSymbol(ThreadContext context, IRubyObject arg)

Convert the given object to a Symbol, possibly calling to_str in the process. MRI: rb_to_symbol

Parameters
context:ThreadContext

the current thread context

arg:IRubyObject

the object to convert to a symbol

Returns:RubySymbol

the new RubySymbol