Leaving this here on a warm Tuesday evening

I’ve written here and there about my love of streams. I cover them a bit in the Swift Cookbook. Now that I’m updating it for Swift 3 via the Pearson Content Update Program, I have a little leeway to play around. I’m trying to expand the text with some fun new recipes.

Today, I wrote about “transformative streams”. A traditional stream, one that you write to with print(..., to:) is just a destination you write to such as stdout, stderr, or a file. A transformative stream fundamentally changes the text flowing through it. You can constrain text to all lowercase, or spell check it, or even print to your platform’s local notifications system.

I decided in this case to build a translation stream. It looks like you see in the following screenshot, converting English text to a foreign language when you print to the stream.

As you see in this screenshot, my solution leverages Swift’s built in standard library print function. Swift enables you to print to streams. When using my ItalianStream.shared stream, material printed to the console is automatically translated to the language provided by that stream.

In my implementation, I wanted to be able to hit a few key points:

• Any specific translation functionality needed to be decoupled from the printing stream so I could swap in and out various API providers without disrupting the implementation.
• I wanted to be able to use many languages.
• I had to offer a re-usable var member, which is required for stream printing.

To accomplish these goals, I decided to go heavily generic and protocol-oriented. I wanted to be able to slot in any language using a genericized stream type, which in turn would provide a shared stream instance for printing. If it sounds a little pretzel-y, it is.

The built-in standard library TextOutputStream protocol has precisely one requirement, a write method that accepts a string and does something with it.  In the code that follows, it translates the string and prints it out.

/// A text output stream that performs translation in
/// the process of printing
public struct TranslationStream<Language: EnglishTranslationProvider>: TextOutputStream {
    /// Writes the contents of the string to stdout after
    /// passing the string through an automatic translator
    public func write(_ string: String) {
        guard let translation = Language.translate(string) else { return }
        print(translation)
    }
}

The tricky bit is that my TranslationStream structure is generic. It  requires a type that conforms to EnglishTranslationProvider, allowing it to request a translation from that provider. Here’s what that protocol looks like:

/// A provider of string translations from English
public protocol EnglishTranslationProvider {
    /// Returns a shared instance of the provider
    static var shared: TranslationStream<Self> { get }

    /// Returns a translated string
    static func translate(_ string: String) -> String?
}

Each translation provider refers back to the TranslationStream type to  offer a shared translation stream to use when printing (you see this in the screenshot as ItalianStream.shared) and a translate method that returns a rendered version of the string. For example, here’s the implementation of my French provider type:

/// A stream type that automatically translates from English to French
public struct FrenchStream: EnglishTranslationProvider {
    /// Returns a shared instance of the provider
    public static var shared = TranslationStream<FrenchStream>()
    
    /// Returns a translated string
    public static func translate(_ string: String) -> String? {
        return FrenchStream.translate(string, language: "fr")
    }
}

Simple, right? There really isn’t much to it. It implements the two required members but otherwise delegates translation to a default translate method declared in a protocol extension.

My particular implementation takes a two-character language code and requests a translation from English via Google. I didn’t include the actual translate(_ string:, language:) method here because there are many competing APIs, which you can easily hook into, and they generally require both API keys and fees.

The important bit I’m trying to get across here is not “oh look, this translates” but rather “oh look, you can transform text by printing to streams”.  I thought the translation stream was a rather nice way to demonstrate how powerful this particular Swift feature could be.

In the following screenshot, I print (line 20) to a user notification.

Expanded my old shape code when porting to 3.0. Sample images here. Note that there’s a separate extension that allows UIKit Bezier calls on NSBezierPaths.

Just leaving this here.

I’ve filed a bug report about having to do non-generic implementations, which makes this a lot uglier than it needs to be. Jordan Rose wrote in response to my bug,

I’m pretty sure this is an overload ordering question, and I’m not convinced the compiler is wrong. If something is a more specific overload and marked unavailable, silently dropping back to the less-specific overload might be counterintuitive. (It also means the behavior of existing code could change silently if something is marked unavailable between releases.)

In any case, if you have any fixes or tweaks, as always please let me know and I’ll update.

So today, in the context of assembling color components, I decided that a hex value should always be padded to 2, 4, 8, 16, 32, or 64 characters when building out chunks.

Under this system, the number 256 should be “0100” and not “100”, representing the smallest standard memory footprint that will store the value. This allows chunks to be losslessly assembled together because there’s a consistent width for each component. If you need to use a larger padding value, you can re-pad to a larger minimum width.

While RGB colors come in 6’s, those are (in my opinion) three channels of 2-digit hex numbers, not a six-digit hex number.

Interesting things about this implementation:

• You have to use Swift.max because Int has its own max symbol.
• I was initially convinced to drop strtol() in favor of the built-in radix initializer, but this does do away with leading 0x support, which you have to strip yourself. (I did not include stripping in this implementation.) In my SwiftString repo, I’ve reverted to the old-style conversions.
• Greg T’s version with fls instead of my convoluted log2 stuff is vastly improved, so I’ve substituted it in-place here.
• My goal is to produce full-width number-chunks that can be assembled to represent components, whether for storing information, for channels, or for clarity in reading. An RGB group of (0xFF, 0x7, 0xFF) must be “FF07FF”, not “FF7FF”. So yes, there will be leading zeroes. If you want to interpret  output as numbers, use a canonical prefix (0x).

extension String {
    /// Left pads string to at least `minWidth` characters wide
    public func leftPad(_ character: Character, toWidth minWidth: Int) -> String {
        guard minWidth > characters.count else { return self }
        return String(repeating: String(character), 
            count: minWidth - characters.count) + self
    }
    
    /// Returns String's hex value
    /// - note: Non-compliant strings default to 0
    /// - note: An earlier version used strtol(), 
    ///   which accepts leading "0x". This does not.
    public var hexValue : Int { return Int(self, radix: 16) ?? 0 }
}

public extension Int {
    /// Returns Int's representation as hex string using 0-padding
    /// to represent the smallest standard memory footprint that can
    /// store the value.
    public var hexString : String {
        let unpaddedHex = String(self, radix:16, uppercase: true)
        let stringCharCount = unpaddedHex.characters.count
        // thanks, Greg Titus
        let desiredPadding = 1 << Swift.max(fls(Int32(stringCharCount - 1)), 1) 
        return unpaddedHex.leftPad("0", toWidth: Int(desiredPadding))
    }}
}

As always, corrections, improvements, suggestions welcome.

To find out the distance, say in days, between two dates, call a calendar’s dateComponents(_:, from: , to:) method and pass it the unit you want to use. This call returns a DateComponents instance. You can then find out how many days fall between the two by looking at the returned instance’s.day property.

But what if you want to write a more general method that returns the distance for pretty much any unit you throw at it, whether it be days, minutes, seconds, or years?

Either you can write a really complex switch statement or you can build an extension for DateComponents that allows you to subscript using any Calendar.Component. (Essentially performing the exact same switch statement but as a built-in feature.) And that is, exactly what I did today.

Here are my distance functions, which use subscripting to access the component information after pulling the distance from the shared calendar:

static public func distance(_ date1: Date, 
    to date2: Date, 
    component: Calendar.Component) -> Int {
    return Date.sharedCalendar
        .dateComponents([component], from: date1, to: date2)[component] ?? 0
}

public func distance(to date: Date, 
    component: Calendar.Component) -> Int {
    return Date.sharedCalendar
        .dateComponents([component], from: self, to: date)[component] ?? 0
}

The subscripting itself, along with a full refresh of my NSDate (well, Date now) utilities can be found at my github repo. This has been one of my more popular (and personally neglected) repositories that dates back almost a decade and I’m happy to say I’ve cleaned it up quite a bit while updating it to Swift.

I’m using a much better way to calculate “same” (for example, same date or same week) by creating a canonical form from the dates and then comparing the canonical versions. For dates, that’s midnight at the start of the day. For weeks, it’s midnight at the start of the week. (update: Sebastian Celis points out the existence of compare(_ date1: Date, to date2: Date, toGranularity component: Component), which is part of swift-corelibs-foundation)

I’ve added in quite a lot of formatter and string options, and doing this in Swift is a pure delight. (It’s a pity playgrounds don’t let you code using gyb-nastics. There’s a lot of redundancy in my code.)

All the date offsets are now much cleaner, and completely migrated to date components (as they should have been years ago).

As always, if you want any requests or changes, ping me now while I’m paying attention to this because my primary interest is migration to Swift and not dates per se. And thanks in advance for any feedback.