objc2_gameplay_kit/generated/

GKRandomSource.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 objc2_foundation::*;

use crate::*;

extern_protocol!(
    /// A protocol for random sources that can generate random numbers. This is the minimal interface needed
    /// to consume random values from a source; concrete subclasses should be used for configuring the
    /// production of random values.
    /// The availability of deterministic random sources is critical to creating reliable gameplay mechanics.
    /// Ensure that systems that should not influence each other have unique random sources and avoid sharing
    /// sources unless absolutely needed.
    ///
    /// This protocol allows you to provide custom random sources from classes that are not able to
    /// derive from GKRandomSource directly.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkrandom?language=objc)
    pub unsafe trait GKRandom {
        /// Returns the next integer in the random sequence and moves ahead to the next one.
        /// The value is in the range of [INT32_MIN, INT32_MAX].
        /// The lower bits are not guaranteed to be random so please use another
        /// property for simple choices.
        ///
        ///
        /// See: nextBool
        ///
        /// See: nextUniform
        #[unsafe(method(nextInt))]
        #[unsafe(method_family = none)]
        unsafe fn nextInt(&self) -> NSInteger;

        /// Returns the next unsigned value in the random sequence that is less than upperBound.
        /// The value is in the range of [0, upperBound). Thus the value never equals or exceeeds upperBound.
        /// The unsigned nature and upper bound allows implementations to use logical shifts to return a
        /// value whose lower bits are more random than a similar call to nextInt.
        ///
        /// This is used to implement nextBool and nextUniform by default.
        #[unsafe(method(nextIntWithUpperBound:))]
        #[unsafe(method_family = none)]
        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 [0.0, 1.0].
        /// There is no weighting across the range so remapping this with a curve may give the best
        /// sampling distribution for your algorithm.
        ///
        /// By default this should be based on nextIntWithUpperBound:. Implementions may base it on
        /// another representation if needed.
        ///
        ///
        /// See: nextIntWithUpperBound:
        ///
        /// See: nextInt
        #[unsafe(method(nextUniform))]
        #[unsafe(method_family = none)]
        unsafe fn nextUniform(&self) -> c_float;

        /// Returns the next true or false value in the random 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 should be based on nextIntWithUpperBound:. Implementations may base it on
        /// another representation if needed.
        ///
        ///
        /// See: nextIntWithUpperBound:
        ///
        /// See: nextUniform
        #[unsafe(method(nextBool))]
        #[unsafe(method_family = none)]
        unsafe fn nextBool(&self) -> bool;
    }
);

extern_class!(
    /// A concrete random source that can generate random numbers. The implementation details are up to the system and
    /// if a particular algorithm is needed then use one of the provided subclasses.
    ///
    /// For certain specialized applications a shared system source may be needed and for those instances there is
    /// a wrapped interface over arc4random_*, accessible via +[GKRandomSource sharedRandom].
    ///
    ///
    /// See: GKARC4RandomSource
    ///
    /// See: GKLinearCongruentialRandomSource
    ///
    /// See: GKMersenneTwisterRandomSource
    ///
    /// See: GKRandomSource.systemRandom
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkrandomsource?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKRandomSource;
);

extern_conformance!(
    unsafe impl GKRandom for GKRandomSource {}
);

extern_conformance!(
    unsafe impl NSCoding for GKRandomSource {}
);

extern_conformance!(
    unsafe impl NSCopying for GKRandomSource {}
);

unsafe impl CopyingHelper for GKRandomSource {
    type Result = Self;
}

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

extern_conformance!(
    unsafe impl NSSecureCoding for GKRandomSource {}
);

impl GKRandomSource {
    extern_methods!(
        /// Creates a new random source initialized using bits from an entropy source like SecRandomCopyBytes.
        /// When used directly from the base class; this source is deterministic and performant but the underlying implementation
        /// details are not specified. Use a subclass with a specific algorithm implementation guaranteed if your application requires
        /// very stringent random source charateristics.
        ///
        ///
        /// See: GKARC4RandomSource
        ///
        /// See: GKLinearCongruentialRandomSource
        ///
        /// See: GKMersenneTwisterRandomSource
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Deserializes a random source from an NSCoder. All random sources support coding for serializing and deserializing the state
        /// of the random source. Each subclass has its own contract for what parts of the state is preserved when serialized but the
        /// general contract is that a serialized source must generate the same sequence of values as the original source would from the
        /// instant it was serialized.
        ///
        /// Note that the sharedRandom instance is an exception as it is explicitly seedless and a shared singleton instance.
        /// When serialized and deserialized it will return the current sharedRandom instance instead.
        ///
        /// # Safety
        ///
        /// `a_decoder` possibly has further requirements.
        #[unsafe(method(initWithCoder:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithCoder(this: Allocated<Self>, a_decoder: &NSCoder) -> Retained<Self>;

        /// Returns a shared instance of a random source that uses the system's underlying random source.
        /// Using this instance modifies the outcome of future calls to the arc4random family of C calls. It is
        /// also affected by calls to the C apis and should not be used for sources that are intended to
        /// be deterministic.
        ///
        ///
        /// Note that while it may seem semantically similar to a GKARC4RandomSource, this is not a drop in replacement.
        #[unsafe(method(sharedRandom))]
        #[unsafe(method_family = none)]
        pub unsafe fn sharedRandom() -> Retained<GKRandomSource>;

        /// Returns a shuffled instance of the given array. The objects in the array are shuffled based on a Fisher-Yates shuffle.
        ///
        /// Any random, be it custom, source or a distribution, that can provide a number with an upper bound of at least the
        /// array.count is suitable for this shuffle.
        ///
        /// # Safety
        ///
        /// `array` generic should be of the correct type.
        #[unsafe(method(arrayByShufflingObjectsInArray:))]
        #[unsafe(method_family = none)]
        pub unsafe fn arrayByShufflingObjectsInArray(&self, array: &NSArray) -> Retained<NSArray>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKRandomSource {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

mod private_NSArrayGameplayKit {
    pub trait Sealed {}
}

/// Category "GameplayKit" on [`NSArray`].
#[doc(alias = "GameplayKit")]
pub unsafe trait NSArrayGameplayKit<ObjectType: Message>:
    ClassType + Sized + private_NSArrayGameplayKit::Sealed
{
    extern_methods!(
        #[unsafe(method(shuffledArrayWithRandomSource:))]
        #[unsafe(method_family = none)]
        unsafe fn shuffledArrayWithRandomSource(
            &self,
            random_source: &GKRandomSource,
        ) -> Retained<NSArray<ObjectType>>;

        #[unsafe(method(shuffledArray))]
        #[unsafe(method_family = none)]
        unsafe fn shuffledArray(&self) -> Retained<NSArray<ObjectType>>;
    );
}

impl<ObjectType: Message> private_NSArrayGameplayKit::Sealed for NSArray<ObjectType> {}
unsafe impl<ObjectType: Message> NSArrayGameplayKit<ObjectType> for NSArray<ObjectType> {}

extern_class!(
    /// A deterministic pseudo-random source that generates random numbers based on an arc4 algorithm.
    /// This is a deterministic random source suitable for creating reliable gameplay mechanics.
    ///
    /// While deterministic, this is not a cryptographic random source, however it may be useful
    /// for obfuscation of gameplay data in manner similar to a stream cipher.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkarc4randomsource?language=objc)
    #[unsafe(super(GKRandomSource, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKARC4RandomSource;
);

extern_conformance!(
    unsafe impl GKRandom for GKARC4RandomSource {}
);

extern_conformance!(
    unsafe impl NSCoding for GKARC4RandomSource {}
);

extern_conformance!(
    unsafe impl NSCopying for GKARC4RandomSource {}
);

unsafe impl CopyingHelper for GKARC4RandomSource {
    type Result = Self;
}

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

extern_conformance!(
    unsafe impl NSSecureCoding for GKARC4RandomSource {}
);

impl GKARC4RandomSource {
    extern_methods!(
        /// The seed used to stir the arc4 random source.
        /// The seed is not encoded through archiving, but the equivalent state buffers are encoded.
        #[unsafe(method(seed))]
        #[unsafe(method_family = none)]
        pub unsafe fn seed(&self) -> Retained<NSData>;

        /// Setter for [`seed`][Self::seed].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setSeed:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSeed(&self, seed: &NSData);

        /// Initializes an arc4 random source with bits from high entropy system resource like SecRandomCopyBytes.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Initializes an arc4 random source with bits from the seed.
        #[unsafe(method(initWithSeed:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithSeed(this: Allocated<Self>, seed: &NSData) -> Retained<Self>;

        /// Arc4 based random sources have repeatable initial sequences. If used for obfuscation you should
        /// drop N values from the start, where N should be any number larger than 768 to ensure the initial
        /// sequence is flushed.
        #[unsafe(method(dropValuesWithCount:))]
        #[unsafe(method_family = none)]
        pub unsafe fn dropValuesWithCount(&self, count: NSUInteger);
    );
}

/// Methods declared on superclass `GKRandomSource`.
impl GKARC4RandomSource {
    extern_methods!(
        /// Deserializes a random source from an NSCoder. All random sources support coding for serializing and deserializing the state
        /// of the random source. Each subclass has its own contract for what parts of the state is preserved when serialized but the
        /// general contract is that a serialized source must generate the same sequence of values as the original source would from the
        /// instant it was serialized.
        ///
        /// Note that the sharedRandom instance is an exception as it is explicitly seedless and a shared singleton instance.
        /// When serialized and deserialized it will return the current sharedRandom instance instead.
        ///
        /// # Safety
        ///
        /// `a_decoder` possibly has further requirements.
        #[unsafe(method(initWithCoder:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithCoder(this: Allocated<Self>, a_decoder: &NSCoder) -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKARC4RandomSource {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// A deterministic pseudo-random source that generates random numbers based on a linear congruential algorithm.
    /// This is a deterministic random source suitable for creating reliable gameplay mechanics.
    /// It is slightly faster than an Arc4 source, but less random. In particular the lower bits
    /// of the generated values are less random than the higher bits.
    ///
    /// While deterministic, this is not a cryptographic random source. It is also not suitable
    /// for obfuscation of gameplay data.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gklinearcongruentialrandomsource?language=objc)
    #[unsafe(super(GKRandomSource, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKLinearCongruentialRandomSource;
);

extern_conformance!(
    unsafe impl GKRandom for GKLinearCongruentialRandomSource {}
);

extern_conformance!(
    unsafe impl NSCoding for GKLinearCongruentialRandomSource {}
);

extern_conformance!(
    unsafe impl NSCopying for GKLinearCongruentialRandomSource {}
);

unsafe impl CopyingHelper for GKLinearCongruentialRandomSource {
    type Result = Self;
}

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

extern_conformance!(
    unsafe impl NSSecureCoding for GKLinearCongruentialRandomSource {}
);

impl GKLinearCongruentialRandomSource {
    extern_methods!(
        /// The seed used to stir the linear congruential random source.
        /// The seed changes each time a random value is generated from this source, as the seed is the state buffer.
        /// The seed is encoded through archiving.
        #[unsafe(method(seed))]
        #[unsafe(method_family = none)]
        pub unsafe fn seed(&self) -> u64;

        /// Setter for [`seed`][Self::seed].
        #[unsafe(method(setSeed:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSeed(&self, seed: u64);

        /// Initializes a linear congruential random source with bits from high entropy system resource like SecRandomCopyBytes.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Initializes a linear congruential random source with bits the given 64 bit seed.
        #[unsafe(method(initWithSeed:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithSeed(this: Allocated<Self>, seed: u64) -> Retained<Self>;
    );
}

/// Methods declared on superclass `GKRandomSource`.
impl GKLinearCongruentialRandomSource {
    extern_methods!(
        /// Deserializes a random source from an NSCoder. All random sources support coding for serializing and deserializing the state
        /// of the random source. Each subclass has its own contract for what parts of the state is preserved when serialized but the
        /// general contract is that a serialized source must generate the same sequence of values as the original source would from the
        /// instant it was serialized.
        ///
        /// Note that the sharedRandom instance is an exception as it is explicitly seedless and a shared singleton instance.
        /// When serialized and deserialized it will return the current sharedRandom instance instead.
        ///
        /// # Safety
        ///
        /// `a_decoder` possibly has further requirements.
        #[unsafe(method(initWithCoder:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithCoder(this: Allocated<Self>, a_decoder: &NSCoder) -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKLinearCongruentialRandomSource {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_class!(
    /// A deterministic pseudo-random source that generates random numbers based on a mersenne twister algorithm.
    /// This is a deterministic random source suitable for creating reliable gameplay mechanics.
    /// It is slightly slower than an Arc4 source, but more random, in that it has a longer period until repeating sequences.
    ///
    /// While deterministic, this is not a cryptographic random source. It is however suitable
    /// for obfuscation of gameplay data.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/gameplaykit/gkmersennetwisterrandomsource?language=objc)
    #[unsafe(super(GKRandomSource, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct GKMersenneTwisterRandomSource;
);

extern_conformance!(
    unsafe impl GKRandom for GKMersenneTwisterRandomSource {}
);

extern_conformance!(
    unsafe impl NSCoding for GKMersenneTwisterRandomSource {}
);

extern_conformance!(
    unsafe impl NSCopying for GKMersenneTwisterRandomSource {}
);

unsafe impl CopyingHelper for GKMersenneTwisterRandomSource {
    type Result = Self;
}

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

extern_conformance!(
    unsafe impl NSSecureCoding for GKMersenneTwisterRandomSource {}
);

impl GKMersenneTwisterRandomSource {
    extern_methods!(
        /// The seed used to stir the mersenne twister random source.
        /// The seed is not encoded through archiving, but the equivalent state buffers are encoded.
        #[unsafe(method(seed))]
        #[unsafe(method_family = none)]
        pub unsafe fn seed(&self) -> u64;

        /// Setter for [`seed`][Self::seed].
        #[unsafe(method(setSeed:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSeed(&self, seed: u64);

        /// Initializes a linear congruential random source with bits from a high entropy system resource like SecRandomCopyBytes.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Initializes a linear congruential random source with bits the given 64 bit seed.
        #[unsafe(method(initWithSeed:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithSeed(this: Allocated<Self>, seed: u64) -> Retained<Self>;
    );
}

/// Methods declared on superclass `GKRandomSource`.
impl GKMersenneTwisterRandomSource {
    extern_methods!(
        /// Deserializes a random source from an NSCoder. All random sources support coding for serializing and deserializing the state
        /// of the random source. Each subclass has its own contract for what parts of the state is preserved when serialized but the
        /// general contract is that a serialized source must generate the same sequence of values as the original source would from the
        /// instant it was serialized.
        ///
        /// Note that the sharedRandom instance is an exception as it is explicitly seedless and a shared singleton instance.
        /// When serialized and deserialized it will return the current sharedRandom instance instead.
        ///
        /// # Safety
        ///
        /// `a_decoder` possibly has further requirements.
        #[unsafe(method(initWithCoder:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithCoder(this: Allocated<Self>, a_decoder: &NSCoder) -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
impl GKMersenneTwisterRandomSource {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}