CHSortedDictionary Class Reference

A dictionary which enumerates keys according to their natural sorted order. More...

#import <CHSortedDictionary.h>

Inheritance diagram for CHSortedDictionary:
Inheritance graph
[legend]
Collaboration diagram for CHSortedDictionary:
Collaboration graph
[legend]

List of all members.

Public Member Functions

(NSArray *) - allKeys [implementation]
 Returns an array containing the receiver's keys in sorted order.
(BOOL) - lockBeforeDate: [implementation]
 Attempts to acquire a lock before a given time and returns whether the attempt was successful.
(BOOL) - tryLock [implementation]
 Attempts to acquire a lock and immediately returns whether the attempt was successful.
(void) - unlock [implementation]
 Relinquishes a previously acquired lock.
Querying Contents

(id) - firstKey
 Returns the minimum key in the receiver, according to natural sorted order.
(id) - lastKey
 Returns the maximum key in the receiver, according to natural sorted order.
(NSMutableDictionary *) - subsetFromKey:toKey:options:
 Returns a new dictionary containing the entries for keys delineated by two given objects.
Locks and Synchronization

(void) - lock
 Attempts to acquire a lock, blocking a thread's execution until the lock can be acquired.

Detailed Description

A dictionary which enumerates keys according to their natural sorted order.

The following additional operations are provided to take advantage of the ordering:

Key-value entries are inserted just as in a normal dictionary, including replacement of values for existing keys, as detailed in -[NSMutableDictionary setObject:forKey:]. However, an additional CHSortedSet structure is used in parallel to sort the keys, and keys are enumerated in that order.

Implementations of sorted dictionaries (aka "maps") in other languages include the following:

Note:
Any method inherited from NSDictionary or NSMutableDictionary is supported, but only overridden methods are listed here.
See also:
CHSortedSet

Member Function Documentation

- (NSArray *) allKeys   [implementation]

Returns an array containing the receiver's keys in sorted order.

Returns:
An array containing the receiver's keys in sorted order. The array is empty if the receiver has no entries.
See also:
- allValues
- count
- keyEnumerator
- (id) firstKey  

Returns the minimum key in the receiver, according to natural sorted order.

Returns:
The minimum key in the receiver, or nil if the receiver is empty.
See also:
- lastKey
- (id) lastKey  

Returns the maximum key in the receiver, according to natural sorted order.

Returns:
The maximum key in the receiver, or nil if the receiver is empty.
See also:
- firstKey
- (void) lock  

Attempts to acquire a lock, blocking a thread's execution until the lock can be acquired.

An application protects a critical section of code by requiring a thread to acquire a lock before executing the code. Once the critical section is past, the thread relinquishes the lock by invoking unlock.

Warning:
Calling -lock on NSLock twice from the same thread will lock the thread permanently. Use NSRecursiveLock for recursive locks.
See also:
CHLockable
NSLocking protocol

Reimplemented from <NSLocking>.

- (BOOL) lockBeforeDate: (NSDate *)  limit   [implementation]

Attempts to acquire a lock before a given time and returns whether the attempt was successful.

The thread is blocked until the receiver acquires the lock or limit is reached.

Parameters:
limit The time limit for attempting to acquire a lock.
Returns:
YES if the lock was acquired before limit, otherwise NO.
See also:
CHLockable

Reimplemented from <CHLockable>.

- (NSMutableDictionary *) subsetFromKey: (id)  start
toKey: (id)  end
options: (CHSubsetConstructionOptions)  options 

Returns a new dictionary containing the entries for keys delineated by two given objects.

The subset is a shallow copy (new memory is allocated for the structure, but the copy points to the same objects) so any changes to the objects in the subset affect the receiver as well. The subset is an instance of the same class as the receiver.

Parameters:
start Low endpoint of the subset to be returned; need not be a key in receiver.
end High endpoint of the subset to be returned; need not be a key in receiver.
options A combination of CHSubsetConstructionOptions values that specifies how to construct the subset. Pass 0 for the default behavior, or one or more options combined with a bitwise OR to specify different behavior.
Returns:
A new sorted map containing the key-value entries delineated by start and end. The contents of the returned subset depend on the input parameters as follows:
  • If both start and end are nil, all keys in the receiver are included. (Equivalent to calling -copy.)
  • If only start is nil, keys that match or follow start are included.
  • If only end is nil, keys that match or preceed start are included.
  • If start comes before end in an ordered set, keys between start and end (or which match either object) are included.
  • Otherwise, all keys except those that fall between start and end are included.
- (BOOL) tryLock   [implementation]

Attempts to acquire a lock and immediately returns whether the attempt was successful.

Returns:
YES if the lock was acquired, otherwise NO.
See also:
CHLockable

Reimplemented from <CHLockable>.

- (void) unlock   [implementation]

Relinquishes a previously acquired lock.

Warning:
NSLock uses POSIX threads to implement its locking behavior. When sending an -unlock message to an NSLock object, you must be sure that message is sent from the same thread that sent the initial -lock message. Unlocking a lock from a different thread can cause undefined behavior.
See also:
CHLockable
NSLocking protocol

Reimplemented from <CHLockable>.

The documentation for this class was generated from the following files:
Generated by  doxygen 1.6.2