# class Reference

- Reference
- Object

##
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

- Array(T)
- Benchmark::BM::Job
- Benchmark::BM::Tms
- Benchmark::IPS::Entry
- Benchmark::IPS::Job
- Box(T)
- Channel(T)
- Compress::Gzip::Header
- Compress::Zip::File
- Compress::Zip::File::Entry
- Compress::Zip::Reader
- Compress::Zip::Reader::Entry
- Compress::Zip::Writer
- Compress::Zip::Writer::Entry
- Crypto::Bcrypt
- Crypto::Bcrypt::Password
- Crypto::Blowfish
- Crystal::EventLoop
- Crystal::EventLoop::Polling::Arena(T, BLOCK_BYTESIZE)
- Crystal::EventLoop::Polling::FiberEvent
- Crystal::Macros::ASTNode
- Crystal::SyntaxHighlighter
- CSV
- CSV::Builder
- CSV::Lexer
- CSV::Parser
- Deque(T)
- Digest
- Dir
- Exception
- Fiber
- Fiber::ExecutionContext::Isolated
- Fiber::ExecutionContext::Parallel
- Fiber::ExecutionContext::Parallel::Scheduler
- Hash(K, V)
- HTTP::Client
- HTTP::Client::Response
- HTTP::CompressHandler
- HTTP::Cookie
- HTTP::Cookies
- HTTP::ErrorHandler
- HTTP::FormData::Builder
- HTTP::FormData::Parser
- HTTP::LogHandler
- HTTP::Request
- HTTP::Server
- HTTP::Server::Context
- HTTP::Server::RequestProcessor
- HTTP::StaticFileHandler
- HTTP::WebSocket
- HTTP::WebSocketHandler
- IO
- Iterator::Stop
- JSON::Builder
- JSON::Lexer
- JSON::Parser
- JSON::PullParser
- JSON::Token
- Levenshtein::Finder
- LLVM::ABI
- LLVM::ABI::FunctionType
- LLVM::Builder
- LLVM::Context
- LLVM::FunctionPassManager
- LLVM::GenericValue
- LLVM::JITCompiler
- LLVM::MemoryBuffer
- LLVM::Module
- LLVM::ModulePassManager
- LLVM::Orc::JITDylib
- LLVM::Orc::LLJIT
- LLVM::Orc::LLJITBuilder
- LLVM::Orc::ThreadSafeContext
- LLVM::Orc::ThreadSafeModule
- LLVM::PassBuilderOptions
- LLVM::PassManagerBuilder
- LLVM::TargetMachine
- Log
- Log::AsyncDispatcher
- Log::Backend
- Log::Builder
- Log::EntriesChecker
- Log::Metadata
- Log::SyncDispatcher
- MIME::Multipart::Builder
- MIME::Multipart::Parser
- Mutex
- OAuth2::AccessToken
- OAuth2::Client
- OAuth2::Session
- OAuth::AccessToken
- OAuth::Consumer
- OAuth::RequestToken
- OpenSSL::Cipher
- OpenSSL::HMAC
- OpenSSL::MD5
- OpenSSL::SHA1
- OpenSSL::SSL::Context
- OpenSSL::SSL::Server
- OptionParser
- PrettyPrint
- Process
- Process::Status
- Random::ISAAC
- Random::PCG32
- Regex
- Spec::Context
- Spec::Example
- Steppable::StepIterator(T, L, B)
- String
- StringPool
- StringScanner
- Sync::ConditionVariable
- Sync::Exclusive(T)
- Sync::Mutex
- Sync::RWLock
- Sync::Shared(T)
- System::Group
- System::User
- Thread
- Time::Location
- URI
- URI::Params::Builder
- URI::Punycode
- WaitGroup
- WeakRef(T)
- XML::Attributes
- XML::Builder
- XML::Namespace
- XML::Node
- XML::Reader
- XML::XPathContext
- YAML::Builder
- YAML::Nodes::Builder
- YAML::Nodes::Node
- YAML::ParseContext
- YAML::PullParser

##
Defined in:

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

##
Constructors

- .new
- .unsafe_construct(address : Pointer, *args, **opts) : self

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

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

##
Class Method Summary

- .pre_initialize(address : Pointer)

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

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

##
Instance Method Summary

- #==(other : self)

  Returns `true` if this reference is the same as other.

- #==(other : JSON::Any)
- #==(other : YAML::Any)
- #==(other)

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

- #dup

  Returns a shallow copy of this object.

- #hash(hasher)

  See `Object#hash(hasher)`

- #initialize
- #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.

- #object_id : UInt64

  Returns a `UInt64` that uniquely identifies this object.

- #pretty_print(pp) : Nil
- #same?(other : Reference) : Bool

  Returns `true` if this reference is the same as other.

- #same?(other : Nil)

  Returns `false`: a reference is never `nil`.

- #to_s(io : IO) : Nil

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

### 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 : String | IO, root : String)
from_json(string_or_io : String | 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 #
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.

##
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 buffer of at least `instance_sizeof(self)` bytes with an alignment of `instance_alignof(self)` or above. `ReferenceStorage` fulfils both requirements.

WARNING The caller is responsible for managing the memory at the given address, in particular if the memory is not garbage-collectable.

    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`, `Struct.pre_initialize`.

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

##
Instance Method Detail

def ==(other : self) #

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

def ==(other : JSON::Any) #
def ==(other : YAML::Any) #
def ==(other) #

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

def dup #

Returns a shallow copy of this object.

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

def hash(hasher) #

See `Object#hash(hasher)`

def initialize #
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>

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

def pretty_print(pp) : Nil #
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.

def same?(other : Nil) #

Returns `false`: a reference is never `nil`.

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>