faker 2.0.0 → 3.8.0

data/lib/faker/default/name.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :name
 
     class << self
+      ##
+      # Produces a random name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name #=> "Tyshawn Johns Sr."
+      #
+      # @faker.version 0.9.0
       def name
         parse('name.name')
       end
 
+      ##
+      # Produces a random name with middle name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name_with_middle #=> "Aditya Elton Douglas"
+      #
+      # @faker.version 1.6.4
       def name_with_middle
         parse('name.name_with_middle')
       end
 
+      ##
+      # Produces a random first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.first_name #=> "Kaci"
+      #
+      # @faker.version 0.9.0
       def first_name
         if parse('name.first_name').empty?
           fetch('name.first_name')
@@ -21,31 +48,102 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random male first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.male_first_name #=> "Edward"
+      #
+      # @faker.version 1.9.1
       def male_first_name
         fetch('name.male_first_name')
       end
       alias first_name_men male_first_name
       alias masculine_name male_first_name
 
+      ##
+      # Produces a random female first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.female_first_name #=> "Natasha"
+      #
+      # @faker.version 1.9.1
       def female_first_name
         fetch('name.female_first_name')
       end
       alias first_name_women female_first_name
       alias feminine_name female_first_name
 
+      ##
+      # Produces a random gender neutral first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.neutral_first_name #=> "Casey"
+      #
+      # @faker.version 2.13.0
+      def neutral_first_name
+        fetch('name.neutral_first_name')
+      end
+      alias first_name_neutral neutral_first_name
+      alias gender_neutral_first_name neutral_first_name
+
+      ##
+      # Produces a random last name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.last_name #=> "Ernser"
+      #
+      # @faker.version 0.9.0
       def last_name
         parse('name.last_name')
       end
       alias middle_name last_name
 
+      ##
+      # Produces a random name prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.prefix #=> "Mr."
+      #
+      # @faker.version 0.9.0
       def prefix
         fetch('name.prefix')
       end
 
+      ##
+      # Produces a random name suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.suffix #=> "IV"
+      #
+      # @faker.version 0.9.0
       def suffix
         fetch('name.suffix')
       end
 
+      ##
+      # Produces random initials.
+      #
+      # @param number [Integer] Number of digits that the generated initials should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.initials            #=> "NJM"
+      #   Faker::Name.initials(number: 2) #=> "NM"
+      #
+      # @faker.version 1.8.5
       def initials(number: 3)
         (0...number).map { rand(65..90).chr }.join
       end

data/lib/faker/default/nation.rb

@@ -4,27 +4,67 @@ module Faker
   class Nation < Base
     flexible :nation
     class << self
-      # Fetch random nationality
+      ##
+      # Produces a random nationality.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.nationality #=> "Nepalese"
+      #
+      # @faker.version 1.9.0
       def nationality
         fetch('nation.nationality')
       end
 
-      # Fetch random national flag emoji
+      ##
+      # Produces a random national flag emoji.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.flag #=> "🇫🇮"
+      #
+      # @faker.version 1.9.0
       def flag
         sample(translate('faker.nation.flag')).pack('C*').force_encoding('utf-8')
       end
 
-      # Fetch random language
+      ##
+      # Produces a random national language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.language #=> "Nepali"
+      #
+      # @faker.version 1.9.0
       def language
         fetch('nation.language')
       end
 
-      # Fetch random capital city
+      ##
+      # Produces a random capital city.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.capital_city #=> "Kathmandu"
+      #
+      # @faker.version 1.9.0
       def capital_city
         fetch('nation.capital_city')
       end
 
-      # Fetch random natinal sport
+      ##
+      # Produces a random national sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.national_sport #=> "dandi biyo"
+      #
+      # @faker.version 1.9.0
       def national_sport
         fetch('team.sport')
       end

data/lib/faker/default/{nhs.rb → national_health_service.rb}

@@ -3,18 +3,41 @@
 module Faker
   class NationalHealthService < Base
     class << self
+      ##
+      # Produces a random British NHS number.
+      #
+      # The NHS sets aside a range of numbers from 999 000 0000 to 999 999 9999
+      # for test purposes.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NationalHealthService.british_number #=> "999 464 0232"
+      #
+      # @faker.version 1.9.2
       def british_number
-        base_number = rand(400_000_001...499_999_999)
+        base_number = rand(999_000_001...999_999_999)
         # If the check digit is equivalent to 10, the number is invalid.
         # See https://en.wikipedia.org/wiki/NHS_number
         base_number -= 1 if check_digit(number: base_number) == 10
-        "#{base_number}#{check_digit(number: base_number)}".to_s
-                                                           .chars
+        "#{base_number}#{check_digit(number: base_number)}".chars
                                                            .insert(3, ' ')
                                                            .insert(7, ' ')
-                                                           .join('')
+                                                           .join
       end
 
+      private
+
+      ##
+      # Produces a random British NHS number's check digit.
+      #
+      # @param number [Integer] Specifies the NHS number the check digit belongs to.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::NationalHealthService.check_digit(number: 400_012_114) #=> 6
+      #
+      # @faker.version 1.9.2
       def check_digit(number: 0)
         sum = 0
         number.to_s.chars.each_with_index do |digit, idx|

data/lib/faker/default/nato_phonetic_alphabet.rb

@@ -3,6 +3,15 @@
 module Faker
   class NatoPhoneticAlphabet < Base
     class << self
+      ##
+      # Produces a code word from the NATO phonetic alphabet.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NatoPhoneticAlphabet.code_word #=> "Hotel"
+      #
+      # @faker.version 1.9.0
       def code_word
         fetch('nato_phonetic_alphabet.code_word')
       end

data/lib/faker/default/number.rb

@@ -3,18 +3,48 @@
 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(digits: 10)
         return if digits < 1
-        return 0 if digits == 1
+        return rand(0..9).round if digits == 1
 
         # Ensure the first digit is not zero
         ([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(digits: 10)
-        '0' + (2..digits).collect { digit }.join
-      end
-
+        "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(digits: 10)
         num = ''
         if digits > 1
@@ -24,32 +54,96 @@ module Faker
         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(l_digits: 5, r_digits: 2)
         l_d = number(digits: l_digits)
-        r_d = if r_digits == 1
-                generate(r_digits)
-              else
-                # Ensure the last digit is not zero
-                # so it does not get truncated on converting to float
-                generate(r_digits - 1).join + non_zero_digit.to_s
-              end
+
+        # Ensure the last digit is not zero
+        # so it does not get truncated on converting to float
+        r_d = generate(r_digits - 1).join + non_zero_digit.to_s
+
         "#{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(digits: 6)
         hex = ''
-        digits.times { hex += rand(15).to_s(16) }
+        digits.times { hex += rand(16).to_s(16) }
         hex
       end
 
+      # Produces a number in binary format.
+      #
+      # @param digits [Integer] Number of digits to generate the binary as string
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.binary(digits: 4) #=> "1001"
+      #
+      # @faker.version next
+      def binary(digits: 4)
+        bin = ''
+        digits.times { bin += rand(2).to_s(2) }
+        bin
+      end
+
+      ##
+      # Produces a float given a mean and standard deviation.
+      #
+      # @param mean [Integer]
+      # @param standard_deviation [Numeric]
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156
+      #
+      # @faker.version 1.0.0
       def normal(mean: 1, standard_deviation: 1)
         theta = 2 * Math::PI * rand
         rho = Math.sqrt(-2 * Math.log(1 - rand))
@@ -57,20 +151,65 @@ module Faker
         mean + scale * Math.cos(theta)
       end
 
+      ##
+      # Produces a number between two provided values. Boundaries are inclusive.
+      #
+      # @param from [Numeric] The lowest number to include.
+      # @param to [Numeric] The highest number to include.
+      # @return [Numeric]
+      #
+      # @example
+      #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #   Faker::Number.between(from: 0.0, to: 1.0) #=> 0.7844640543957383
+      #
+      # @faker.version 1.0.0
       def between(from: 1.00, to: 5000.00)
         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 [Numeric]
+      #
+      # @example
+      #   Faker::Number.within(range: 1..10) #=> 7
+      #   Faker::Number.within(range: 0.0..1.0) #=> 0.7844640543957383
+      #
+      # @faker.version 1.0.0
       def within(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(from: 1.00, to: 5000.00)
         random_number = between(from: from, to: to)
 
         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(from: -5000.00, to: -1.00)
         random_number = between(from: from, to: to)