Method: Array#sample

Defined in:

array.c

#sample ⇒ Object #sample(random: rng) ⇒ Object #sample(n) ⇒ Array #sample(n, random: rng) ⇒ Array

Choose a random element or n random elements from the array.

The elements are chosen by using random and unique indices into the array in order to ensure that an element doesn’t repeat itself unless the array already contained duplicate elements.

If the array is empty the first form returns nil and the second form returns an empty array.

a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
a.sample         #=> 7
a.sample(4)      #=> [6, 4, 2, 5]

The optional rng argument will be used as the random number generator.

a.sample(random: Random.new(1))     #=> 6
a.sample(4, random: Random.new(1))  #=> [6, 10, 9, 2]

Overloads:

• #sample ⇒ Object

  Returns:

  • (Object)
• #sample(random: rng) ⇒ Object

  Returns:

  • (Object)
• #sample(n) ⇒ Array

  Returns:

  • (Array)
• #sample(n, random: rng) ⇒ Array

  Returns:

  • (Array)

# File 'array.c', line 5423

static VALUE
rb_ary_sample(int argc, VALUE *argv, VALUE ary)
{
    VALUE nv, result;
    VALUE opts, randgen = rb_cRandom;
    long n, len, i, j, k, idx[10];
    long rnds[numberof(idx)];
    long memo_threshold;

    if (OPTHASH_GIVEN_P(opts)) {
	VALUE rnd;
	ID keyword_ids[1];

	keyword_ids[0] = id_random;
	rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
	if (rnd != Qundef) {
	    randgen = rnd;
	}
    }
    len = RARRAY_LEN(ary);
    if (rb_check_arity(argc, 0, 1) == 0) {
	if (len < 2)
	    i = 0;
	else
	    i = RAND_UPTO(len);

	return rb_ary_elt(ary, i);
    }
    nv = argv[0];
    n = NUM2LONG(nv);
    if (n < 0) rb_raise(rb_eArgError, "negative sample number");
    if (n > len) n = len;
    if (n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    rnds[i] = RAND_UPTO(len - i);
	}
    }
    k = len;
    len = RARRAY_LEN(ary);
    if (len < k && n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    if (rnds[i] >= len) return rb_ary_new_capa(0);
	}
    }
    if (n > len) n = len;
    switch (n) {
      case 0:
	return rb_ary_new_capa(0);
      case 1:
	i = rnds[0];
	return rb_ary_new_from_values(1, &RARRAY_AREF(ary, i));
      case 2:
	i = rnds[0];
	j = rnds[1];
	if (j >= i) j++;
	return rb_ary_new_from_args(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j));
      case 3:
	i = rnds[0];
	j = rnds[1];
	k = rnds[2];
	{
	    long l = j, g = i;
	    if (j >= i) l = i, g = ++j;
	    if (k >= l && (++k >= g)) ++k;
	}
	return rb_ary_new_from_args(3, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j), RARRAY_AREF(ary, k));
    }
    memo_threshold =
	len < 2560 ? len / 128 :
	len < 5120 ? len / 64 :
	len < 10240 ? len / 32 :
	len / 16;
    if (n <= numberof(idx)) {
	long sorted[numberof(idx)];
	sorted[0] = idx[0] = rnds[0];
	for (i=1; i<n; i++) {
	    k = rnds[i];
	    for (j = 0; j < i; ++j) {
		if (k < sorted[j]) break;
		++k;
	    }
	    memmove(&sorted[j+1], &sorted[j], sizeof(sorted[0])*(i-j));
	    sorted[j] = idx[i] = k;
	}
	result = rb_ary_new_capa(n);
        RARRAY_PTR_USE_TRANSIENT(result, ptr_result, {
	    for (i=0; i<n; i++) {
		ptr_result[i] = RARRAY_AREF(ary, idx[i]);
	    }
	});
    }
    else if (n <= memo_threshold / 2) {
	long max_idx = 0;
#undef RUBY_UNTYPED_DATA_WARNING
#define RUBY_UNTYPED_DATA_WARNING 0
	VALUE vmemo = Data_Wrap_Struct(0, 0, st_free_table, 0);
	st_table *memo = st_init_numtable_with_size(n);
	DATA_PTR(vmemo) = memo;
	result = rb_ary_new_capa(n);
	RARRAY_PTR_USE(result, ptr_result, {
	    for (i=0; i<n; i++) {
		long r = RAND_UPTO(len-i) + i;
		ptr_result[i] = r;
		if (r > max_idx) max_idx = r;
	    }
	    len = RARRAY_LEN(ary);
	    if (len <= max_idx) n = 0;
	    else if (n > len) n = len;
            RARRAY_PTR_USE_TRANSIENT(ary, ptr_ary, {
		for (i=0; i<n; i++) {
		    long j2 = j = ptr_result[i];
		    long i2 = i;
		    st_data_t value;
		    if (st_lookup(memo, (st_data_t)i, &value)) i2 = (long)value;
		    if (st_lookup(memo, (st_data_t)j, &value)) j2 = (long)value;
		    st_insert(memo, (st_data_t)j, (st_data_t)i2);
		    ptr_result[i] = ptr_ary[j2];
		}
	    });
	});
	DATA_PTR(vmemo) = 0;
	st_free_table(memo);
    }
    else {
	result = rb_ary_dup(ary);
	RBASIC_CLEAR_CLASS(result);
	RB_GC_GUARD(ary);
	RARRAY_PTR_USE(result, ptr_result, {
	    for (i=0; i<n; i++) {
		j = RAND_UPTO(len-i) + i;
		nv = ptr_result[j];
		ptr_result[j] = ptr_result[i];
		ptr_result[i] = nv;
	    }
	});
	RBASIC_SET_CLASS_RAW(result, rb_cArray);
    }
    ARY_SET_LEN(result, n);

    return result;
}