objc2_gameplay_kit/generated/

GKRandomDistribution.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;

use crate::*;

extern_class!(
    /// A random distribution is a random source itself with a specific mapping from the input source to the output values.
    /// The distribution is uniform, meaning there is no bias towards any of the possible outcomes.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkrandomdistribution?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKRandomDistribution;
);

#[cfg(feature = "GKRandomSource")]
extern_conformance!(
    unsafe impl GKRandom for GKRandomDistribution {}
);

extern_conformance!(
    unsafe impl NSObjectProtocol for GKRandomDistribution {}
);

impl GKRandomDistribution {
    extern_methods!(
        /// The lowest value the distribution will output.
        #[unsafe(method(lowestValue))]
        #[unsafe(method_family = none)]
        pub unsafe fn lowestValue(&self) -> NSInteger;

        /// The highest value the distribution will output.
        #[unsafe(method(highestValue))]
        #[unsafe(method_family = none)]
        pub unsafe fn highestValue(&self) -> NSInteger;

        /// The number of unique possible outcomes, depending on the distribution type this is not always highest - lowest + 1.
        #[unsafe(method(numberOfPossibleOutcomes))]
        #[unsafe(method_family = none)]
        pub unsafe fn numberOfPossibleOutcomes(&self) -> NSUInteger;

        #[cfg(feature = "GKRandomSource")]
        /// Initializes a random distribution within the range [lowest, highest] using a source to grab input values from.
        #[unsafe(method(initWithRandomSource:lowestValue:highestValue:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithRandomSource_lowestValue_highestValue(
            this: Allocated<Self>,
            source: &ProtocolObject<dyn GKRandom>,
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        /// Returns the next integer in the distribution sequence and moves ahead to the next one.
        /// The value is in the range of [lowest, highest].
        #[unsafe(method(nextInt))]
        #[unsafe(method_family = none)]
        pub unsafe fn nextInt(&self) -> NSInteger;

        /// Returns the next unsigned value in the distribution sequence that is less than upperBound.
        /// The value never equals or exceeeds upperBounds, and in this case it will also never exceed
        /// the highest value of the distribution.
        #[unsafe(method(nextIntWithUpperBound:))]
        #[unsafe(method_family = none)]
        pub unsafe fn nextIntWithUpperBound(&self, upper_bound: NSUInteger) -> NSUInteger;

        /// Returns the next uniform float in the random sequence and moves ahead to the next one.
        /// The value is in the range of [lowest / higest, 1.0].
        ///
        /// The value is quantized to the distribution's lowest and highest bounds. Thus on a d20
        /// distribution the value is quantized to 5% increments. The output value 0 is not possible
        /// to get unless the lowest value bound is also 0 or below.
        ///
        ///
        /// See: nextInt
        #[unsafe(method(nextUniform))]
        #[unsafe(method_family = none)]
        pub unsafe fn nextUniform(&self) -> c_float;

        /// Returns the next true or false value in the distribution sequence and moves ahead to the next one.
        /// The value is either nonzero (true) or zero (false).
        /// Use this for simple boolean switches in logic that don't require fuzzy evaluation.
        /// For fuzzy evaluation use nextUniform.
        ///
        /// By default this is based on the referenced source's definition of nextBool.
        ///
        ///
        /// See: GKRandomSource.nextBool
        #[unsafe(method(nextBool))]
        #[unsafe(method_family = none)]
        pub unsafe fn nextBool(&self) -> bool;

        /// Convenience creation of random distribution within the range [lowest, highest] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionWithLowestValue:highestValue:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionWithLowestValue_highestValue(
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        /// Convenience creation of random distribution with the die like range [1, sideCount] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionForDieWithSideCount:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionForDieWithSideCount(side_count: NSInteger) -> Retained<Self>;

        /// Convenience creation for the very common d6 range [1, 6] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d6))]
        #[unsafe(method_family = none)]
        pub unsafe fn d6() -> Retained<Self>;

        /// Convenience creation for the very common d20 range [1, 20] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d20))]
        #[unsafe(method_family = none)]
        pub unsafe fn d20() -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKRandomDistribution {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// A gaussian distribution is biased towards the mean value, the possible outcomes are spread out from the mean
    /// with decreasing probability. Values within 1 deviation of the mean make up 68.27% of the distribution, values
    /// within 2 deviations make up 95% and values within 3 deviations make up 99.7%.
    ///
    /// Note that a gaussian distribution's unbounded behavior beyond 3 deviations is undesired,
    /// thus this distribution deviates nominally by modifying the bounds to 3 deviations.
    /// Thus values within 3 deviations actually make up 100% of the distribution.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkgaussiandistribution?language=objc)
    #[unsafe(super(GKRandomDistribution, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKGaussianDistribution;
);

#[cfg(feature = "GKRandomSource")]
extern_conformance!(
    unsafe impl GKRandom for GKGaussianDistribution {}
);

extern_conformance!(
    unsafe impl NSObjectProtocol for GKGaussianDistribution {}
);

impl GKGaussianDistribution {
    extern_methods!(
        /// The mean, or expected, value of the distribution. Values are more probable the closer to the mean they are.
        #[unsafe(method(mean))]
        #[unsafe(method_family = none)]
        pub unsafe fn mean(&self) -> c_float;

        /// The deviation, often called 'sigma', is the deviation from the mean that would include roughly 68% of the distribution.
        /// The range of the distribution is [mean - 3 * deviation, mean + 3 * deviation]. Values beyond 3 deviations
        /// are considered so improbable that they are removed from the output set.
        #[unsafe(method(deviation))]
        #[unsafe(method_family = none)]
        pub unsafe fn deviation(&self) -> c_float;

        #[cfg(feature = "GKRandomSource")]
        /// Initializes a Gaussian random distribution within the range [lowest, highest] using a source to grab input values from.
        /// This sets the gaussian parameters to:
        ///
        /// mean = (highest + lowest) / 2
        /// deviation = (highest - lowest) / 6
        ///
        /// The mean and deviation will be floating point numbers even if the distribution is meant to produce integer values.
        ///
        /// See: mean
        ///
        /// See: deviation
        #[unsafe(method(initWithRandomSource:lowestValue:highestValue:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithRandomSource_lowestValue_highestValue(
            this: Allocated<Self>,
            source: &ProtocolObject<dyn GKRandom>,
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        #[cfg(feature = "GKRandomSource")]
        /// Initializes a Gaussian random distribution within the range [mean - 3 * deviation, mean + 3 * deviation]
        /// using a source to grab input values from.
        #[unsafe(method(initWithRandomSource:mean:deviation:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithRandomSource_mean_deviation(
            this: Allocated<Self>,
            source: &ProtocolObject<dyn GKRandom>,
            mean: c_float,
            deviation: c_float,
        ) -> Retained<Self>;
    );
}

/// Methods declared on superclass `GKRandomDistribution`.
impl GKGaussianDistribution {
    extern_methods!(
        /// Convenience creation of random distribution within the range [lowest, highest] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionWithLowestValue:highestValue:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionWithLowestValue_highestValue(
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        /// Convenience creation of random distribution with the die like range [1, sideCount] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionForDieWithSideCount:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionForDieWithSideCount(side_count: NSInteger) -> Retained<Self>;

        /// Convenience creation for the very common d6 range [1, 6] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d6))]
        #[unsafe(method_family = none)]
        pub unsafe fn d6() -> Retained<Self>;

        /// Convenience creation for the very common d20 range [1, 20] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d20))]
        #[unsafe(method_family = none)]
        pub unsafe fn d20() -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKGaussianDistribution {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// A shuffled distribution tries to make sure individual samples are not clustered whilst retaining a uniform distribution of values
    /// over time. This is often referred to as fair or less random, as the predicatability of the outcomes in a series is vastly increased,
    /// yet the distribution of values is uniform.
    ///
    /// Do not use with distributions ranging more than 256 between lowest and highest as the shuffling seqeunce is stored internally in memory.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkshuffleddistribution?language=objc)
    #[unsafe(super(GKRandomDistribution, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKShuffledDistribution;
);

#[cfg(feature = "GKRandomSource")]
extern_conformance!(
    unsafe impl GKRandom for GKShuffledDistribution {}
);

extern_conformance!(
    unsafe impl NSObjectProtocol for GKShuffledDistribution {}
);

impl GKShuffledDistribution {
    extern_methods!();
}

/// Methods declared on superclass `GKRandomDistribution`.
impl GKShuffledDistribution {
    extern_methods!(
        #[cfg(feature = "GKRandomSource")]
        /// Initializes a random distribution within the range [lowest, highest] using a source to grab input values from.
        #[unsafe(method(initWithRandomSource:lowestValue:highestValue:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithRandomSource_lowestValue_highestValue(
            this: Allocated<Self>,
            source: &ProtocolObject<dyn GKRandom>,
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        /// Convenience creation of random distribution within the range [lowest, highest] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionWithLowestValue:highestValue:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionWithLowestValue_highestValue(
            lowest_inclusive: NSInteger,
            highest_inclusive: NSInteger,
        ) -> Retained<Self>;

        /// Convenience creation of random distribution with the die like range [1, sideCount] using an isolated source to grab input values from.
        /// This is equivalent to calling alloc followed by initWithSource:lowest:highest:, where source is [[GKRandomSource alloc] init].
        ///
        /// See: initWithRandomSource:lowestValue:highestValue:
        #[unsafe(method(distributionForDieWithSideCount:))]
        #[unsafe(method_family = none)]
        pub unsafe fn distributionForDieWithSideCount(side_count: NSInteger) -> Retained<Self>;

        /// Convenience creation for the very common d6 range [1, 6] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d6))]
        #[unsafe(method_family = none)]
        pub unsafe fn d6() -> Retained<Self>;

        /// Convenience creation for the very common d20 range [1, 20] with an isolated random source
        /// shielded from outside sources.
        #[unsafe(method(d20))]
        #[unsafe(method_family = none)]
        pub unsafe fn d20() -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKShuffledDistribution {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}