swift - What Does The relative(to:) Function Actually Do? -

this swift standard library documentation:

relative(to:)

returns range of indices within given collection described range expression.

here method signature:

func relative<c>(to collection: c) -> range<self.bound> c : _indexable, self.bound == c.index 

along explanation:

parameters

collection

the collection evaluate range expression in relation to.

return value

a range suitable slicing collection. returned range not guaranteed inside bounds of collection. callers should apply same preconditions return value range provided directly user.

finally, here test code:

let continuouscollection = array(0..<10) var range = 0..<5 print(range.relative(to: continuouscollection)) //0..<5 range = 5..<15 print(range.relative(to: continuouscollection)) //5..<15 range = 11..<15 print(range.relative(to: continuouscollection)) //11..<15 let disparatecollection = [1, 4, 6, 7, 10, 12, 13, 16, 18, 19, 22] range = 0..<5 print(range.relative(to: disparatecollection)) //0..<5 range = 5..<15 print(range.relative(to: disparatecollection)) //5..<15 range = 11..<15 print(range.relative(to: disparatecollection)) //11..<15 

in every case, relative(to:) returns original range. method supposed do?

relative(to:) requirement of rangeexpression protocol, swift's range types conform in swift 4.

this includes:

• half-open ranges created infix ..< operator (range & countablerange)
• closed ranges created infix ... operator (closedrange & countableclosedrange)
• the partial ranges introduced in se-0172, including:
  • left-handed ranges created postfix ... operator (partialrangefrom & countablepartialrangefrom)
  • closed right-handed ranges created prefix ... operator (partialrangeupto)
  • half-open right-handed ranges created prefix ..< operator (partialrangethrough)

as documentation states, calling relative(to:) on range expression given collection (where range has bounds match index type of collection) returns range suitable slicing collection.

in case of half-open ranges, bounds stay same, you've observed. however, results differ other range types. example, closed ranges, upper bound need incremented (as it's no longer inclusive). partial ranges, missing lower or upper bounds need "filled in" collection's startindex or endindex respectively.

for example:

let continuouscollection = array(0 ..< 10)  {     let range = 0 ..< 5 // countablerange     print(range.relative(to: continuouscollection)) // 0..<5 }  {     let range = 0 ... 5 // closedcountablerange     print(range.relative(to: continuouscollection)) // 0..<6 }  {     let range = 4... // countablepartialrangefrom     print(range.relative(to: continuouscollection)) // 4..<10 }  {     let range = ..<9 // partialrangeupto     print(range.relative(to: continuouscollection)) // 0..<9 }  {     let range = ...3 // partialrangethrough     print(range.relative(to: continuouscollection)) // 0..<4 } 

the relative(to:) requirement of rangeexpression allows standard library, amongst other things, write a generic ranged subscript on collection, allowing arbitrary collection subscripted arbitrary range type index bound(s):

let continuouscollection = array(0 ..< 10)  print(continuouscollection[0 ..< 5]) // [0, 1, 2, 3, 4] print(continuouscollection[0 ... 5]) // [0, 1, 2, 3, 4, 5] print(continuouscollection[4...]) // [4, 5, 6, 7, 8, 9] print(continuouscollection[..<9]) // [0, 1, 2, 3, 4, 5, 6, 7, 8] print(continuouscollection[...3]) // [0, 1, 2, 3]