Class: Symbol

Inherits:
Object show all
Includes:
Comparable
Defined in:
string.c,
string.c

Overview

********************************************************************

A +Symbol+ object represents a named identifier inside the Ruby interpreter.

You can create a +Symbol+ object explicitly with:

- A {symbol literal}[rdoc-ref:syntax/literals.rdoc@Symbol+Literals].

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 <code>Fred</code> is a constant in one context, a method in
another, and a class in a third, the +Symbol+ <code>:Fred</code>
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]

A +Symbol+ object differs from a String object in that
a +Symbol+ object represents an identifier, while a String object
represents text or data.

== What's Here

First, what's elsewhere. \Class +Symbol+:

- Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
- Includes {module Comparable}[rdoc-ref:Comparable@What-27s+Here].

Here, class +Symbol+ provides methods that are useful for:

- {Querying}[rdoc-ref:Symbol@Methods+for+Querying]
- {Comparing}[rdoc-ref:Symbol@Methods+for+Comparing]
- {Converting}[rdoc-ref:Symbol@Methods+for+Converting]

=== Methods for Querying

- ::all_symbols: Returns an array of the symbols currently in Ruby's symbol table.
- #=~: Returns the index of the first substring in symbol that matches a
  given Regexp or other object; returns +nil+ if no match is found.
- #[], #slice : Returns a substring of symbol
  determined by a given index, start/length, or range, or string.
- #empty?: Returns +true+ if +self.length+ is zero; +false+ otherwise.
- #encoding: Returns the Encoding object that represents the encoding
  of symbol.
- #end_with?: Returns +true+ if symbol ends with
  any of the given strings.
- #match: Returns a MatchData object if symbol
  matches a given Regexp; +nil+ otherwise.
- #match?: Returns +true+ if symbol
  matches a given Regexp; +false+ otherwise.
- #length, #size: Returns the number of characters in symbol.
- #start_with?: Returns +true+ if symbol starts with
  any of the given strings.

=== Methods for Comparing

- #<=>: 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.

=== Methods for Converting

- #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.
- #succ, #next: Returns the symbol that is the successor to symbol.
- #swapcase: Returns symbol with all upcase characters downcased
  and all downcase characters upcased.
- #to_proc: Returns a Proc object which responds to the method named by symbol.
- #to_s, #id2name: Returns the string corresponding to +self+.
- #to_sym, #intern: Returns +self+.
- #upcase: Returns symbol with all characters upcased.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #>, #>=, #between?, #clamp

Class Method Details

.all_symbols ⇒ Object

Returns an array of all symbols currently in Ruby’s symbol table:

Symbol.all_symbols.size    # => 9334
Symbol.all_symbols.take(3) # => [:!, :"\"", :"#"]


12494
12495
12496
12497
12498
 
# File 'string.c', line 12494

static VALUE
sym_all_symbols(VALUE _)
{
    return rb_sym_all_symbols();
}

Instance Method Details

#<=>(object) ⇒ -1, ...

If object is a symbol, returns the equivalent of symbol.to_s <=> object.to_s:

:bar <=> :foo # => -1
:foo <=> :foo # => 0
:foo <=> :bar # => 1

Otherwise, returns nil:

:foo <=> 'bar' # => nil

Related: String#<=>.

Returns:

  • (-1, 0, +1, nil) 

12204
12205
12206
12207
12208
12209
12210
12211
 
# File 'string.c', line 12204

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));
}

#== ⇒ Object

#=== ⇒ Object

#=~(object) ⇒ Integer?

Equivalent to symbol.to_s =~ object, including possible updates to global variables; see String#=~.

Returns:


12257
12258
12259
12260
12261
 
# File 'string.c', line 12257

static VALUE
sym_match(VALUE sym, VALUE other)
{
    return rb_str_match(rb_sym2str(sym), other);
}

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp, capture = 0) ⇒ String? #[](substring) ⇒ String?

Equivalent to symbol.to_s[]; see String#[].

Overloads:


12307
12308
12309
12310
12311
 
# File 'string.c', line 12307

static VALUE
sym_aref(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_aref_m(argc, argv, rb_sym2str(sym));
}

#capitalize(*options) ⇒ Object

Equivalent to sym.to_s.capitalize.to_sym.

See String#capitalize.


12384
12385
12386
12387
12388
 
# File 'string.c', line 12384

static VALUE
sym_capitalize(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_capitalize(argc, argv, rb_sym2str(sym)));
}

#casecmp(object) ⇒ -1, ...

:include: doc/symbol/casecmp.rdoc

Returns:

  • (-1, 0, 1, nil) 

12221
12222
12223
12224
12225
12226
12227
12228
 
# File 'string.c', line 12221

static VALUE
sym_casecmp(VALUE sym, VALUE other)
{
    if (!SYMBOL_P(other)) {
        return Qnil;
    }
    return str_casecmp(rb_sym2str(sym), rb_sym2str(other));
}

#casecmp?(object) ⇒ true, ...

:include: doc/symbol/casecmp_p.rdoc

Returns:

  • (true, false, nil) 

12238
12239
12240
12241
12242
12243
12244
12245
 
# File 'string.c', line 12238

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));
}

#downcase(*options) ⇒ Object

Equivalent to sym.to_s.downcase.to_sym.

See String#downcase.

Related: Symbol#upcase.


12368
12369
12370
12371
12372
 
# File 'string.c', line 12368

static VALUE
sym_downcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_downcase(argc, argv, rb_sym2str(sym)));
}

#empty? ⇒ Boolean

Returns true if self is :'', false otherwise.

Returns:

  • (Boolean) 

12334
12335
12336
12337
12338
 
# File 'string.c', line 12334

static VALUE
sym_empty(VALUE sym)
{
    return rb_str_empty(rb_sym2str(sym));
}

#encoding ⇒ Encoding

Equivalent to self.to_s.encoding; see String#encoding.

Returns:


12443
12444
12445
12446
12447
 
# File 'string.c', line 12443

static VALUE
sym_encoding(VALUE sym)
{
    return rb_obj_encoding(rb_sym2str(sym));
}

#end_with?(*strings) ⇒ Boolean

Equivalent to self.to_s.end_with?; see String#end_with?.

Returns:

  • (Boolean) 

12429
12430
12431
12432
12433
 
# File 'string.c', line 12429

static VALUE
sym_end_with(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_end_with(argc, argv, rb_sym2str(sym));
}

#inspect ⇒ String

Returns a string representation of self (including the leading colon):

:foo.inspect # => ":foo"

Related: Symbol#to_s, Symbol#name.

Returns:


12113
12114
12115
12116
12117
12118
12119
12120
12121
12122
12123
12124
12125
12126
12127
12128
12129
12130
12131
12132
12133
12134
12135
12136
12137
12138
12139
12140
12141
12142
12143
12144
12145
12146
12147
 
# File 'string.c', line 12113

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);
        VALUE orig_str = str;

        len = RSTRING_LEN(orig_str);
        str = rb_enc_str_new(0, len + 1, enc);

        // Get data pointer after allocation
        ptr = RSTRING_PTR(orig_str);
        dest = RSTRING_PTR(str);
        memcpy(dest + 1, ptr, len);

        RB_GC_GUARD(orig_str);
    }
    dest[0] = ':';

    RUBY_ASSERT_BUILTIN_TYPE(str, T_STRING);

    return str;
}

#length ⇒ Integer

Equivalent to self.to_s.length; see String#length.

Returns:


12320
12321
12322
12323
12324
 
# File 'string.c', line 12320

static VALUE
sym_length(VALUE sym)
{
    return rb_str_length(rb_sym2str(sym));
}

#match(pattern, offset = 0) ⇒ MatchData? #match(pattern, offset = 0) {|matchdata| ... } ⇒ Object

Equivalent to self.to_s.match, including possible updates to global variables; see String#match.

Overloads:

  • #match(pattern, offset = 0) ⇒ MatchData?

    Returns:

  • #match(pattern, offset = 0) {|matchdata| ... } ⇒ Object

    Yields:

    • (matchdata)

    Returns:


12274
12275
12276
12277
12278
 
# File 'string.c', line 12274

static VALUE
sym_match_m(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_match_m(argc, argv, rb_sym2str(sym));
}

#match?(pattern, offset) ⇒ Boolean

Equivalent to sym.to_s.match?; see String#match.

Returns:

  • (Boolean) 

12289
12290
12291
12292
12293
 
# File 'string.c', line 12289

static VALUE
sym_match_m_p(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_match_m_p(argc, argv, sym);
}

#succ ⇒ Object

Equivalent to self.to_s.succ.to_sym:

:foo.succ # => :fop

Related: String#succ.


12180
12181
12182
12183
12184
 
# File 'string.c', line 12180

static VALUE
sym_succ(VALUE sym)
{
    return rb_str_intern(rb_str_succ(rb_sym2str(sym)));
}

#length ⇒ Integer

Equivalent to self.to_s.length; see String#length.

Returns:


12320
12321
12322
12323
12324
 
# File 'string.c', line 12320

static VALUE
sym_length(VALUE sym)
{
    return rb_str_length(rb_sym2str(sym));
}

#[](index) ⇒ String? #[](start, length) ⇒ String? #[](range) ⇒ String? #[](regexp, capture = 0) ⇒ String? #[](substring) ⇒ String?

Equivalent to symbol.to_s[]; see String#[].

Overloads:


12307
12308
12309
12310
12311
 
# File 'string.c', line 12307

static VALUE
sym_aref(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_aref_m(argc, argv, rb_sym2str(sym));
}

#start_with?(*string_or_regexp) ⇒ Boolean

Equivalent to self.to_s.start_with?; see String#start_with?.

Returns:

  • (Boolean) 

12414
12415
12416
12417
12418
 
# File 'string.c', line 12414

static VALUE
sym_start_with(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_start_with(argc, argv, rb_sym2str(sym));
}

#succ ⇒ Object

Equivalent to self.to_s.succ.to_sym:

:foo.succ # => :fop

Related: String#succ.


12180
12181
12182
12183
12184
 
# File 'string.c', line 12180

static VALUE
sym_succ(VALUE sym)
{
    return rb_str_intern(rb_str_succ(rb_sym2str(sym)));
}

#swapcase(*options) ⇒ Object

Equivalent to sym.to_s.swapcase.to_sym.

See String#swapcase.


12400
12401
12402
12403
12404
 
# File 'string.c', line 12400

static VALUE
sym_swapcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_swapcase(argc, argv, rb_sym2str(sym)));
}

#to_proc ⇒ Object

Returns a Proc object which calls the method with name of self on the first parameter and passes the remaining parameters to the method.

proc = :to_s.to_proc   # => #<Proc:0x000001afe0e48680(&:to_s) (lambda)>
proc.call(1000)        # => "1000"
proc.call(1000, 16)    # => "3e8"
(1..3).collect(&:to_s) # => ["1", "2", "3"]


1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
 
# File 'proc.c', line 1513

VALUE
rb_sym_to_proc(VALUE sym)
{
    static VALUE sym_proc_cache = Qfalse;
    enum {SYM_PROC_CACHE_SIZE = 67};
    VALUE proc;
    long index;
    ID id;

    if (!sym_proc_cache) {
        sym_proc_cache = rb_ary_hidden_new(SYM_PROC_CACHE_SIZE * 2);
        rb_vm_register_global_object(sym_proc_cache);
        rb_ary_store(sym_proc_cache, SYM_PROC_CACHE_SIZE*2 - 1, Qnil);
    }

    id = SYM2ID(sym);
    index = (id % SYM_PROC_CACHE_SIZE) << 1;

    if (RARRAY_AREF(sym_proc_cache, index) == sym) {
        return RARRAY_AREF(sym_proc_cache, index + 1);
    }
    else {
        proc = sym_proc_new(rb_cProc, ID2SYM(id));
        RARRAY_ASET(sym_proc_cache, index, sym);
        RARRAY_ASET(sym_proc_cache, index + 1, proc);
        return proc;
    }
}

#upcase(*options) ⇒ Object

Equivalent to sym.to_s.upcase.to_sym.

See String#upcase.


12350
12351
12352
12353
12354
 
# File 'string.c', line 12350

static VALUE
sym_upcase(int argc, VALUE *argv, VALUE sym)
{
    return rb_str_intern(rb_str_upcase(argc, argv, rb_sym2str(sym)));
}