BEFoundation is an Objective-C framework that extends Apple's Foundation with utilities for notifications, runtime manipulation, number and data handling, image processing, data structures, file and path monitoring, security-scoped bookmarks, caching, and more. It is cross-platform (macOS and iOS) and ships as a Universal binary (arm64 + x86_64).
For full documentation, see the BEFoundation Documentation or the Documentation Index.
.package(url: "https://github.com/belisoful/BEFoundation.git", from: "1.2.0")or add it in Xcode via File ▸ Add Package Dependencies….
pod 'BEFoundation'Download an artifact below and drop it into your target.
The .xcframework is the recommended download: it carries macOS and iOS (device + simulator) in one binary, so a single artifact drops into any target. The plain .framework builds are macOS-only.
- BEFoundation.xcframework.zip v1.2.0 (macOS + iOS) — recommended, multi-platform
- BEFoundation.macos-arm-x86.framework.zip v1.2.0 (macOS Universal: arm64 x86_64)
- BEFoundation.macos-arm.framework.zip v1.2.0 (macOS arm64)
mutableUserInfoforNSNotificationNSPriorityNotification: Notifications with explicit priorityNSPriorityNotificationCenter: Dispatches notifications in priority order linked to NSNotificationCenter
BECharacterSetandBEMutableCharacterSet: Making a distinction betweenNSCharacterSetandNSMutableCharacterSet
BEPlatformTypes: compile-time aliases (BEColor,BEImage,BEFont,BEView) that resolve to the right AppKit/UIKit class per platform, so the same source builds on bothBEColor+BExtension: hex-string colors (#RGB/#RGBA/#RRGGBB/#RRGGBBAA) and appearance-aware dynamic colorsBEColor+BEWebColor: the 141 CSS/SVG color keywords as constants,web-prefixed properties, and name lookupsBEView+BExtension: Auto Layout helpers: pin to superview/view, center, and size constraintsBEImage+BExtension:CGImage/CIImageround-trips, PNG/JPEG export, pixel size, and aspect-aware resize (fit/fill)BEDotView: a status-indicator dot view (3D radial-gradient or flat), a port of Prado'sTDotNSPasteboard+BExtension(macOS): one-call typed read/write for strings, URLs, and images
BEMetalHelper: Metal helper utilities for converting MTLTextures to aBEImage(NSImage/UIImage), and grey data to XRGBCIImage+BExtension: overlay images with alpha, render text
BEMutable: Mutable and Collection classes have their own protocols for distinctionNSObject+DynamicMethods: Runtime extensions to add selectors implemented by blocks to specific objects and classesNSObject+Macroable: Laravel-inspired macro system for attaching block-based methods to classes and individual instances at runtime, built on top ofNSObject+DynamicMethodsBEObjectRegistry: Global object registry with weak references to track object lifetimesBESingleton: Singleton pattern macro
BEStackExtensions: Array-based Stack and Queue (pushObject:,popObject,shift)BEPriorityExtensions: Priority ordering extensions forNSArrayandNSOrderedSetFxTime: Immutable object to encapsulate CMTime and methods;FxMutableTimeadds read-write components and in-place arithmetic
BEPathWatcher: Path watcher class to observe file system changes
NSURL+Data: create and readdata:-scheme URLsBEWebData: read a resource through one interface, whether it is adata:URL, anhttp(s)download, or a local fileNSData+URLDownload: download remote data in memory or to a temporary fileBEFileCache: a two-tier cache, anNSCachememory tier over a durable on-disk tier indexed for O(1) cold start, with count/cost limits,NSDiscardableContentawareness, crash-safe reconciliation at launch, a score-driven eviction policy (last-access recency,retentionCost, and anevictionBalancedial between age and value density), and caller-defined entry file naming (fileNameBlock)BESecurityScopedURLManager: create, resolve, and manage the access lifecycle of security-scoped bookmarks
NSCoder+AtIndex: Indexed encoding/decoding with key control (string or numeric)NSCoder+HalfFloat: 16-bit float encoding/decodingNSMutableNumber: Mutable variant ofNSNumberNSNumber+Primes16b: Contains all 16-bit prime numbers with roundingNSDateFormatterRFC3339: Proper RFC 3339 date formatting initialization and settingNSDateFormatterRFC2822: Fixed-format RFC 2822 (Internet Message Format) date formatting initialization and setting
BEPredicateRule: Evaluation system that can accept, reject, or remain neutral based on predicate evaluation
NSObject+DynamicMethods: Dynamic protocol conformance implemented by objects and classes- Extensions for:
NSDictionary+BExtension: numeric subscripts, object conversion, mapping, swapping, adding, and mergingNSMutableDictionary: numeric subscripts, filtering, swap, and recursive and nonrecursive adding and mergingNSArray+BExtension: mapping, and conversionNSMutableArray:removeFirstElement,insertElementsOfArray:atIndex:, and filteringNSSet+BExtension: conversion, and mappingNSMutableSet: filteringNSOrderedSet+BExtension: conversion, and mappingNSMutableOrderedSet: conversion,removeFirstElement/removeLastElement, and filteringNSString+BExtension:stringValuereturns the receiver itself, aligning withNSNumberand other plist data typesNSMutableString: deleteAtIndex
BEFoundation ships unit tests for all major components, using XCTest, covering behavior, edge cases, runtime behaviors, and error conditions. The suite runs parallelized across test workers. Continuous integration runs it on macOS (arm64), the macOS x86_64 slice, and the iOS Simulator, plus an AddressSanitizer pass, a DocC catalog build, xcodebuild analyze, pod lib lint, a SwiftPM build, a category-collision check, and builds under the newest Xcode 26 and under Xcode 27. In v1.1, coverage was extended to NSObject+Macroable (67 tests covering BEMacroMeta, class macros, object macros, invocation, isolation, and subclass inheritance).
- Download the BEFoundation.framework ZIP file for your project.
- Unzip the file.
- Include the BEFoundation.framework in your Project Target under the General Tab and "Framework and Libraries" section.
- Under the "Embed" dropdown select "Embed & Sign" or "Embed Without Signing".
- Import the Headers you'd like to use.
- Clone or download this repository.
- Add the
BEFoundationsource folder to your Xcode project. - Link against required frameworks:
Foundation,CoreImage,Metal, etc. - Ensure ARC is enabled (where applicable).
BEFoundation was initially conceived and engineered by belisoful@icloud.com to resolve the lack of [NSString stringValue] and implementing a selector for an object (and instances) with a block. These requirements came about in working with Apple's FxPlug API in developing an advanced framework around it. The FxPlug buttons require an object method be implemented per button which is not directly possible in Objective C. The buttons need to be parameterized for an FxPlug framework.
- http://gcpdot.com Fully created by @belisoful in about year 2000.
- https://github.com/pradosoft/prado Implementing Advanced Features like the TCronModule.
-
Behavior change: the deployment minimums rise to macOS 12.0 and iOS 15.0 (from 11.0 and 14.0). Xcode 27 accepts nothing lower, and the project builds without overrides again. Update
platformsin your package manifest or podspec if you pinned the old floor. -
Release binaries are attached to each GitHub Release only; the
Framework Releasefolders are no longer committed. -
Fix:
NSObject+MacroableandNSObject+DynamicMethodsno longer deadlock when a macro is registered while another thread dispatches on the same class; cross-class lookups take the owning class's lock, dispatch validates the invocation signature, and re-registering an instance protocol with a different class reaches already-synced objects. See FIXES.md. -
Fix:
BESecurityScopedURLManagerstops access on the NSURL instance that started it, so the sandbox extension is released;removeURLFromCatalog:ends the whole session. The newinitWithStorageIdentifier:gives private instances their own persisted catalog. -
Fix:
NSPriorityNotificationCenterno longer serializes observer call-outs on the notification'suserInfo. Behavior change: onlydefaultCenterbridges toNSNotificationCenter.defaultCenter; a center created withinitis self-contained. -
Fix:
BEFileCachedecodes payloads with secure coding. The newallowedClassesproperty admits customNSSecureCodingclasses; the payload's root class is recorded in the.metasidecar. -
Fix:
NSNumber+Primes16bnever returns 1 as a prime.NSDictionary+BExtensionrecursive merge and add descend into immutable nested dictionaries by default.NSNumber+BExtensionfollows IEEE 754 for floating divide-by-zero, returns NaN on integer overflow, and raises on a nil operand. -
Fix:
BEDotViewapplies its defaults on theinitWithCoder:path, accepts#RGBshorthand, rejects malformed hex, and keeps explicit color overrides across a depth change.BEWindowControllersurvives-closewhen its manager is the sole owner. -
Fix:
NSURL+Datais the single data-URL parser;BEWebDatareads from it, so both APIs agree on case-insensitive and quoted parameters, whitespace in base64, and the default charset.+charsetFromMediaType:applies the same rules to an HTTPContent-Type.BEWebDatafrees a no-copy buffer through its deallocator. -
Fix:
BEColor webColorNamed:resolves the seven CSSgreyspellings;colorWithHexString:rejects a doubled prefix such as#0x1234.FxTimeandBECharacterSetfail a malformed secure-coded archive instead of decoding zeros.BEPredicateRulefactories returninstancetypeand a nil predicate raises. -
Behavior change (Swift):
BECharacterSet,BEObjectRegistry, andBEUniversalObjectRegistrydeclareinitnonnull, so Swift importsinit()in place ofinit?(). -
Fix:
BEObjectRegistryre-keying an object's UUID from a same-salt registry keeps the other registry's entry.BESecurityScopedURLManagerfast enumeration works across calls.BEPathWatchercloses the descriptor and returns NO when its dispatch source cannot be created.NSNotification+ExtraPropertiesdeclaresidentifierascopy, matching its setter.NSData+URLDownloadclamps theContent-Lengthallocation hint to 16 MB.BEDotViewsetters are safe under MRC and the class releases its ivars indealloc. -
BESecurityScopedURLManagerTestsnow runs on iOS. -
NSMutableNumberis re-vendored from upstream v1.3.1, which compiles without warnings on Xcode 27. -
The podspec license now reads
Public Domain, matchingLICENSE.
- Fix:
NSPriorityNotificationCenterno longer crashes on notifications whoseobjectis a non-object pointer. SceneKit posts such notifications throughCFNotificationCenterPostNotification; the object is now read unretained, and super-center notifications reach queued observers unchanged. See FIXES.md.
Cross-Platform (iOS & macOS)
- The framework now builds and is unit-tested on both iOS and macOS.
BEPlatformTypesprovides compile-time aliases (BEColor,BEImage,BEFont,BEView) that resolve to the right AppKit/UIKit class per platform. - Distributed as a multi-platform
BEFoundation.xcframework(macOS, iOS device, iOS simulator) alongside the macOS-only.frameworkbuilds. - Installable through Swift Package Manager and CocoaPods. Public headers moved to
Sources/BEFoundation/include/BEFoundation/, so#import <BEFoundation/Foo.h>resolves the same way for SwiftPM, CocoaPods, and the built framework. BEColor+BEWebColor: the 141 CSS/SVG color keywords asBEWebColorName…constants andweb-prefixed class properties, with case-insensitive name lookup and exact reverse lookup.BEDotView: a cross-platform status-indicator dot (3D or flat), a Core Graphics port of Prado'sTDot.BEColor+BExtension: hex-string colors and appearance-aware dynamic colors.BEView+BExtension: Auto Layout convenience constraints (pin, center, size).BEImage+BExtension:CGImage/CIImageround-trips, PNG/JPEG export, pixel size, and aspect-aware resizing.- Behavior change: the
BEImage+BExtensionround-trip and data members are renamed to representation-style names:CGImageRepresentation,CIImageRepresentation,imageFromCGImage:,imageFromCIImage:,pngRepresentation,jpegRepresentationWithCompressionQuality:. Apple frameworks attach same-named category methods toNSImageat runtime (PencilKit adds a private+[NSImage imageWithCGImage:]and-CGImage), and which duplicate wins is undefined, so the 1.0 UIImage-parity spellings were unsafe.pixelSizeand theresizedTo…members keep their names. The round-trip members are also available on iOS now, and the factories returnnilforNULL/nilinput on both platforms. NSPasteboard+BExtension(macOS): typed read/write for strings, URLs, and images.
Foundation & Networking
- NSNotification+ExtraProperties adds tag and identifier if the notification object has such properties or are set in the NSNotification
- NSString (CharacterCounter) category for counting characters of a NSString.
NSURL+Data: categories for creating and reading "data" scheme NSURL.BEWebData: for decoding a "data" scheme within NSURL, download "http/s" files, or read file system files.NSData+URLDownload: for easy download of internet data via in-memory or temporary file.BEFileCache: persistent two-tier (memory + disk) caching with count/cost limits, crash-safe reconciliation at launch, a configurable score-driven eviction policy (retentionCost+evictionBalance), and caller-defined entry file naming (fileNameBlock).BESecurityScopedURLManager: security-scoped bookmark lifecycle management.NSDateFormatterRFC2822: fixed-format RFC 2822 (Internet Message Format) date formatter for email-style dates.NSObject+Macroable: Macro system for attaching block-based methods to a class (available on all instances) or to a specific object instance at runtime, built onNSObject+DynamicMethods.FxTimeis now immutable and thread-safe. The newFxMutableTimesubclass carries the read-write components and in-place arithmetic; code that mutated anFxTimemust now useFxMutableTime.-copyreturns an immutableFxTime;-mutableCopyreturns anFxMutableTime.- Behavior change:
FxTime-compare:/-compareTime:now follow the CocoaNSComparisonResultconvention. The result sign is inverted versus 1.0; code that compensated for the old inversion must drop the workaround. - Behavior change:
NSCoder+AtIndex.hno longer imports<simd/simd.h>(it was unused). Clients that relied on the transitive include through the umbrella header must import<simd/simd.h>themselves.
Behavior change: category methods renamed off Apple's private selectors
Apple attaches private categories to Foundation classes at runtime, and when a BEFoundation category defined the same selector the runtime picked a winner by image load order. The build emits no diagnostic; a collision surfaces as an intermittent test failure. Every colliding selector is renamed; the behavior is unchanged.
| 1.0 | 1.1 | Collided with |
|---|---|---|
-[NSMutableArray push:], -pop |
-pushObject:, -popObject |
OSAnalytics (its push: returns nil, breaking chaining) |
-[NSMutableOrderedSet push:], -pop |
-pushObject:, -popObject |
— (renamed with the array pair for symmetry) |
-removeFirstObject, -removeLastObject |
-removeFirstElement, -removeLastElement |
CoreFoundation |
-[NSMutableArray insertObjects:atIndex:] |
-insertElementsOfArray:atIndex: |
ScreenReaderCore |
setSet:, setOrderedSet:, setArray: setters |
be_setSet:, be_setOrderedSet:, be_setArray: |
CoreFoundation |
isMutable (class and instance) |
hasMutability |
Foundation's private per-instance predicate on every NSCharacterSet |
The set, orderedSet, and array properties keep their names; only the setter selectors
changed, so dot syntax (array.set = value) is unaffected. Scripts/check-category-collisions.sh
now fails the build if any category selector reappears on an Apple class; it runs in CI.
Behavior change: queued priority-notification observers
An observer registered with an NSOperationQueue now receives a plain NSPriorityNotification
it may retain indefinitely. Previously it received a pooled object that was recycled the moment
the handler returned, so a retained notification's name, object, and userInfo went nil and
were later overwritten by an unrelated post. NSPooledPriorityNotification is removed; it was
also measurably slower than plain allocation under concurrent posting.
Behavior change: NSMutableNumber is a genuine NSNumber subclass
NSMutableNumber now inherits from NSNumber. isKindOfClass: reports
NSNumber, equality with a plain NSNumber is symmetric, CFNumberRef bridging works, and
inherited API such as decimalValue returns a value instead of raising. Vendored from the
standalone NSMutableNumber v1.3.0.
AppKit
BEPathControl: an NSPathControl that displays paths relative to a sub-directory.BETabView: a drop-in NSTabView replacement that supports hidden tabs.BEWindowController: a drop-in NSWindowController replacement with parent/child window-controller relationships and awindowDidLoadnotification.BEWindowControllerManager: an application singleton that tracks window controllers and closes children when a parent closes.