NSProgress

[hartbit]

I've started working on NSProgress because it seems easy enough for me to implement. Here's what I've done so far:

• Updated to the new API naming (beta 1)
• Implemented basic completedUnitCount, totalUnitCount, fractionCompleted

[hartbit]

First question for @parkera (or anybody else who can answer): are we allowed to make very small API modifications? For example, I was envisioning moving some string values into enums with raw value strings:

public let NSProgressFileOperationKindDownloading: String = "NSProgressFileOperationKindDownloading"
public let NSProgressFileOperationKindDecompressingAfterDownloading: String = "NSProgressFileOperationKindDecompressingAfterDownloading"
public let NSProgressFileOperationKindReceiving: String = "NSProgressFileOperationKindReceiving"
public let NSProgressFileOperationKindCopying: String = "NSProgressFileOperationKindCopying"

Would become:

public enum NSProgressFileOperationKind: String {
    case downloading = "NSProgressFileOperationKindDownloading"
    case decompressingAfterDownloading = "NSProgressFileOperationKindDecompressingAfterDownloading"
    case receiving = "NSProgressFileOperationKindReceiving"
    case copying = "NSProgressFileOperationKindCopying"
}

Its more of a "namespacing" change really.

[parkera]

For now, let's leave the API identical to the one in Foundation. That will make it easier to update in the future. You probably already noticed that the swift-evolution "drop NS" proposal listed this particular enum as being hoisted into the Progress class itself anyway. More details on that will be available a little bit later.

[hartbit]

@parkera Ok, sounds great. One extra question:

Objective-C Foundation has NSProgress.init() defined, but it's inheriting it from NSObject. I guess we should add an init definition in NSProgress to have identical APIs. Correct?

EDIT: They were originally two questions, but I figure it out on my own ^^

[hartbit]

@parkera New question :) The comments for isIndeterminate say:

Whether the progress being made is indeterminate. -isIndeterminate returns YES when the value of the totalUnitCount or completedUnitCount property is less than zero. Zero values for both of those properties indicates that there turned out to not be any work to do after all; -isIndeterminate returns NO and -fractionCompleted returns 1.0 in that case. NSProgress is by default KVO-compliant for these properties, with the notifications always being sent on the thread which updates the property.

But after unit-testing Darwin Foundation, fractionCompleted does not return 1.0 when both totalUnitCount and completedUnitCount are equal to 0, it actually returns 0.0:

progress.completedUnitCount = 0
progress.totalUnitCount = 0
XCTAssertEqual(progress.fractionCompleted, 0)

I guess I should follow the implementation rather than the documentation?

[parkera]

I think I had to change the definition of isIndeterminate at some point in the ObjC version. Here is what it uses:

// An uninitialized NSProgress ( completed == total == 0 ) is not finished, it is indeterminate
return _completed < 0 || _total < 0 || (_completed == 0 && _total == 0);

[parkera]

as described in the other comment:

completedUnitCount < 0 || totalUnitCount < 0 || (completedUnitCount == 0 && totalUnitCount == 0)

[parkera]

by the way, isFinished is:

((_completed >= _total) && _completed > 0 && _total > 0) || (_completed > 0 && _total == 0);

[parkera]

This is a great start.

[hartbit]

@parkera I've taken up work on Progress again. I've started by adapting to the new APIs, and doing some documentation at the same time.

Is it OK to copy/paste some documentation from https://developer.apple.com/reference/foundation/nsprogress ?

[hartbit]

Other questions:

• I saw that localizedDescription and localizedAdditionalDescription return a IUO String even if their documentation states that they return an empty string when they can't compute a description. I think that's a relic from the Objective-C headers not having the nullability attributes. I transformed those into straight Strings. Any complaints?
• Some functions have weird looking secondary parameter labels like func addChild(_ child: Progress, withPendingUnitCount inUnitCount: Int64)'s inUnitCount. As those are only used in the documentation and are not part of the signature of the function, I modified them to be more natural. Any complaints?

[hartbit]

I saw that localizedDescription and localizedAdditionalDescription return a IUO String even if their documentation states that they return an empty string when they can't compute a description. I think that's a relic from the Objective-C headers not having the nullability attributes. I transformed those into straight Strings. Any complaints?

In fact, after more consideration, this is a weird case. Technically, if I want to be 100% compatible, I can't remove the IUO because the property's setter is public: I can set the localizedDescription to nil under Darwin Foundation. Which makes no sense. And doesn't even do anything because the getter still returns the precomputed value. This is an API issue. To be correct, the property should become a computed property (or have its setter made private) on Darwin Foundation. But I don't know if that's possible.

[parkera]

The documentation is a bit misleading - these should never return an empty string. They are not really IOU, they are null-resettable.

[parkera]

@hartbit Thanks for getting this started. I went ahead and finished it up in #679.