riftvalleysoftware/rvs_generic_swift_toolbox

A Set of utilities to ease basic and repetitive tasks, in Swift.

Overview

This repository is an Xcode project with a set of ambidextrous (That's what I really mean by "generic"; not just using generics) tools that can be applied to Swift projects deployed for iOS, iPadOS, MacOS, WatchOS and TVOS.

These tools will work for all of these platforms, and will, at most, rely only on the Foundation library, and the Core Graphics types (in the Core Foundation Library).

COLLECTION TOOLS

- RVS_FIFOQueue

This is a high-performance generic FIFO queue data structure. It's based on the work of Ole Begemann, who used it as an example in his Advanced Swift book.

- RVS_SequenceProtocol

This is a simple protocol that gives classes and structs that conform to it, some basic Sequence behavior.

- RVS_WeakObjectReference

This is a simple weak reference hashable container, which allows us to have collections of weak references (normally, membership in a collection creates a strong link).

DEBUG TOOLS

- RVS_DebugTools

This is a set of tools used to aid debugging and testing code.

EXTENSIONS

- RVS_Number_Extensions

Extensions to integer data types, as well as some degree/radian conversion for floats and doubles.

- RVS_Bundle_Extensions

Extensions to the Foundation Bundle.

- RVS_String_Extensions

Extensions to the StringProtocol protocol. These are mostly parsing, filtering, and conversion capabilities.

- RVS_Foundation_Extensions

Extensions to the StringProtocol protocol. This adds some significant capabilities, such as MD5/SHA-hashing, substring searching, simple localization, and basic parsing.

Adds degree/radian conversion to CGFloat.

Adds rotation support to CGPoint.

IP ADDRESS PARSING

- RVS_IPAddress

A set of simple tools for parsing and formatting IPv4 and IPv6 addresses. This was originally the RVS_IPAddress project.

Usage

Swift Package Manager (SPM)

You can use SPM to load the project as a dependency, by referencing its GitHub Repo URI (SSH: git@github.com:RiftValleySoftware/RVS_Generic_Swift_Toolbox.git, or HTTPS: https://github.com/RiftValleySoftware/RVS_Generic_Swift_Toolbox.git).

Once you have the dependency attached, you reference it by adding an import to the files that consume the package:

import RVS_Generic_Swift_Toolbox

All of the extensions and utilities will be available.

Carthage

Carthage is probably the "lowest-overhead" way to use these tools. It's extremely simple to use, and squeaky clean. You will only need to include references to the files into your project. You implement it by adding the following line in your Cartfile:

github "RiftValleySoftware/RVS_Generic_Swift_Toolbox"

Once you have done this, navigate the Terminal to the directory containing the Cartfile, and execute:

carthage update

This will result in a directory, at the same level as the Cartfile, called Carthage. Inside of that directory, will be another directory, called Checkouts. Inside of that directory, will be a directory called RVS_Generic_Swift_Toolbox. The files that you are looking for will be in the Sources/RVS_Generic_Swift_Toolbox directory. They are arranged in the grouping they are documented, above.

Just drag those files into your Xcode project, and add them to the appropriate targets.

If you choose to use the build products, be aware that Carthage builds may not always sign the modules, so you could have issues submitting to the app store.

Git Submodule

You could also directly include the project as a Git Submodule. Submodules can be annoying to work with, but are a good way to maintain ironclad version integrity. If you do this, then you should do the same as above, but instead of a Carthage directory, you will have whatever directory you choose to use to place the submodule.

Behavior and Boundary Values

Collections: Queue indexes start at 0, and endIndex is one past the last element. Enqueueing, dequeueing, and cutting the line can be mixed with iteration and subscripting. Weak object references retain their identity and hash after the object is released; references to different objects remain different.
Integer Tools: maskedValue(firstPlace:runLength:) uses 0-based bit positions and the width of the receiving integer. Invalid ranges return 0. Signed values are treated as bit patterns, and a full-width mask preserves the sign. Roman numerals support values from 1 through 4999, including values stored in smaller integer types.
Hex Conversion: hex2Int returns nil when the filtered number exceeds Int.max. hex2UTF8 accepts both Strings and Substrings, and maps each hex byte directly to the same-valued Unicode scalar. Despite its historical name, it does not decode multi-byte UTF8 sequences.
IP Addresses: Malformed elements, shortcuts, brackets, and port suffixes are rejected. IPv6 accepts hexadecimal elements and :: compression; IPv4-embedded and scoped IPv6 strings are not supported. Port values retain the existing behavior of accepting nonnegative values representable by Int; callers using TCP or UDP should also check the 0...65535 range. A port of 0 means no port in formatted output.
Byte Arrays: The ContiguousBytes array accessors accept unaligned input, preserve native byte order, and ignore incomplete trailing values.
String Validation: isAValidEmailAddress is a basic format check, not a complete email-address parser. urlEncodedString uses the allowed characters for an entire URL query; characters such as & and = remain unescaped. Use URLComponents and URLQueryItem when assembling individual query parameters.

Localization

The localizedVariant property searches the main bundle's Accessibility, Errors, and Localizable tables, in that order. Strings and Substrings are both supported. A missing translation returns the original key.

Frameworks and tests can supply their own bundle:

let translated = "Greeting".localizedVariant(bundle: myBundle)

Bundle.supportedLanguages(in:) lists localizations without Base, and preserves script and region subtags. Supply a display locale to name all languages in that locale, or omit it to show each language in its own language.

Testing

On MacOS, run the XCTest suite in both build configurations:

swift test swift test -c release

The shared Xcode scheme also runs the tests on the supported Apple platforms. Its MacOS test target requires MacOS 14 or later, matching the XCTest frameworks in the current Xcode toolchain. The library retains its existing deployment targets. Tests create their own temporary bundles for metadata and localization, so these checks do not depend on the test runner's main bundle.

Requirements

These utilities require Swift 5.7 or later, along with the Foundation Library (it also uses the Core Foundation Library, which, for some reason, is treated separately, in iOS).

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Package Metadata

Repository: riftvalleysoftware/rvs_generic_swift_toolbox

Default branch: master

README: README.md