Line data    Source code

       1           0 : /*
       2             : 
       3             : OOProbabilitySet.h
       4             : 
       5             : A collection for selecting objects randomly, with probability weighting.
       6             : Probability weights can be 0 - an object may be in the set but not selectable.
       7             : Comes in mutable and immutable variants.
       8             : 
       9             : Performance characteristics:
      10             :   *     -randomObject, the primary method, is O(log n) for immutable
      11             :         OOProbabilitySets and O(n) for mutable ones.
      12             :   *     -containsObject: and -probabilityForObject: are O(n). This could be
      13             :         optimized, but there's currently no need.
      14             : 
      15             : 
      16             : Copyright (C) 2008-2013 Jens Ayton
      17             : 
      18             : Permission is hereby granted, free of charge, to any person obtaining a copy
      19             : of this software and associated documentation files (the "Software"), to deal
      20             : in the Software without restriction, including without limitation the rights
      21             : to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
      22             : copies of the Software, and to permit persons to whom the Software is
      23             : furnished to do so, subject to the following conditions:
      24             : 
      25             : The above copyright notice and this permission notice shall be included in all
      26             : copies or substantial portions of the Software.
      27             : 
      28             : THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      29             : IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      30             : FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      31             : AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      32             : LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      33             : OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      34             : SOFTWARE.
      35             : 
      36             : */
      37             : 
      38             : #import "OOCocoa.h"
      39             : 
      40             : 
      41           0 : @interface OOProbabilitySet: NSObject <NSCopying, NSMutableCopying>
      42             : 
      43           0 : + (id) probabilitySet;
      44           0 : + (id) probabilitySetWithObjects:(id *)objects weights:(float *)weights count:(NSUInteger)count;
      45           0 : + (id) probabilitySetWithPropertyListRepresentation:(NSDictionary *)plist;
      46             : 
      47           0 : - (id) init;
      48           0 : - (id) initWithObjects:(id *)objects weights:(float *)weights count:(NSUInteger)count;
      49           0 : - (id) initWithPropertyListRepresentation:(NSDictionary *)plist;
      50             : 
      51             : // propertyListRepresentation is only valid if objects are property list objects.
      52           0 : - (NSDictionary *) propertyListRepresentation;
      53             : 
      54           0 : - (NSUInteger) count;
      55           0 : - (id) randomObject;
      56             : 
      57           0 : - (float) weightForObject:(id)object;   // Returns -1 for unknown objects.
      58           0 : - (float) sumOfWeights;
      59           0 : - (NSArray *) allObjects;
      60             : 
      61             : @end
      62             : 
      63             : 
      64             : @interface OOProbabilitySet (OOExtendedProbabilitySet)
      65             : 
      66           0 : - (BOOL) containsObject:(id)object;
      67           0 : - (NSEnumerator *) objectEnumerator;
      68           0 : - (float) probabilityForObject:(id)object;      // Returns -1 for unknown objects, or a value from 0 to 1 inclusive for known objects.
      69             : 
      70             : @end
      71             : 
      72             : 
      73           0 : @interface OOMutableProbabilitySet: OOProbabilitySet
      74             : 
      75           0 : - (void) setWeight:(float)weight forObject:(id)object;  // Adds object if needed.
      76           0 : - (void) removeObject:(id)object;
      77             : 
      78             : @end