Swiftpack.co - Package - GigabiteLabs/random-swift

random-swift

A utility for randomly generating data, content, and assets for iOS & macOS apps written in Swift.

CI Status Version License Platform Readme Score codebeat badge

Requirements

  • iOS v11.0 or higher
  • macOS v10.15 or higher (mac catalyst)

Installation

Cococapods

random-swift is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'random-swift'

Swift Package Manager

add this repository to your project via Swift PM:

  • open your project
  • select the project's .xcodeproj in the navigator
  • select your project target
  • select "Swift Packages"
  • enter: https://github.com/GigabiteLabs/random-swift.git and choose the latest release version.

Documentation

Full public documentation of the framework can be found here.

Import Options

Import into entire project

Open AppDelegate.swift

Add an exported import statement to the top of the class like so:

@_exported import random_swift

The framework is now accessible in every class in your project.

Note: There are some differing opinions about @_exported import, namely, the risk of object and class name collisions between frameworks, however, if you don’t have any issues with the exported import approach in your project, you’re gonna be alright, and the convenience trade-off is probably worth it.

Import into class or file

After installing, import into your class:

import random_swift

Usage

Currently supported:

Global Accessibility & Persistent Configuration

  • Security & true randomness assured by leveraging the underlying arc4random() generator built into swift

  • Random is available as a shared instance within the imported scope (class, project, etc.)

     // access it with:
     Random.(type)
    
  • A configuration set persists on the shared instance for the duration of the application session

     // setup an IntRange configuration
     let intRange = IntRange(lower: 4, upper: 100)
    
     // setup a percentage range configuration
     let pctRange = PercentageRange(min: 0.10, max: 0.98)
    
     // assign the configurations
     Random.intRange = intRange
     Random.percentageRange = pctRange
    

    While this shared instance is still in memory (i.e. the app is still running / not terminated or backgrounded), the last used configuration will be used as the default configuration for any calls for random values that need a range or an upper-bound limit.

  • You can dynamically use new range configurations if you need to change them on the fly for new requests

    An example retrieving a new randomValue with a new range config:

     // setup:
     let newIntRange = IntRange(lower: 1, upper: 5000)
     
     // get a random int value within the range
     let rangedInt = Random.int.withinRange(range: newIntRange)
     
     // get a random int value anywhere between 0 and the newIntRange.upper
     Random.int.withUpperLimit(of: newIntRange)
    

Random Word Generation

Random supports true random word generation.

Random words are generated from a static dictionary containing 235,886 words, all of which are packaged by default with macOS.

Functions

  • Get a random Word:

    let randomWord = Random.word
    

### Random Value Generation

Random Ints

Functions

  • Get a random Int:

     let randomInt = Random.int.value()
    
  • Get a random Int below a given IntRange upper-bound limit:

     // setup a range
     let range = IntRange(lower: 10, upper: 200)
     
     // get a random int value within the range
     let rangedInt = Random.int.withinRange(range: range)
    
  • Get a random Int value within a given range, between both upper and lower bounds:

     // setup a range
     let range = IntRange(lower: 10, upper: 250)
     
     // get a random int value between range.lower and range.upper
     let randomWithinRange: Int = Random.int.withinRange(range: newIntRange)
    

Computed Properties

  • Get a random Int:

     let randomInt = Random.int.value
    

Note: The following computed properties require configuration to be in place beforehand.

These will always return 0 if:

- A config has not been set by using a function call
- or by directly configuring `Random.intRange`.

Usage is basically the same as a function call:

  • Get a random Int below a given IntRange upper-bound limit:

     // setup a range & configure
     let range = IntRange(lower: 10, upper: 200)
     Random.intRange = range
     
     // get a random int value within the range
     let rangedInt = Random.int.withinUpperLimit
    
  • Get a random Int value within a given range, between both upper and lower bounds:

     // setup a range & configure
     let range = IntRange(lower: 10, upper: 250)
     Random.intRange = range
     
     // get a random int value between range.lower and range.upper
     let randomWithinRange: Int = Random.int.withinRange
     // randomWithinRange == some Int between 10 and 200, exclusive of 200 (so max 199)
    

Random Percentages

Functions

  • Get a random percentage (aka Double) with optional max decimal place rounding:

     let randomPct = Random.percentage.value(roundedTo: 5)
     // returns percentage with no more than 5 place values
     // e.g. 0.45369
    
  • Get a random percentage below a given PercentageRange max limit, optionally rounding to a max number of decimal place values:

     // setup a range
     let range = PercentageRange(lower: 0.10, upper: 0.999)
    
     // get a random int value within the range
     let rangedPct: Double = Random.percentage.withUpperLimit(of: range, maxDecimalPlaces: 3)
     // returns percentage with no more than 3 decimal places
     // e.g. 0.294
    
  • Get a random percentage value within a given range, between min and max limits:

     // setup a range
     let range = PercentageRange(lower: 0.15, upper: 0.322)
     
     // get a random int value between range.lower and range.upper
     let randomPctWithinRange: Double = Random.percentage.withinRange(range, maxDecimalPlaces: 1)
     // returns percentage with no more than 1 decimal place
     // e.g. 0.6
    

Computed Properties

  • Get a random percentage (aka Double):

     let randomPct: Double = Random.percentage.value
    

Note: the following computed properties require configuration to be in place beforehand.

These will always return 0.0 if:

- A config has not been set by using a function call
- or by directly configuring `Random.percentageRange`.

Usage is basically the same as a function call:

  • Get a random percentage below a given PercentageRange max limit:

     // setup a range & configure shared instance
     let range = PercentageRange(lower: 0.15, upper: 0.322)
     Random.intRange = range
     
     // get a random percentage value within the range
     let rangedPct: Double = Random.percentage.withUpperLimit
    
  • Get a random percentage value within a given range, between min and max limits:

     // setup a range & configure
     let range = PercentageRange(lower: 0.01, upper: 0.9)
     Random.intRange = range
     
     // get a random int value between range.lower and range.upper
     let randomPctWithinRange: Double = Random.percentage.withinRange
     // randomWithinRange == some Int between 0.01 and 0.9, exclusive of 0.9 (so max 0.89)
    

Authors

Original Author: Dan Burkhardt Founder & Lead Engineer @GigabiteLabs Twitter: @GigabiteDan

Contributors: (nobody else yet ;)

License

random-swift is available under the MIT license. See the LICENSE file for more info.

Github

link
Stars: 0

Dependencies

Used By

Total: 0

Releases

Swift PM Enhancements, Cross-Compatibility w/Cocoapods - 2020-10-02 07:07:53

This update is almost entirely about making sure and that is framework is fully compatible with both Swift package manager aunt Cocoapods. Here are the changes:

  • re-organization of entire folder structure around the requirements of Swift package manager
  • relinking Cocoapods into the Swift package manager directory structure
  • implemented support for Swift package resource bundle refs
  • ensures that both build and test is possible from the command line for the swift package
  • pre-processor macro implemented to prevent Cocoapods from referencing the same Bundle as the Swift package
  • UIKit imports protected using canImport

Random Word Generation Support Added - 2020-07-08 04:48:41

  • random-swift generates random words using a local dictionary of 235,886 words
  • random words are disabled by default in release builds due to memory impact
  • configuration object added for user-defined config
  • unit tests added, some edge cases for failing resource paths cannot be easily tested, coverage drops to 98.4%
  • Minor bug fix with bundle path resolution

Random Word Generation Support Added - 2020-07-08 03:48:09

  • random-swift generates random words using a local dictionary of 235,886 words
  • random words are disabled by default in release builds due to memory impact
  • configuration object added for user-defined config
  • unit tests added, some edge cases for failing resource paths cannot be easily tested, coverage drops to 98.4%

Updated Readme & Travis - 2020-07-03 11:20:09

  • Usage instructions
  • Travis build status linked
  • Badges fixed

Initial Release - 2020-07-03 09:10:25

  • Random in values
  • Random percentage values
  • Unit tests passing with 100% coverage