averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-21 12:14:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

[stdlib] Document String index conversions

Browse Source 
Also rename some parameters to make the documentation read well.

Fixes rdar://18018911

Swift SVN r24512
This commit is contained in:
Dave Abrahams
2015-01-19 18:36:29 +00:00
parent 7446cee72b
commit 2cbdffb09f
4 changed files with 182 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
stdlib/core/String.swift
View File

@@ -938,21 +938,31 @@ extension String {
// Index conversions
extension String.Index {
/// Construct the position in `characters` that corresponds exactly to
/// `unicodeScalarIndex`. If no such position exists, the result is `nil`.
///
/// Requires: `unicodeScalarIndex` is an element of
/// `indices(characters.unicodeScalars)`.
public init?(
_ sourceIndex: String.UnicodeScalarIndex,
_ unicodeScalarIndex: String.UnicodeScalarIndex,
within characters: String
) {
if !sourceIndex._isOnGraphemeClusterBoundary {
if !unicodeScalarIndex._isOnGraphemeClusterBoundary {
return nil
}
self.init(_base: sourceIndex)
self.init(_base: unicodeScalarIndex)
}
/// Construct the position in `characters` that corresponds exactly to
/// `utf16Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf16Index` is an element of
/// `indices(characters.utf16)`.
public init?(
_ sourceIndex: String.UTF16Index,
_ utf16Index: String.UTF16Index,
within characters: String
) {
if let me = sourceIndex.samePositionIn(
if let me = utf16Index.samePositionIn(
characters.unicodeScalars
)?.samePositionIn(characters) {
self = me
@@ -962,11 +972,16 @@ extension String.Index {
}
}
/// Construct the position in `characters` that corresponds exactly to
/// `utf8Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf8Index` is an element of
/// `indices(characters.utf8)`.
public init?(
_ sourceIndex: String.UTF8Index,
_ utf8Index: String.UTF8Index,
within characters: String
) {
if let me = sourceIndex.samePositionIn(
if let me = utf8Index.samePositionIn(
characters.unicodeScalars
)?.samePositionIn(characters) {
self = me
@@ -976,19 +991,33 @@ extension String.Index {
}
}
/// Return the position in `utf8` that corresponds exactly
/// to `self`.
///
/// Requires: `self` is an element of `indices(String(utf8))`.
public func samePositionIn(
otherView: String.UTF8View
utf8: String.UTF8View
) -> String.UTF8View.Index {
return String.UTF8View.Index(self, within: otherView)
return String.UTF8View.Index(self, within: utf8)
}
/// Return the position in `utf16` that corresponds exactly
/// to `self`.
///
/// Requires: `self` is an element of `indices(String(utf16))`.
public func samePositionIn(
otherView: String.UTF16View
utf16: String.UTF16View
) -> String.UTF16View.Index {
return String.UTF16View.Index(self, within: otherView)
return String.UTF16View.Index(self, within: utf16)
}
/// Return the position in `unicodeScalars` that corresponds exactly
/// to `self`.
///
/// Requires: `self` is an element of `indices(String(unicodeScalars))`.
public func samePositionIn(
otherView: String.UnicodeScalarView
unicodeScalars: String.UnicodeScalarView
) -> String.UnicodeScalarView.Index {
return String.UnicodeScalarView.Index(self, within: otherView)
return String.UnicodeScalarView.Index(self, within: unicodeScalars)
}
}

54
stdlib/core/StringUTF16.swift
View File

@@ -232,43 +232,73 @@ public func ~> (
// Index conversions
extension String.UTF16View.Index {
/// Construct the position in `utf16` that corresponds exactly to
/// `utf8Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf8Index` is an element of
/// `indices(String(utf16).utf8)`.
public init?(
_ sourceIndex: String.UTF8Index, within utf16: String.UTF16View
_ utf8Index: String.UTF8Index, within utf16: String.UTF16View
) {
let core = utf16._core
_precondition(
sourceIndex._coreIndex >= 0 && sourceIndex._coreIndex <= core.endIndex,
utf8Index._coreIndex >= 0 && utf8Index._coreIndex <= core.endIndex,
"Invalid String.UTF8Index for this UTF-16 view")
// Detect positions that have no corresponding index.
if !sourceIndex._isOnUnicodeScalarBoundary {
if !utf8Index._isOnUnicodeScalarBoundary {
return nil
}
self.init(sourceIndex._coreIndex)
self.init(utf8Index._coreIndex)
}
/// Construct the position in `utf16` that corresponds exactly to
/// `unicodeScalarIndex`.
///
/// Requires: `unicodeScalarIndex` is an element of
/// `indices(String(utf16).unicodeScalars)`.
public init(
_ sourceIndex: String.UnicodeScalarIndex, within utf16: String.UTF16View) {
self.init(sourceIndex._position)
_ unicodeScalarIndex: String.UnicodeScalarIndex,
within utf16: String.UTF16View) {
self.init(unicodeScalarIndex._position)
}
public init(_ sourceIndex: String.Index, within utf16: String.UTF16View) {
self.init(sourceIndex._utf16Index)
/// Construct the position in `utf16` that corresponds exactly to
/// `characterIndex`.
///
/// Requires: `characterIndex` is an element of
/// `indices(String(utf16))`.
public init(_ characterIndex: String.Index, within utf16: String.UTF16View) {
self.init(characterIndex._utf16Index)
}
/// Return the position in `utf8` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of
/// `indices(String(utf8).utf16)`.
public func samePositionIn(
otherView: String.UTF8View
utf8: String.UTF8View
) -> String.UTF8View.Index? {
return String.UTF8View.Index(self, within: otherView)
return String.UTF8View.Index(self, within: utf8)
}
/// Return the position in `unicodeScalars` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of
/// `indices(String(unicodeScalars).utf16)`.
public func samePositionIn(
otherView: String.UnicodeScalarView
unicodeScalars: String.UnicodeScalarView
) -> String.UnicodeScalarIndex? {
return String.UnicodeScalarIndex(self, within: otherView)
return String.UnicodeScalarIndex(self, within: unicodeScalars)
}
/// Return the position in `characters` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of `indices(characters.utf16)`.
public func samePositionIn(
characters: String
) -> String.Index? {

70
stdlib/core/StringUTF8.swift
View File

@@ -309,58 +309,86 @@ func == (lhs: String.UTF8View.Index, rhs: String.UTF8View.Index) -> Bool {
while true
}
extension String.UTF8Index {
// Index conversions
extension String.UTF8View.Index {
internal init(_ core: _StringCore, _utf16Offset: Int) {
let (_, buffer) = core._encodeSomeUTF8(_utf16Offset)
self.init(core, _utf16Offset, buffer)
}
public init?(_ sourceIndex: String.UTF16Index, within utf8: String.UTF8View) {
let sourceView = String.UTF16View(utf8._core)
/// Construct the position in `utf8` that corresponds exactly to
/// `utf16Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf8Index` is an element of
/// `indices(String(utf16).utf8)`.
public init?(_ utf16Index: String.UTF16Index, within utf8: String.UTF8View) {
let utf16 = String.UTF16View(utf8._core)
if sourceIndex != sourceView.startIndex
&& sourceIndex != sourceView.endIndex {
if utf16Index != utf16.startIndex
&& utf16Index != utf16.endIndex {
_precondition(
sourceIndex >= sourceView.startIndex
&& sourceIndex <= sourceView.endIndex,
utf16Index >= utf16.startIndex
&& utf16Index <= utf16.endIndex,
"Invalid String.UTF16Index for this UTF-8 view")
// Detect positions that have no corresponding index. Note that
// we have to check before and after, because an unpaired
// surrogate will be decoded as a single replacement character,
// thus making the corresponding position valid in UTF8.
if UTF16.isTrailSurrogate(sourceView[sourceIndex])
&& UTF16.isLeadSurrogate(sourceView[sourceIndex.predecessor()]) {
if UTF16.isTrailSurrogate(utf16[utf16Index])
&& UTF16.isLeadSurrogate(utf16[utf16Index.predecessor()]) {
return nil
}
}
self.init(utf8._core, _utf16Offset: sourceIndex._offset)
self.init(utf8._core, _utf16Offset: utf16Index._offset)
}
/// Construct the position in `utf8` that corresponds exactly to
/// `unicodeScalarIndex`.
///
/// Requires: `unicodeScalarIndex` is an element of
/// `indices(String(utf8).unicodeScalars)`.
public init(
_ sourceIndex: String.UnicodeScalarIndex, within utf8: String.UTF8View) {
self.init(utf8._core, _utf16Offset: sourceIndex._position)
_ unicodeScalarIndex: String.UnicodeScalarIndex,
within utf8: String.UTF8View
) {
self.init(utf8._core, _utf16Offset: unicodeScalarIndex._position)
}
public init(_ sourceIndex: String.Index, within utf8: String.UTF8View) {
self.init(utf8._core, _utf16Offset: sourceIndex._base._position)
}
/// Construct the position in `utf8` that corresponds exactly to
/// `characterIndex`.
///
/// Requires: `characterIndex` is an element of
/// `indices(String(utf8))`.
public init(_ characterIndex: String.Index, within utf8: String.UTF8View) {
self.init(utf8._core, _utf16Offset: characterIndex._base._position)
}
// Index conversions
extension String.UTF8View.Index {
/// Return the position in `utf16` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of `indices(String(utf16).utf8)`.
public func samePositionIn(
otherView: String.UTF16View
utf16: String.UTF16View
) -> String.UTF16View.Index? {
return String.UTF16View.Index(self, within: otherView)
return String.UTF16View.Index(self, within: utf16)
}
/// Return the position in `unicodeScalars` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of
/// `indices(String(unicodeScalars).utf8)`.
public func samePositionIn(
otherView: String.UnicodeScalarView
unicodeScalars: String.UnicodeScalarView
) -> String.UnicodeScalarIndex? {
return String.UnicodeScalarIndex(self, within: otherView)
return String.UnicodeScalarIndex(self, within: unicodeScalars)
}
/// Return the position in `characters` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of `indices(characters.utf8)`.
public func samePositionIn(
characters: String
) -> String.Index? {

69
stdlib/core/StringUnicodeScalarView.swift
View File

@@ -349,65 +349,92 @@ extension String.UnicodeScalarView : RangeReplaceableCollectionType {
// Index conversions
extension String.UnicodeScalarIndex {
/// Construct the position in `unicodeScalars` that corresponds exactly to
/// `utf16Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf16Index` is an element of
/// `indices(String(unicodeScalars).utf16)`.
public init?(
_ sourceIndex: String.UTF16Index,
_ utf16Index: String.UTF16Index,
within unicodeScalars: String.UnicodeScalarView
) {
let sourceView = String.UTF16View(unicodeScalars._core)
let utf16 = String.UTF16View(unicodeScalars._core)
if sourceIndex != sourceView.startIndex
&& sourceIndex != sourceView.endIndex {
if utf16Index != utf16.startIndex
&& utf16Index != utf16.endIndex {
_precondition(
sourceIndex >= sourceView.startIndex
&& sourceIndex <= sourceView.endIndex,
utf16Index >= utf16.startIndex
&& utf16Index <= utf16.endIndex,
"Invalid String.UTF16Index for this UnicodeScalar view")
// Detect positions that have no corresponding index. Note that
// we have to check before and after, because an unpaired
// surrogate will be decoded as a single replacement character,
// thus making the corresponding position valid.
if UTF16.isTrailSurrogate(sourceView[sourceIndex])
&& UTF16.isLeadSurrogate(sourceView[sourceIndex.predecessor()]) {
if UTF16.isTrailSurrogate(utf16[utf16Index])
&& UTF16.isLeadSurrogate(utf16[utf16Index.predecessor()]) {
return nil
}
}
self.init(sourceIndex._offset, unicodeScalars._core)
self.init(utf16Index._offset, unicodeScalars._core)
}
/// Construct the position in `unicodeScalars` that corresponds exactly to
/// `utf8Index`. If no such position exists, the result is `nil`.
///
/// Requires: `utf8Index` is an element of
/// `indices(String(unicodeScalars).utf8)`.
public init?(
_ sourceIndex: String.UTF8Index,
_ utf8Index: String.UTF8Index,
within unicodeScalars: String.UnicodeScalarView
) {
let core = unicodeScalars._core
_precondition(
sourceIndex._coreIndex >= 0 && sourceIndex._coreIndex <= core.endIndex,
utf8Index._coreIndex >= 0 && utf8Index._coreIndex <= core.endIndex,
"Invalid String.UTF8Index for this UnicodeScalar view")
// Detect positions that have no corresponding index.
if !sourceIndex._isOnUnicodeScalarBoundary {
if !utf8Index._isOnUnicodeScalarBoundary {
return nil
}
self.init(sourceIndex._coreIndex, core)
self.init(utf8Index._coreIndex, core)
}
/// Construct the position in `unicodeScalars` that corresponds
/// exactly to `characterIndex`.
///
/// Requires: `characterIndex` is an element of
/// `indices(String(unicodeScalars))`.
public init(
_ sourceIndex: String.Index,
_ characterIndex: String.Index,
within unicodeScalars: String.UnicodeScalarView
) {
self.init(sourceIndex._base._position, unicodeScalars._core)
self.init(characterIndex._base._position, unicodeScalars._core)
}
public func samePositionIn(
otherView: String.UTF8View
) -> String.UTF8View.Index {
return String.UTF8View.Index(self, within: otherView)
/// Return the position in `utf8` that corresponds exactly
/// to `self`.
///
/// Requires: `self` is an element of `indices(String(utf8))`.
public func samePositionIn(utf8: String.UTF8View) -> String.UTF8View.Index {
return String.UTF8View.Index(self, within: utf8)
}
/// Return the position in `utf16` that corresponds exactly
/// to `self`.
///
/// Requires: `self` is an element of `indices(String(utf16))`.
public func samePositionIn(
otherView: String.UTF16View
utf16: String.UTF16View
) -> String.UTF16View.Index {
return String.UTF16View.Index(self, within: otherView)
return String.UTF16View.Index(self, within: utf16)
}
/// Return the position in `characters` that corresponds exactly
/// to `self`, or if no such position exists, `nil`.
///
/// Requires: `self` is an element of `indices(characters.unicodeScalars)`.
public func samePositionIn(characters: String) -> String.Index? {
return String.Index(self, within: characters)
}