diff --git a/lib/faker/default/date.rb b/lib/faker/default/date.rb index 8b3e16446b..497815eb3f 100644 --- a/lib/faker/default/date.rb +++ b/lib/faker/default/date.rb @@ -3,6 +3,18 @@ module Faker class Date < Base class << self + ## + # Produce a random date between two dates. + # + # @param from [Date] The start of the usable date range. + # @param to [Date] The end of the usable date range. + # @return [Date] + # + # @example + # Faker::Date.between(from: 2.days.ago, to: Date.today) + # #=> # + # + # @faker.version 1.0.0 def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:) warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN @@ -16,8 +28,21 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:) end # rubocop:disable Metrics/ParameterLists + + ## + # Produce a random date between two dates. + # + # @param from [Date] The start of the usable date range. + # @param to [Date] The end of the usable date range. + # @param excepted [Date] A date to exclude. + # @return [Date] + # + # @example + # Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today) + # #=> # + # + # @faker.version 1.6.2 def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN end @@ -37,7 +62,18 @@ def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_except break date.to_date if date != excepted end end - + # rubocop:enable Metrics/ParameterLists + + ## + # Produce a random date in the future (up to N days). + # + # @param days [Integer] The maximum number of days to go into the future. + # @return [Date] + # + # @example + # Faker::Date.forward(days: 23) #=> # + # + # @faker.version 1.0.0 def forward(legacy_days = NOT_GIVEN, days: 365) warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN @@ -49,6 +85,16 @@ def forward(legacy_days = NOT_GIVEN, days: 365) between(from: from, to: to).to_date end + ## + # Produce a random date in the past (up to N days). + # + # @param days [Integer] The maximum number of days to go into the past. + # @return [Date] + # + # @example + # Faker::Date.backward(days: 14) #=> # + # + # @faker.version 1.0.0 def backward(legacy_days = NOT_GIVEN, days: 365) warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN @@ -60,6 +106,17 @@ def backward(legacy_days = NOT_GIVEN, days: 365) between(from: from, to: to).to_date end + ## + # Produce a random date in the past (up to N days). + # + # @param min_age [Integer] The minimum age that the birthday would imply. + # @param max_age [Integer] The maximum age that the birthday would imply. + # @return [Date] + # + # @example + # Faker::Date.birthday(min_age: 18, max_age: 65) #=> # + # + # @faker.version 1.4.3 def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65) warn_for_deprecated_arguments do |keywords| keywords << :min_age if legacy_min_age != NOT_GIVEN diff --git a/lib/faker/default/number.rb b/lib/faker/default/number.rb index 4e2ae78404..38230e0ec4 100644 --- a/lib/faker/default/number.rb +++ b/lib/faker/default/number.rb @@ -3,6 +3,16 @@ module Faker class Number < Base class << self + ## + # Produce a random number. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [Integer] + # + # @example + # Faker::Number.number(digits: 10) #=> 1968353479 + # + # @faker.version 1.0.0 def number(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -15,6 +25,16 @@ def number(legacy_digits = NOT_GIVEN, digits: 10) ([non_zero_digit] + generate(digits - 1)).join.to_i end + ## + # Produce a random number with a leading zero. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [String] + # + # @example + # Faker::Number.leading_zero_number(digits: 10) #=> "0669336915" + # + # @faker.version 1.0.0 def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -23,6 +43,16 @@ def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10) '0' + (2..digits).collect { digit }.join end + ## + # Produce a number with a number of digits, preserves leading zeroes. + # + # @param digits [Integer] Number of digits that the generated number should have. + # @return [String] + # + # @example + # Faker::Number.decimal_part(digits: 2) #=> "09" + # + # @faker.version 1.0.0 def decimal_part(legacy_digits = NOT_GIVEN, digits: 10) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -36,6 +66,18 @@ def decimal_part(legacy_digits = NOT_GIVEN, digits: 10) leading_zero_number(digits: digits) + num.to_s end + ## + # Produces a float. + # + # @param l_digits [Integer] Number of digits that the generated decimal should have to the left of the decimal point. + # @param r_digits [Integer] Number of digits that the generated decimal should have to the right of the decimal point. + # @return [Float] + # + # @example + # Faker::Number.decimal(l_digits: 2) #=> 11.88 + # Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843 + # + # @faker.version 1.0.0 def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: 5, r_digits: 2) warn_for_deprecated_arguments do |keywords| keywords << :l_digits if legacy_l_digits != NOT_GIVEN @@ -53,14 +95,42 @@ def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: "#{l_d}.#{r_d}".to_f end + ## + # Produces a non-zero single-digit integer. + # + # @return [Integer] + # + # @example + # Faker::Number.non_zero_digit #=> 8 + # + # @faker.version 1.0.0 def non_zero_digit rand(1..9) end + ## + # Produces a single-digit integer. + # + # @return [Integer] + # + # @example + # Faker::Number.digit #=> 1 + # + # @faker.version 1.0.0 def digit rand(10) end + ## + # Produces a number in hexadecimal format. + # + # @param digits [Integer] Number of digits in the he + # @return [String] + # + # @example + # Faker::Number.hexadecimal(digits: 3) #=> "e74" + # + # @faker.version 1.0.0 def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6) warn_for_deprecated_arguments do |keywords| keywords << :digits if legacy_digits != NOT_GIVEN @@ -71,6 +141,17 @@ def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6) hex end + ## + # Produces a float given a mean and standard deviation. + # + # @param mean [Integer] + # @param standard_deviation [Integer, Float] + # @return [Float] + # + # @example + # Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156 + # + # @faker.version 1.0.0 def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: 1, standard_deviation: 1) warn_for_deprecated_arguments do |keywords| keywords << :mean if legacy_mean != NOT_GIVEN @@ -83,6 +164,17 @@ def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: mean + scale * Math.cos(theta) end + ## + # Produces a number between two provided values. Boundaries are inclusive. + # + # @param from [Integer] The lowest number to include. + # @param to [Integer] The highest number to include. + # @return [Integer] + # + # @example + # Faker::Number.between(from: 1, to: 10) #=> 7 + # + # @faker.version 1.0.0 def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00) warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN @@ -92,6 +184,16 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000 Faker::Base.rand_in_range(from, to) end + ## + # Produces a number within two provided values. Boundaries are inclusive or exclusive depending on the range passed. + # + # @param range [Range] The range from which to generate a number. + # @return [Integer] + # + # @example + # Faker::Number.within(range: 1..10) #=> 7 + # + # @faker.version 1.0.0 def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00) warn_for_deprecated_arguments do |keywords| keywords << :range if legacy_range != NOT_GIVEN @@ -100,6 +202,17 @@ def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00) between(from: range.min, to: range.max) end + ## + # Produces a positive float. + # + # @param from [Integer] The lower boundary. + # @param to [Integer] The higher boundary. + # @return [Float] + # + # @example + # Faker::Number.positive #=> 235.59238499107653 + # + # @faker.version 1.0.0 def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00) warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN @@ -111,6 +224,17 @@ def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 500 greater_than_zero(random_number) end + ## + # Produces a negative float. + # + # @param from [Integer] The lower boundary. + # @param to [Integer] The higher boundary. + # @return [Float] + # + # @example + # Faker::Number.negative #=> -4480.042585669558 + # + # @faker.version 1.0.0 def negative(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: -5000.00, to: -1.00) warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN diff --git a/lib/faker/default/time.rb b/lib/faker/default/time.rb index b96a5d5d81..c8cf423520 100644 --- a/lib/faker/default/time.rb +++ b/lib/faker/default/time.rb @@ -14,8 +14,31 @@ class Time < Base class << self # rubocop:disable Metrics/ParameterLists + # rubocop:disable Style/AsciiComments + + ## + # Produce a random time between two times. + # + # @param from [Time, Date, DateTime] The start of the usable time range. + # @param to [Time, Date, DateTime] The end of the usable time range. + # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] + # + # @example + # # Random Stringified time between two times, formatted to the specified I18n format + # # (Examples are from a Rails console with rails-i18n 5.1.1 defaults loaded) + # I18n.locale = 'en-US' + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "Tue, 16 Oct 2018 10:48:27 AM -05:00" + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "15 Oct 10:48 AM" + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "October 15, 2018 10:48 AM" + # + # I18n.locale = 'ja' + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "2018/10/15 10:48:27" + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "18/10/15 10:48" + # Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "2018年10月16日(火) 10時48分27秒 -0500" + # + # @faker.version 1.5.0 def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, format: nil) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN keywords << :to if legacy_to != NOT_GIVEN @@ -28,10 +51,37 @@ def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_ time = Faker::Base.rand_in_range(from, to) time_with_format(time, format) end - - # rubocop:disable Metrics/ParameterLists + # rubocop:enable Style/AsciiComments + + ## + # Produce a random time between two dates. + # + # @param from [Date] The start of the usable time range. + # @param to [Date] The end of the usable time range. + # @param period [Symbol] The time of day, if any. See {TIME_RANGES}. + # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] + # + # @example + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :all) + # #=> "2014-09-19 07:03:30 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :day) + # #=> "2014-09-18 16:28:13 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :night) + # #=> "2014-09-20 19:39:38 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :morning) + # #=> "2014-09-19 08:07:52 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :afternoon) + # #=> "2014-09-18 12:10:34 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :evening) + # #=> "2014-09-19 20:21:03 -0700" + # Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :midnight) + # #=> "2014-09-20 00:40:14 -0700" + # Faker::Time.between_dates(from: Date.today - 5, to: Date.today + 5, period: :afternoon, format: :default) + # #=> "Fri, 19 Oct 2018 15:17:46 -0500" + # + # @faker.version 1.0.0 def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, period: :all, format: nil) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :from if legacy_from != NOT_GIVEN keywords << :to if legacy_to != NOT_GIVEN @@ -44,9 +94,22 @@ def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period time_with_format(time, format) end - # rubocop:disable Metrics/ParameterLists + ## + # Produce a random time in the future (up to N days). + # + # @param days [Integer] The maximum number of days to go into the future. + # @param period [Symbol] The time of day, if any. See {TIME_RANGES}. + # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] + # + # @example + # Faker::Time.forward(days: 23, period: :morning) + # # => "2014-09-26 06:54:47 -0700" + # Faker::Time.forward(days: 5, period: :evening, format: :long) + # #=> "October 21, 2018 20:47" + # + # @faker.version 1.5.0 def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN keywords << :period if legacy_period != NOT_GIVEN @@ -56,9 +119,22 @@ def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format) end - # rubocop:disable Metrics/ParameterLists + ## + # Produce a random time in the past (up to N days). + # + # @param days [Integer] The maximum number of days to go into the past. + # @param period [Symbol] The time of day, if any. See {TIME_RANGES}. + # @param format [Symbol] The name of a DateTime format to use. + # @return [Time] + # + # @example + # Faker::Time.backward(days: 14, period: :evening) + # #=> "2014-09-17 19:56:33 -0700" + # Faker::Time.backward(days: 5, period: :morning, format: :short) + # #=> "14 Oct 07:44" + # + # @faker.version 1.5.0 def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil) - # rubocop:enable Metrics/ParameterLists warn_for_deprecated_arguments do |keywords| keywords << :days if legacy_days != NOT_GIVEN keywords << :period if legacy_period != NOT_GIVEN @@ -67,6 +143,7 @@ def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format) end + # rubocop:enable Metrics/ParameterLists private