sample.js (1626B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2018 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var factory = require( './factory.js' ); 24 25 26 // MAIN // 27 28 /** 29 * Samples elements from an array-like object. 30 * 31 * @name sample 32 * @type {Function} 33 * @param {ArrayLike} x - array-like object from which to sample 34 * @param {Options} [options] - function options 35 * @param {NonNegativeInteger} [options.size] - sample size 36 * @param {ProbabilityArray} [options.probs] - element probabilities 37 * @param {boolean} [options.replace=true] - boolean indicating whether to sample with replacement 38 * @throws {TypeError} first argument must be array-like 39 * @throws {TypeError} options argument must be an object 40 * @throws {TypeError} must provide valid options 41 * @throws {RangeError} `size` option must be less than or equal to the length of `x` when the `replace` option is `false` 42 * @returns {Array} sample 43 * 44 * @example 45 * var out = sample( [ 3, null, NaN, 'abc', function(){} ] ); 46 * // e.g., returns [ 3, 'abc', null, 3, null ] 47 */ 48 var sample = factory(); 49 50 51 // EXPORTS // 52 53 module.exports = sample;