<!--
{
  "availability" : [
    "iOS: 26.0.0 -",
    "iPadOS: 26.0.0 -",
    "macCatalyst: 26.0.0 -",
    "macOS: 26.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 26.0.0 -",
    "watchOS: 26.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Swift",
  "identifier" : "/documentation/Swift/UTF8Span/UnicodeScalarIterator",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Swift"
    ],
    "preciseIdentifier" : "s:s8UTF8SpanV21UnicodeScalarIteratorV"
  },
  "title" : "UTF8Span.UnicodeScalarIterator"
}
-->

# UTF8Span.UnicodeScalarIterator

Iterate the `Unicode.Scalar`s contents of a `UTF8Span`.

```
@frozen struct UnicodeScalarIterator
```

## Overview

```
func printScalarValues(_ string: borrowing String) {
    var iterator = string.utf8Span.makeUnicodeScalarIterator()
    while let scalar = iterator.next() {
        print(scalar.escaped(asASCII: true))
    }
}

let string = "A🎉"
printScalarValues(string)
// Prints "A"
// Prints "\u{0001F389}"
```

## Topics

### Initializers

[`init(UTF8Span)`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/init(_:))

### Instance Properties

[`let codeUnits: UTF8Span`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/codeUnits)

[`var currentCodeUnitOffset: Int`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/currentCodeUnitOffset)

The byte offset of the start of the next scalar. This is
always scalar-aligned.

### Instance Methods

[`func next() -> Unicode.Scalar?`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/next())

Decode and return the scalar starting at `currentCodeUnitOffset`.
After the function returns, `currentCodeUnitOffset` holds the
position at the end of the returned scalar, which is also the start
of the next scalar.

[`func prefix() -> UTF8Span`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/prefix())

Returns the UTF8Span containing all the content up to the iterator’s
current position.

[`func previous() -> Unicode.Scalar?`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/previous())

Decode and return the scalar ending at `currentCodeUnitOffset`. After
the function returns, `currentCodeUnitOffset` holds the position at
the start of the returned scalar, which is also the end of the
previous scalar.

[`func reset(roundingBackwardsFrom: Int)`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/reset(roundingBackwardsFrom:))

Reset to the nearest scalar-aligned code unit offset `<= i`.

[`func reset(roundingForwardsFrom: Int)`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/reset(roundingForwardsFrom:))

Reset to the nearest scalar-aligned code unit offset `>= i`.

[`func reset(toUnchecked: Int)`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/reset(toUnchecked:))

Reset this iterator to `codeUnitOffset`, skipping *all* safety
checks (including bounds checks).

[`func skipBack() -> Int`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/skipBack())

Move `currentCodeUnitOffset` to the start of the previous scalar, without
decoding it.

[`func skipBack(by: Int) -> Int`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/skipBack(by:))

Move `currentCodeUnitOffset` to the start of the previous `n` scalars,
without decoding them.

[`func skipForward() -> Int`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/skipForward())

Advance `currentCodeUnitOffset` to the end of the current scalar, without
decoding it.

[`func skipForward(by: Int) -> Int`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/skipForward(by:))

Advance `currentCodeUnitOffset` to the end of `n` scalars, without decoding
them.

[`func suffix() -> UTF8Span`](/documentation/Swift/UTF8Span/UnicodeScalarIterator/suffix())

Returns the UTF8Span containing all the content after the iterator’s
current position.

## Relationships

### Conforms To

[`Copyable`](/documentation/Swift/Copyable)

[`BitwiseCopyable`](/documentation/Swift/BitwiseCopyable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)