Ruby: include/ruby/internal/intern/array.h File Reference

Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)

Macros | Functions
array.h File Reference

Public APIs related to rb_cArray. More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Macros
#define | rb_ary_new2 rb_ary_new_capa
#define | rb_ary_new3 rb_ary_new_from_args
#define | rb_ary_new4 rb_ary_new_from_values

## Functions
void | rb_mem_clear (VALUE *, long)
VALUE | rb_assoc_new (VALUE, VALUE)
VALUE | rb_check_array_type (VALUE)
VALUE | rb_ary_new (void)
VALUE | rb_ary_new_capa (long capa)
VALUE | rb_ary_new_from_args (long n,...)
VALUE | rb_ary_new_from_values (long n, const VALUE *elts)
VALUE | rb_ary_tmp_new (long)
void | rb_ary_free (VALUE)
void | rb_ary_modify (VALUE)
VALUE | rb_ary_freeze (VALUE)
VALUE | rb_ary_shared_with_p (VALUE, VALUE)
VALUE | rb_ary_aref (int, const VALUE *, VALUE)
VALUE | rb_ary_subseq (VALUE, long, long)
void | rb_ary_store (VALUE, long, VALUE)
VALUE | rb_ary_dup (VALUE)
VALUE | rb_ary_resurrect (VALUE ary)
VALUE | rb_ary_to_ary (VALUE)
VALUE | rb_ary_to_s (VALUE)
VALUE | rb_ary_cat (VALUE, const VALUE *, long)
VALUE | rb_ary_push (VALUE, VALUE)
VALUE | rb_ary_pop (VALUE)
VALUE | rb_ary_shift (VALUE)
VALUE | rb_ary_unshift (VALUE, VALUE)
VALUE | rb_ary_entry (VALUE, long)
VALUE | rb_ary_each (VALUE)
VALUE | rb_ary_join (VALUE, VALUE)
VALUE | rb_ary_reverse (VALUE)
VALUE | rb_ary_rotate (VALUE, long)
VALUE | rb_ary_sort (VALUE)
VALUE | rb_ary_sort_bang (VALUE)
VALUE | rb_ary_delete (VALUE, VALUE)
VALUE | rb_ary_delete_at (VALUE, long)
VALUE | rb_ary_clear (VALUE)
VALUE | rb_ary_plus (VALUE, VALUE)
VALUE | rb_ary_concat (VALUE, VALUE)
VALUE | rb_ary_assoc (VALUE, VALUE)
VALUE | rb_ary_rassoc (VALUE, VALUE)
VALUE | rb_ary_includes (VALUE, VALUE)
VALUE | rb_ary_cmp (VALUE, VALUE)
VALUE | rb_ary_replace (VALUE copy, VALUE orig)
VALUE | rb_get_values_at (VALUE, long, int, const VALUE *, VALUE(*)(VALUE, long))
VALUE | rb_ary_resize (VALUE ary, long len)
| expands or shrinks ary to len elements. More...

## Detailed Description

Public APIs related to rb_cArray.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file array.h.

## Macro Definition Documentation

## ◆ rb_ary_new2

#define rb_ary_new2 rb_ary_new_capa

Definition at line 72 of file array.h.

## ◆ rb_ary_new3

#define rb_ary_new3 rb_ary_new_from_args

Definition at line 73 of file array.h.

## ◆ rb_ary_new4

#define rb_ary_new4 rb_ary_new_from_values

Definition at line 74 of file array.h.

## Function Documentation

## ◆ rb_ary_aref()

VALUE rb_ary_aref | ( | int | argc,
|  | const VALUE * | argv,
|  | VALUE | ary
| ) |  |

Definition at line 1802 of file array.c.

References argc, argv, rb_ary_aref1(), and rb_check_arity.

Referenced by Init_Array().

## ◆ rb_ary_assoc()

VALUE rb_ary_assoc | ( | VALUE | ary,
|  | VALUE | key
| ) |  |

Definition at line 4938 of file array.c.

References select_bang_arg::ary, key, NIL_P, Qnil, RARRAY_AREF, RARRAY_LEN, rb_check_array_type(), and rb_equal().

Referenced by Init_Array().

## ◆ rb_ary_cat()

VALUE rb_ary_cat | ( | VALUE | ary,
|  | const VALUE * | argv,
|  | long | len
| ) |  |

Definition at line 1314 of file array.c.

References argv, ARY_SET_LEN, len, and RARRAY_LEN.

Referenced by rb_mod_init_copy().

## ◆ rb_ary_clear()

VALUE rb_ary_clear | ( | VALUE | ary | ) |

Definition at line 4534 of file array.c.

References select_bang_arg::ary, ARY_CAPA, ARY_DEFAULT_SIZE, ARY_EMBED_P, ARY_SET_EMBED_LEN, ARY_SET_LEN, ARY_SHARED_P, ary_verify, and FL_SET_EMBED.

Referenced by Init_Array(), rb_threadptr_pending_interrupt_clear(), and ruby_set_argv().

## ◆ rb_ary_cmp()

VALUE rb_ary_cmp | ( | VALUE | ary1,
|  | VALUE | ary2
| ) |  |

Definition at line 5198 of file array.c.

References INT2FIX, len, NIL_P, Qnil, Qundef, RARRAY_LEN, rb_check_array_type(), and rb_exec_recursive_paired().

Referenced by Init_Array().

## ◆ rb_ary_concat()

VALUE rb_ary_concat | ( | VALUE | x,
|  | VALUE | y
| ) |  |

Definition at line 4859 of file array.c.

References to_ary.

Referenced by yyparse().

## ◆ rb_ary_delete()

VALUE rb_ary_delete | ( | VALUE | ary,
|  | VALUE | item
| ) |  |

Definition at line 3956 of file array.c.

References select_bang_arg::ary, ary_verify, Qnil, RARRAY_AREF, RARRAY_LEN, rb_ary_store(), rb_block_given_p(), rb_equal(), and rb_yield().

Referenced by Init_Array().

## ◆ rb_ary_delete_at()

VALUE rb_ary_delete_at | ( | VALUE | ary,
|  | long | pos
| ) |  |

Definition at line 4010 of file array.c.

References select_bang_arg::ary, ARY_INCREASE_LEN, ary_verify, len, MEMMOVE, ptr, Qnil, RARRAY_AREF, RARRAY_LEN, RARRAY_PTR_USE_TRANSIENT, and rb_ary_modify().

## ◆ rb_ary_dup()

VALUE rb_ary_dup | ( | VALUE | ary | ) |

Definition at line 2666 of file array.c.

References ARY_SET_LEN, ary_verify, len, RARRAY_CONST_PTR_TRANSIENT, RARRAY_LEN, and rb_ary_new2.

Referenced by rb_ary_sort().

## ◆ rb_ary_each()

VALUE rb_ary_each | ( | VALUE | ary | ) |

Definition at line 2517 of file array.c.

References ary_verify, RARRAY_AREF, RARRAY_LEN, rb_yield(), and RETURN_SIZED_ENUMERATOR.

Referenced by Init_Array().

## ◆ rb_ary_entry()

VALUE rb_ary_entry | ( | VALUE | ary,
|  | long | offset
| ) |  |

Definition at line 1672 of file array.c.

Referenced by EVENTSINK_Invoke(), rb_ary_aref1(), rb_ary_at(), rb_debug_inspector_frame_binding_get(), rb_debug_inspector_frame_class_get(), rb_debug_inspector_frame_iseq_get(), rb_debug_inspector_frame_self_get(), rb_error_frozen_object(), and rb_resolve_me_location().

## ◆ rb_ary_free()

void rb_ary_free | ( | VALUE | ary | ) |

Definition at line 864 of file array.c.

References ARY_HEAP_CAPA, ARY_OWNS_HEAP_P, ARY_SHARED_P, ARY_SHARED_ROOT_OCCUPIED, ARY_SHARED_ROOT_P, RARRAY_LEN, RB_DEBUG_COUNTER_INC, and USE_DEBUG_COUNTER.

## ◆ rb_ary_freeze()

VALUE rb_ary_freeze | ( | VALUE | ary | ) |

Definition at line 674 of file array.c.

References rb_obj_freeze().

Referenced by rb_method_definition_set().

## ◆ rb_ary_includes()

VALUE rb_ary_includes | ( | VALUE | ary,
|  | VALUE | item
| ) |  |

Definition at line 5126 of file array.c.

References select_bang_arg::ary, Qfalse, Qtrue, RARRAY_AREF, RARRAY_LEN, and rb_equal().

Referenced by Init_Array().

## ◆ rb_ary_join()

VALUE rb_ary_join | ( | VALUE | ary,
|  | VALUE | sep
| ) |  |

Definition at line 2780 of file array.c.

References len, NIL_P, RARRAY_AREF, RARRAY_LEN, rb_check_string_type(), rb_enc_associate(), rb_str_buf_new(), rb_str_new, rb_str_set_len(), rb_usascii_encoding(), rb_usascii_str_new, RSTRING_LEN, and StringValue.

Referenced by rb_insn_operand_intern(), rb_proc_isolate_bang(), and rb_proc_ractor_make_shareable().

## ◆ rb_ary_modify()

void rb_ary_modify | ( | VALUE | ary | ) |

Definition at line 606 of file array.c.

References rb_ary_cancel_sharing().

Referenced by rb_ary_delete_at(), rb_ary_resize(), rb_ary_reverse(), rb_ary_rotate(), rb_ary_sort_bang(), and rb_ary_store().

## ◆ rb_ary_new()

VALUE rb_ary_new | ( | void |  | ) |

Definition at line 749 of file array.c.

References RARRAY_EMBED_LEN_MAX, and rb_ary_new2.

Referenced by EVENTSINK_Invoke(), Init_Encoding(), Init_GC(), Init_load(), Init_ossl_asn1(), Init_VM(), Init_win32ole(), Init_win32ole_event(), ole_methods_from_typeinfo(), ole_variant2val(), ossl_get_errors(), rb_call_end_proc(), rb_f_global_variables(), rb_f_untrace_var(), rb_insn_operand_intern(), rb_memory_view_extract_item_members(), rb_mod_ancestors(), rb_mod_included_modules(), rb_obj_instance_variables(), and rb_ractor_thread_list().

## ◆ rb_ary_new_capa()

VALUE rb_ary_new_capa | ( | long | capa | ) |

Definition at line 743 of file array.c.

References rb_cArray.

Referenced by rb_hash_keys(), rb_hash_values(), and rb_insns_name_array().

## ◆ rb_ary_new_from_args()

VALUE rb_ary_new_from_args | ( | long | n,
|  |  | ...
| ) |  |

Definition at line 754 of file array.c.

References ARY_SET_LEN, and rb_ary_new2.

## ◆ rb_ary_new_from_values()

VALUE rb_ary_new_from_values | ( | long | n,
|  | const VALUE * | elts
| ) |  |

Definition at line 788 of file array.c.

References rb_ary_tmp_new_from_values(), and rb_cArray.

Referenced by rb_insn_operand_intern().

## ◆ rb_ary_plus()

VALUE rb_ary_plus | ( | VALUE | x,
|  | VALUE | y
| ) |  |

Definition at line 4800 of file array.c.

References ARY_SET_LEN, len, RARRAY_CONST_PTR_TRANSIENT, RARRAY_LEN, rb_ary_new2, and to_ary.

Referenced by Init_Array().

## ◆ rb_ary_pop()

VALUE rb_ary_pop | ( | VALUE | ary | ) |

Definition at line 1350 of file array.c.

References ARY_CAPA, ARY_DEFAULT_SIZE, ARY_OWNS_HEAP_P, ARY_SET_LEN, ary_verify, Qnil, RARRAY_AREF, and RARRAY_LEN.

## ◆ rb_ary_push()

VALUE rb_ary_push | ( | VALUE | ary,
|  | VALUE | item
| ) |  |

Definition at line 1301 of file array.c.

References ARY_SET_LEN, ary_verify, ptr, RARRAY_LEN, RARRAY_PTR_USE_TRANSIENT, and RB_OBJ_WRITE.

Referenced by EVENTSINK_Invoke(), Init_Array(), Init_Encoding(), Init_VM(), ole_typedesc2val(), ossl_get_errors(), rb_f_global_variables(), rb_f_untrace_var(), rb_gc_register_mark_object(), rb_get_kwargs(), rb_get_values_at(), rb_hash_values_at(), rb_insn_operand_intern(), rb_insns_name_array(), rb_iseq_parameters(), rb_memory_view_extract_item_members(), rb_mod_ancestors(), rb_mod_included_modules(), rb_ractor_thread_list(), rb_threadptr_pending_interrupt_enque(), rb_uninterruptible(), rb_unnamed_parameters(), ruby_init_loadpath(), ruby_set_argv(), and yyparse().

## ◆ rb_ary_rassoc()

VALUE rb_ary_rassoc | ( | VALUE | ary,
|  | VALUE | value
| ) |  |

Definition at line 4967 of file array.c.

References select_bang_arg::ary, Qnil, RARRAY_AREF, RARRAY_LEN, rb_equal(), and T_ARRAY.

Referenced by Init_Array().

## ◆ rb_ary_replace()

VALUE rb_ary_replace | ( | VALUE | copy,
|  | VALUE | orig
| ) |  |

Definition at line 4484 of file array.c.

References ARY_HEAP_LEN, ARY_HEAP_PTR, ARY_OWNS_HEAP_P, ARY_SET_LEN, ARY_SET_PTR, ARY_SHARED_P, ARY_SHARED_ROOT, ary_verify, FL_SET_EMBED, FL_UNSET_EMBED, FL_UNSET_SHARED, RARRAY_CONST_PTR_TRANSIENT, RARRAY_EMBED_LEN_MAX, RARRAY_LEN, and to_ary.

Referenced by Init_Array().

## ◆ rb_ary_resize()

VALUE rb_ary_resize | ( | VALUE | ary,
|  | long | len
| ) |  |

expands or shrinks ary to len elements.

expanded region will be filled with Qnil.

Parameters

  ary | an array
  len | new size

Returns
  ary

Postcondition
  the size of ary is len.

Definition at line 2235 of file array.c.

References ARY_CAPA, ARY_DEFAULT_SIZE, ARY_EMBED_P, ARY_EMBED_PTR, ARY_HEAP_PTR, ARY_MAX_SIZE, ARY_SET_CAPA, ARY_SET_EMBED_LEN, ARY_SET_HEAP_LEN, ARY_SET_LEN, ary_verify, len, MEMCPY, RARRAY_EMBED_LEN_MAX, RARRAY_LEN, rb_ary_modify(), rb_eIndexError, and rb_raise().

Referenced by rb_get_values_at(), rb_mod_init_copy(), and rb_nmin_run().

## ◆ rb_ary_resurrect()

VALUE rb_ary_resurrect | ( | VALUE | ary | ) |

Definition at line 2679 of file array.c.

References RARRAY_LEN, and rb_cArray.

## ◆ rb_ary_reverse()

VALUE rb_ary_reverse | ( | VALUE | ary | ) |

Definition at line 2998 of file array.c.

References len, RARRAY_LEN, RARRAY_PTR_USE_TRANSIENT, and rb_ary_modify().

Referenced by rb_nmin_run().

## ◆ rb_ary_rotate()

VALUE rb_ary_rotate | ( | VALUE | ary,
|  | long | cnt
| ) |  |

Definition at line 3079 of file array.c.

References cnt, len, ptr, Qnil, RARRAY_LEN, RARRAY_PTR_USE_TRANSIENT, and rb_ary_modify().

## ◆ rb_ary_shared_with_p()

VALUE rb_ary_shared_with_p | ( | VALUE | ary1,
|  | VALUE | ary2
| ) |  |

Definition at line 687 of file array.c.

References ARY_EMBED_P, ARY_SHARED_P, Qfalse, Qtrue, and RARRAY.

Referenced by rb_get_expanded_load_path().

## ◆ rb_ary_shift()

VALUE rb_ary_shift | ( | VALUE | ary | ) |

Definition at line 1413 of file array.c.

References ARY_DEFAULT_SIZE, ARY_EMBED_P, ARY_INCREASE_LEN, ARY_INCREASE_PTR, ARY_SHARED_P, ARY_SHARED_ROOT, ARY_SHARED_ROOT_OCCUPIED, ary_verify, assert, len, MEMMOVE, ptr, Qnil, RARRAY_AREF, RARRAY_LEN, RARRAY_PTR_USE_TRANSIENT, and top.

## ◆ rb_ary_sort()

VALUE rb_ary_sort | ( | VALUE | ary | ) |

Definition at line 3396 of file array.c.

References ary_sort_data::ary, rb_ary_dup(), and rb_ary_sort_bang().

Referenced by Init_Array().

## ◆ rb_ary_sort_bang()

VALUE rb_ary_sort_bang | ( | VALUE | ary | ) |

Definition at line 3298 of file array.c.

References ary_sort_data::ary, ARY_EMBED_LEN, ARY_EMBED_P, ARY_EMBED_PTR, ARY_HEAP_LEN, ARY_HEAP_PTR, ARY_SET_CAPA, ARY_SET_EMBED_LEN, ARY_SET_HEAP_LEN, ARY_SET_LEN, ARY_SET_PTR, ARY_SHARED_P, ary_verify, assert, ary_sort_data::cmp_opt, FL_FREEZE, FL_SET, FL_SET_EMBED, FL_UNSET, FL_UNSET_EMBED, FL_UNSET_SHARED, len, cmp_opt_data::opt_inited, cmp_opt_data::opt_methods, ptr, RARRAY_LEN, RARRAY_PTR_USE, rb_ary_modify(), rb_block_given_p(), rb_cArray, and ruby_qsort().

Referenced by Init_Array(), and rb_ary_sort().

## ◆ rb_ary_store()

void rb_ary_store | ( | VALUE | ary,
|  | long | idx,
|  | VALUE | val
| ) |  |

Definition at line 1141 of file array.c.

References ARY_CAPA, ARY_MAX_SIZE, ARY_SET_LEN, len, RARRAY_LEN, rb_ary_modify(), rb_eIndexError, and rb_raise().

Referenced by Init_ossl_asn1(), ossl_generate_cb_2(), rb_ary_delete(), rb_ary_delete_same(), rb_sym_to_proc(), and rb_unnamed_parameters().

## ◆ rb_ary_subseq()

VALUE rb_ary_subseq | ( | VALUE | ary,
|  | long | beg,
|  | long | len
| ) |  |

Definition at line 1700 of file array.c.

References len, and rb_ary_subseq_step().

## ◆ rb_ary_tmp_new()

VALUE rb_ary_tmp_new | ( | long | capa | ) |

Definition at line 846 of file array.c.

References rb_ary_transient_heap_evacuate, and TRUE.

Referenced by Init_load(), Init_sym(), Init_Thread(), Init_vm_objects(), rb_default_coverage(), rb_gc_register_mark_object(), rb_get_kwargs(), rb_mod_init_copy(), rb_nmin_run(), rb_struct_new(), and rb_sym_to_proc().

## ◆ rb_ary_to_ary()

VALUE rb_ary_to_ary | ( | VALUE | obj | ) |

Definition at line 2133 of file array.c.

References NIL_P, rb_ary_new3, and rb_check_array_type().

## ◆ rb_ary_to_s()

VALUE rb_ary_to_s | ( | VALUE | ary | ) |

Definition at line 2894 of file array.c.

## ◆ rb_ary_unshift()

VALUE rb_ary_unshift | ( | VALUE | ary,
|  | VALUE | item
| ) |  |

Definition at line 1654 of file array.c.

## ◆ rb_assoc_new()

VALUE rb_assoc_new | ( | VALUE | car,
|  | VALUE | cdr
| ) |  |

Definition at line 975 of file array.c.

References rb_ary_new3.

Referenced by rb_big_divmod(), rb_big_divrem_normal(), rb_gcdlcm(), rb_hash_assoc(), rsock_s_recvfrom(), rsock_s_recvfrom_nonblock(), and yyparse().

## ◆ rb_check_array_type()

VALUE rb_check_array_type | ( | VALUE | ary | ) |

Definition at line 988 of file array.c.

References rb_check_convert_type_with_id(), and T_ARRAY.

Referenced by rb_Array(), rb_ary_assoc(), rb_ary_cmp(), rb_ary_to_ary(), rb_hash_set_pair(), rb_io_popen(), rb_yield_splat(), and rb_yield_splat_kw().

## ◆ rb_get_values_at()

VALUE rb_get_values_at | ( | VALUE | obj,
|  | long | olen,
|  | int | argc,
|  | const VALUE * | argv,
|  | VALUE(*)(VALUE, long) | func
| ) |  |

Definition at line 3673 of file array.c.

References argc, argv, FIX2LONG, FIXNUM_P, len, NUM2LONG, RARRAY_LEN, rb_ary_new2, rb_ary_push(), rb_ary_resize(), and rb_range_beg_len().

## ◆ rb_mem_clear()

void rb_mem_clear | ( | VALUE * | mem,
|  | long | size
| ) |  |

Definition at line 260 of file array.c.

References Qnil.