Package org.jruby.api

Class Convert

java.lang.Object
org.jruby.api.Convert
public class Convert extends Object

Conversion utilities.

There are 3 mechanisms for converting between types: *

  • type#getValue() where we know exactly what it is and we will be responsible for how it is used
  • `as` where we know it is the thing but we will not care about truncation or range issues
  • `to` where we do not know but hope it is the thing OR we know but need to check range

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 Details

    • Convert

      public Convert()

  • Method Details

    • castAsArray

      public static RubyArray 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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyArray

    • castAsArray

      public static RubyArray 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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyArray

    • castAsBignum

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyBignum

    • castAsClass

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyClass

    • castAsFile

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyFile

    • castAsFixnum

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyFixnum

    • castAsFixnum

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyFixnum

    • castAsHash

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyHash

    • castAsHash

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyHash

    • castAsInteger

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyInteger

    • castAsInteger

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyInteger

    • castAsModule

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyModule

    • castAsModule

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyModule

    • castAsNumeric

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyNumeric

    • castAsProc

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyProc

    • castAsProc

      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 - the current thread context
      newValue - the value to cast
      message - the message to include in the type error
      Returns:
      the value as a RubyProc

    • castAsRange

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyRange

    • castAsString

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubyString

    • castAsSymbol

      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 - the current thread context
      newValue - the value to cast
      Returns:
      the value as a RubySymbol

    • checkToInteger

      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 - the current thread context
      obj - the object to be converted
      Returns:
      the integer value or nil if the object or conversion is not an Integer.

    • checkToRational

      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 - the current thread context
      obj - the object to convert
      Returns:
      a Rational based on the object, or nil if it could not be converted

    • checkToString

      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 - the current thread context
      obj - the object to be converted
      Returns:
      the String value or nil if the object or conversion is not a String.

    • checkInt

      public static int checkInt(ThreadContext context, long num)
      Check to make sure the long num given will fit into an int.
      Parameters:
      context - the current thread context
      num - the long to check
      Returns:
      the int value

    • asBoolean

      public static RubyBoolean asBoolean(ThreadContext context, boolean value)
      Create a Ruby Boolean from a java boolean.
      Parameters:
      context - the current thread context
      value - the boolean value
      Returns:
      the Ruby Boolean

    • asFixnum

      public static RubyFixnum asFixnum(ThreadContext context, long value)
      Create a Ruby Fixnum from a java long.
      Parameters:
      context - the current thread context
      value - the long value
      Returns:
      the Ruby Fixnum

    • asFixnum

      public static RubyFixnum asFixnum(ThreadContext context, int value)
      Create a Ruby Fixnum from a java int.
      Parameters:
      context - the current thread context
      value - the int value
      Returns:
      the Ruby Fixnum

    • asFloat

      public static RubyFloat asFloat(ThreadContext context, double value)
      Create a Ruby Float from a java double.
      Parameters:
      context - the current thread context
      value - the double value
      Returns:
      the Ruby Float

    • asFloat

      public static RubyFloat asFloat(ThreadContext context, long value)
      Create a Ruby Float from a java long.
      Parameters:
      context - the current thread context
      value - the long value
      Returns:
      the Ruby Float

    • asInteger

      public static RubyInteger asInteger(ThreadContext context, double value)
      Create some type of Ruby Integer from a java double
      Parameters:
      context - the current thread context
      value - the double value
      Returns:
      the result

    • toByte

      public static byte toByte(ThreadContext context, IRubyObject arg)

    • toDouble

      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 - the current thread context
      arg - the Object to convert
      Returns:
      the value

    • toLong

      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 - the current thread context
      arg - the RubyNumeric to convert
      Returns:
      the value

    • toLong

      public static long toLong(ThreadContext context, RubyBignum value)

    • toLong

      public static long toLong(ThreadContext context, RubyFloat value)

    • toInt

      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 - the current thread context
      arg - the RubyNumeric to convert
      Returns:
      the int value

    • toInt

      public static long toInt(ThreadContext context, RubyFloat value)

    • toInt

      public static int toInt(ThreadContext context, RubyFixnum arg)

    • toInteger

      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 - the current thread context
      arg - the RubyNumeric to convert
      Returns:
      the int value

    • asSymbol

      public static RubySymbol asSymbol(ThreadContext context, String string)
      Creates a new RubySymbol from the provided java String.
      Parameters:
      context - the current thread context
      string - the contents to become a symbol
      Returns:
      the new RubyString

    • asSymbol

      public static RubySymbol asSymbol(ThreadContext context, ByteList bytelist)
      Creates a new RubySymbol from the provided java String.
      Parameters:
      context - the current thread context
      bytelist - the contents to become a symbol
      Returns:
      the new RubyString

    • asSymbol

      public static RubySymbol asSymbol(ThreadContext context, RubyString string)
      Creates a new RubySymbol from the provided java String.
      Parameters:
      context - the current thread context
      string - the contents to become a symbol
      Returns:
      the new RubySymbol

    • toSymbol

      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 - the current thread context
      arg - the object to convert to a symbol
      Returns:
      the new RubySymbol