Module cacao::foundation

This module contains some lightweight wrappers over Foundation data types.

Some of it is pulled/inspired from Servo’s cocoa-rs (e.g, the “id” type). While this isn’t a clone of their module (we don’t need everything from there, but remaining compatible in case an end-user wants to drop that low is deal), it’s worth linking their license and repository - they’ve done really incredible work and it’s 100% worth acknowledging.

• core-foundation-rs Repository
• core-foundation-rs MIT License
• core-foundation-rs Apache License

Why?

A good question. The existing wrappers tend to use traits over id, which works well for some cases, but I found it frustrating and messy trying to work with them. These provide the API I was looking for, and help provide all the proper retain/release logic needed for the Objective-C side.

Structs

AutoReleasePool

A wrapper around NSAutoReleasePool. The core App structures create and manage one of these, but it’s conceivable that users might need to create their own.

NSArray

A wrapper for NSArray that makes common operations in our framework a bit easier to handle and reason about. This also provides a central place to look at replacing with CFArray if ever deemed necessary (unlikely, given how much Apple has optimized the Foundation classes, but still…).

NSData

Wrapper for a retained NSData object.

NSMutableDictionary

A wrapper for NSMutableDictionary.

NSNumber

Wrapper for a NSNumber object.

NSString

A wrapper for NSString.

NSURL

Wraps NSURL for use throughout the framework.

Enums

NSURLBookmarkCreationOption

Options used when creating bookmark data.

NSURLBookmarkResolutionOption

Options used when resolving bookmark data.

Constants

NO

The equivalent of false for Objective-C’s BOOL type.

YES

The equivalent of true for Objective-C’s BOOL type.

nil

Exactly what it sounds like.

Functions

load_or_register_class

Attempts to load a subclass, given a superclass_name and subclass_name. If the subclass cannot be loaded, it’s dynamically created and injected into the runtime, and then returned. The returned value can be used for allocating new instances of this class in the Objective-C runtime.

to_bool

Bool mapping types differ between ARM and x64. There’s a number of places that we need to check against BOOL results throughout the framework, and this just simplifies some mismatches.

Type Definitions

BOOL

The Objective-C BOOL type.

NSInteger

Platform-specific.

NSUInteger

Platform-specific.

id

More or less maps over to Objective-C’s id type, which… can really be anything.