Rework Route type

[emma-k-alexandra]

Since v11 of WMATA.swift, Route has been a typealias for String. Prior to v11, Route was a struct, and before that Route was an enum similar to Station, and way, way back Route was actually a class.

There's been a lot of shifting to figure out what the right type for this rather simple piece of data is. I think today's String value is the closest to correct so far, but it still isn't quite satisfactory. Some sharp edges remain with Routes that I think can be alleviated.

A Route has two fundamental parts: The actual route and the variant. Examples:

Route values: A4, Z8 W2

Variants values: /*2, *4, /

Both values can change often as new routes and variants are introduced. Currently, the String value of Route handles these frequent changes. However, several of WMATA's APIs like Bus.Positions and Bus.Incidents do not allow for variants when calling them. This is documented, but it's still possible to call the APIs using routes with variants since Route is just a String.

Here, the package can improve developer experience. If Route was its own type with knowledge of the route value and the variant provided by the developer, the package could choose to use the correct Route information in each endpoint. This would move guidance from documentation into typed checks in code, which is almost always preferable.

Here's the type I think could work well for Route:

struct Route: Codable, RawRepresentable {
    var route: String
    var variant: String?

    init(_ route: String, variant: String? = nil) {
       ...
    }
    
    init?(rawValue: String) {
        ...
    }
}

Route(rawValue: "Z8*4")
Route("10A")
Route("Z8", variant: "*4")

I think it could be a pain to parse the routes coming out go WMATA's API into their two parts because the WMATA is super inconsistent about naming route variants.

Overall though, I think this struct would allow the package to help the developer more and more accurately represent what a Route actually is.

Any input welcome.