Symbol
objects represent named identifiers inside the Ruby interpreter.
You can create a Symbol object explicitly with:
The same Symbol
object will be created for a given name or string for the duration of a program’s execution, regardless of the context or meaning of that name. Thus if Fred
is a constant in one context, a method in another, and a class in a third, the Symbol
:Fred
will be the same object in all three contexts.
module One class Fred end $f1 = :Fred end module Two Fred = 1 $f2 = :Fred end def Fred() end $f3 = :Fred $f1.object_id #=> 2514190 $f2.object_id #=> 2514190 $f3.object_id #=> 2514190
Constant, method, and variable names are returned as symbols:
module One Two = 2 def three; 3 end @four = 4 @@five = 5 $six = 6 end seven = 7 One.constants # => [:Two] One.instance_methods(true) # => [:three] One.instance_variables # => [:@four] One.class_variables # => [:@@five] global_variables.grep(/six/) # => [:$six] local_variables # => [:seven]
Symbol
objects are different from String
objects in that Symbol
objects represent identifiers, while String
objects represent text or data.
First, what’s elsewhere. Class Symbol:
Inherits from class Object.
Includes module Comparable.
Here, class Symbol provides methods that are useful for:
::all_symbols
Returns an array of the symbols currently in Ruby’s symbol table.
empty?
Returns true
if self.length
is zero; false
otherwise.
end_with?
Returns true
if symbol ends with any of the given strings.
start_with?
Returns true
if symbol starts with any of the given strings.
Returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.
Returns true
if a given symbol has the same content and encoding.
casecmp
Ignoring case, returns -1, 0, or 1 as a given symbol is smaller than, equal to, or larger than symbol.
casecmp?
Returns true
if symbol is equal to a given symbol after Unicode case folding; false
otherwise.
capitalize
Returns symbol with the first character upcased and all other characters downcased.
downcase
Returns symbol with all characters downcased.
inspect
Returns the string representation of self
as a symbol literal.
name
Returns the frozen string corresponding to symbol.
swapcase
Returns symbol with all upcase characters downcased and all downcase characters upcased.
upcase
Returns symbol with all characters upcased.
static VALUE
sym_all_symbols(VALUE _)
{
return rb_sym_all_symbols();
}
Returns an array of all the symbols currently in Ruby’s symbol table.
Symbol.all_symbols.size #=> 903 Symbol.all_symbols[1,20] #=> [:floor, :ARGV, :Binding, :symlink, :chown, :EOFError, :$;, :String, :LOCK_SH, :"setuid?", :$<, :default_proc, :compact, :extend, :Tms, :getwd, :$=, :ThreadGroup, :wait2, :$>]
# File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 22
def self.json_create(o)
o['s'].to_sym
end
static VALUE
sym_cmp(VALUE sym, VALUE other)
{
if (!SYMBOL_P(other)) {
return Qnil;
}
return rb_str_cmp_m(rb_sym2str(sym), rb_sym2str(other));
}
Compares symbol
with other_symbol
after calling to_s
on each of the symbols. Returns -1, 0, +1, or nil
depending on whether symbol
is less than, equal to, or greater than other_symbol
.
nil
is returned if the two values are incomparable.
See String#<=> for more information.
#define sym_equal rb_obj_equal
Equality—If sym and obj are exactly the same symbol, returns true
.
static VALUE
sym_match(VALUE sym, VALUE other)
{
return rb_str_match(rb_sym2str(sym), other);
}
Returns sym.to_s =~ obj
.
static VALUE
sym_aref(int argc, VALUE *argv, VALUE sym)
{
return rb_str_aref_m(argc, argv, rb_sym2str(sym));
}
Returns sym.to_s[]
.
# File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 9
def as_json(*)
{
JSON.create_id => self.class.name,
's' => to_s,
}
end
Returns a hash, that will be turned into a JSON
object and represent this object.
static VALUE
sym_capitalize(int argc, VALUE *argv, VALUE sym)
{
return rb_str_intern(rb_str_capitalize(argc, argv, rb_sym2str(sym)));
}
Equivalent to sym.to_s.capitalize.to_sym
.
See String#capitalize
.
static VALUE
sym_casecmp(VALUE sym, VALUE other)
{
if (!SYMBOL_P(other)) {
return Qnil;
}
return str_casecmp(rb_sym2str(sym), rb_sym2str(other));
}
Case-insensitive version of Symbol#<=>:
:aBcDeF.casecmp(:abcde) # => 1 :aBcDeF.casecmp(:abcdef) # => 0 :aBcDeF.casecmp(:abcdefg) # => -1 :abcdef.casecmp(:ABCDEF) # => 0
Returns nil
if the two symbols have incompatible encodings, or if other_symbol
is not a symbol:
sym = "\u{e4 f6 fc}".encode("ISO-8859-1").to_sym other_sym = :"\u{c4 d6 dc}" sym.casecmp(other_sym) # => nil :foo.casecmp(2) # => nil
Currently, case-insensitivity only works on characters A-Z/a-z, not all of Unicode. This is different from Symbol#casecmp?
.
Related: Symbol#casecmp?
.
static VALUE
sym_casecmp_p(VALUE sym, VALUE other)
{
if (!SYMBOL_P(other)) {
return Qnil;
}
return str_casecmp_p(rb_sym2str(sym), rb_sym2str(other));
}
Returns true
if sym
and other_symbol
are equal after Unicode case folding, false
if they are not equal:
:aBcDeF.casecmp?(:abcde) # => false :aBcDeF.casecmp?(:abcdef) # => true :aBcDeF.casecmp?(:abcdefg) # => false :abcdef.casecmp?(:ABCDEF) # => true :"\u{e4 f6 fc}".casecmp?(:"\u{c4 d6 dc}") #=> true
Returns nil
if the two symbols have incompatible encodings, or if other_symbol
is not a symbol:
sym = "\u{e4 f6 fc}".encode("ISO-8859-1").to_sym other_sym = :"\u{c4 d6 dc}" sym.casecmp?(other_sym) # => nil :foo.casecmp?(2) # => nil
See Case Mapping.
Related: Symbol#casecmp
.
static VALUE
sym_downcase(int argc, VALUE *argv, VALUE sym)
{
return rb_str_intern(rb_str_downcase(argc, argv, rb_sym2str(sym)));
}
static VALUE
sym_empty(VALUE sym)
{
return rb_str_empty(rb_sym2str(sym));
}
Returns whether sym is :“” or not.
static VALUE
sym_encoding(VALUE sym)
{
return rb_obj_encoding(rb_sym2str(sym));
}
Returns the Encoding
object that represents the encoding of sym.
static VALUE
sym_end_with(int argc, VALUE *argv, VALUE sym)
{
return rb_str_end_with(argc, argv, rb_sym2str(sym));
}
Returns true if sym
ends with one of the suffixes
given.
:hello.end_with?("ello") #=> true # returns true if one of the +suffixes+ matches. :hello.end_with?("heaven", "ello") #=> true :hello.end_with?("heaven", "paradise") #=> false
static VALUE
sym_inspect(VALUE sym)
{
VALUE str = rb_sym2str(sym);
const char *ptr;
long len;
char *dest;
if (!rb_str_symname_p(str)) {
str = rb_str_inspect(str);
len = RSTRING_LEN(str);
rb_str_resize(str, len + 1);
dest = RSTRING_PTR(str);
memmove(dest + 1, dest, len);
}
else {
rb_encoding *enc = STR_ENC_GET(str);
RSTRING_GETMEM(str, ptr, len);
str = rb_enc_str_new(0, len + 1, enc);
dest = RSTRING_PTR(str);
memcpy(dest + 1, ptr, len);
}
dest[0] = ':';
return str;
}
Returns the representation of sym as a symbol literal.
:fred.inspect #=> ":fred"
static VALUE
sym_to_sym(VALUE sym)
{
return sym;
}
In general, to_sym
returns the Symbol
corresponding to an object. As sym is already a symbol, self
is returned in this case.
static VALUE
sym_length(VALUE sym)
{
return rb_str_length(rb_sym2str(sym));
}
Same as sym.to_s.length
.
static VALUE
sym_match_m(int argc, VALUE *argv, VALUE sym)
{
return rb_str_match_m(argc, argv, rb_sym2str(sym));
}
Returns sym.to_s.match
.
static VALUE
sym_match_m_p(int argc, VALUE *argv, VALUE sym)
{
return rb_str_match_m_p(argc, argv, sym);
}
Returns sym.to_s.match?
.
VALUE
rb_sym2str(VALUE sym)
{
}
Returns the name or string corresponding to sym. Unlike to_s
, the returned string is frozen.
:fred.name #=> "fred" :fred.name.frozen? #=> true :fred.to_s #=> "fred" :fred.to_s.frozen? #=> false
static VALUE
sym_start_with(int argc, VALUE *argv, VALUE sym)
{
return rb_str_start_with(argc, argv, rb_sym2str(sym));
}
Returns true if sym
starts with one of the prefixes
given. Each of the prefixes
should be a String
or a Regexp
.
:hello.start_with?("hell") #=> true :hello.start_with?(/H/i) #=> true # returns true if one of the prefixes matches. :hello.start_with?("heaven", "hell") #=> true :hello.start_with?("heaven", "paradise") #=> false
static VALUE
sym_succ(VALUE sym)
{
return rb_str_intern(rb_str_succ(rb_sym2str(sym)));
}
Same as sym.to_s.succ.intern
.
static VALUE
sym_swapcase(int argc, VALUE *argv, VALUE sym)
{
return rb_str_intern(rb_str_swapcase(argc, argv, rb_sym2str(sym)));
}
Equivalent to sym.to_s.swapcase.to_sym
.
See String#swapcase
.
# File tmp/rubies/ruby-3.1.2/ext/json/lib/json/add/symbol.rb, line 17
def to_json(*a)
as_json.to_json(*a)
end
VALUE
rb_sym_to_proc(VALUE sym)
{
}
Returns a Proc object which responds to the given method by sym.
(1..3).collect(&:to_s) #=> ["1", "2", "3"]
VALUE
rb_sym_to_s(VALUE sym)
{
return str_new_shared(rb_cString, rb_sym2str(sym));
}
Returns the name or string corresponding to sym.
:fred.id2name #=> "fred" :ginger.to_s #=> "ginger"
Note that this string is not frozen (unlike the symbol itself). To get a frozen string, use name
.
static VALUE
sym_upcase(int argc, VALUE *argv, VALUE sym)
{
return rb_str_intern(rb_str_upcase(argc, argv, rb_sym2str(sym)));
}
Equivalent to sym.to_s.upcase.to_sym
.
See String#upcase
.