class Reference

Overview

Reference is the base class of classes you define in your program. It is set as a class' superclass when you don't specify one:

class MyClass # < Reference
end

A reference type is passed by reference: when you pass it to methods, return it from methods or assign it to variables, a pointer is actually passed.

Invoking .new on a Reference allocates a new instance on the heap. The instance's memory is automatically freed (garbage-collected) when the instance is no longer referred by any other entity in the program.

Direct Known Subclasses

Defined in:

json/any.cr
primitives.cr
reference.cr
yaml/any.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Object

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

Macros inherited from class Object

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

Constructor Detail

def self.new #

[View source]
def self.unsafe_construct(address : Pointer, *args, **opts) : self #

Constructs an object in-place at the given address, forwarding args and opts to #initialize. Returns that object.

This method can be used to decouple object allocation from initialization. For example, the instance data might come from a custom allocator, or it might reside on the stack using a type like ReferenceStorage.

address must point to a suitably aligned buffer of at least instance_sizeof(self) bytes.

WARNING This method is unsafe, as it assumes the caller is responsible for managing the memory at the given address manually.

class Foo
  getter i : Int64
  getter str = "abc"

  def initialize(@i)
  end

  def finalize
    puts "bye"
  end
end

foo_buffer = uninitialized ReferenceStorage(Foo)
foo = Foo.unsafe_construct(pointerof(foo_buffer), 123_i64)
begin
  foo # => #<Foo:0x... @i=123, @str="abc">
ensure
  foo.finalize if foo.responds_to?(:finalize) # prints "bye"
end

See also: Reference.pre_initialize.

EXPERIMENTAL This API is still under development. Join the discussion about custom reference allocation at #13481.


[View source]

Class Method Detail

def self.pre_initialize(address : Pointer) #

Performs basic initialization so that the given address is ready for use as an object's instance data. Returns address cast to self's type.

More specifically, this is the part of object initialization that occurs after memory allocation and before calling one of the #initialize overloads. It zeroes the memory, sets up the type ID (necessary for dynamic dispatch), and then runs all inline instance variable initializers.

address must point to a suitably aligned buffer of at least instance_sizeof(self) bytes.

WARNING This method is unsafe, as it assumes the caller is responsible for managing the memory at the given address manually.

class Foo
  getter i : Int64
  getter str = "abc"

  def initialize(@i)
  end

  def self.alloc_with_libc(i : Int64)
    foo_buffer = LibC.malloc(instance_sizeof(Foo))
    foo = Foo.pre_initialize(foo_buffer)
    foo.i                  # => 0
    foo.str                # => "abc"
    (foo || "").is_a?(Foo) # => true

    foo.initialize(i) # okay
    foo
  end
end

foo = Foo.alloc_with_libc(123_i64)
foo.i # => 123

See also: Reference.unsafe_construct.

EXPERIMENTAL This API is still under development. Join the discussion about custom reference allocation at #13481.


[View source]

Instance Method Detail

def ==(other : self) #

Returns true if this reference is the same as other. Invokes #same?.


[View source]
def ==(other : JSON::Any) #

[View source]
def ==(other : YAML::Any) #

[View source]
def ==(other) #

Returns false (other can only be a Value here).


[View source]
def dup #

Returns a shallow copy of this object.

This allocates a new object and copies the contents of self into it.


[View source]
def hash(hasher) #

See Object#hash(hasher)


[View source]
def initialize #

[View source]
def inspect(io : IO) : Nil #

Appends a String representation of this object which includes its class name, its object address and the values of all instance variables.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).inspect # => #<Person:0x10fd31f20 @name="John", @age=32>

[View source]
def object_id : UInt64 #

Returns a UInt64 that uniquely identifies this object.

The returned value is the memory address of this object.

string = "hello"
string.object_id # => 4460249568

pointer = Pointer(String).new(string.object_id)
string2 = pointer.as(String)
string2.object_id == string.object_id # => true

[View source]
def pretty_print(pp) : Nil #

[View source]
def same?(other : Reference) : Bool #

Returns true if this reference is the same as other. This is only true if this reference's #object_id is the same as other's.


[View source]
def same?(other : Nil) #

Returns false: a reference is never nil.


[View source]
def to_s(io : IO) : Nil #

Appends a short String representation of this object which includes its class name and its object address.

class Person
  def initialize(@name : String, @age : Int32)
  end
end

Person.new("John", 32).to_s # => #<Person:0x10a199f20>

[View source]