API

ProtocolStringZillaViewableProtocol defining the interface for StringZilla-compatible byte-spans.19

protocol StringZillaViewable : Collection

Discussion:

The Swift documentation is extremely vague about the actual memory layout of a String and the cost of obtaining the underlying UTF8 representation or any other raw pointers. https://developer.apple.com/documentation/swift/stringprotocol/withcstring(:) https://developer.apple.com/documentation/swift/stringprotocol/withcstring(encodedas::) https://developer.apple.com/documentation/swift/stringprotocol/data(using:allowlossyconversion:)

Conforms to

Collection, Sequence

Conforming types

String, Substring.UTF8View, String.UTF8View

withStringZillaScopeA type that represents a position in the collection.

StringProtocol+StringZilla.swift:110 ↗

func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R

Executes a closure with a pointer to the string's UTF8 C representation and its length.

Parameters

`body`		A closure that takes a pointer to a C string and its length.

Returns

Returns a value of type R, which is the result of the closure.

Throws

Can throw an error.

stringZillaByte*× 3Calculates the offset index for a given byte pointer relative to a start pointer.

StringProtocol+StringZilla.swift:118 ↗

func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index

Parameters

`bytePointer`		A pointer to the byte for which the offset is calculated.
`startPointer`		The starting pointer, as obtained from `withStringZillaScope`.

Returns

The calculated index offset.

hashComputes a 64-bit hash of the string content using StringZilla's fast hash algorithm.

StringProtocol+StringZilla.swift:196 ↗

func hash(seed: UInt64 = 0) -> UInt64

Parameters

`seed`		Optional seed value for the hash function, defaulting to 0.

Returns

A 64-bit unsigned integer hash value.

countRunesCounts the Unicode codepoints in the receiver's UTF-8 bytes.

StringProtocol+StringZilla.swift:208 ↗

func countRunes() -> Int

Returns

The number of codepoints, matching unicodeScalars.count on well-formed input.

indexResolves a zero-based codepoint index to a position in the receiver.

StringProtocol+StringZilla.swift:221 ↗

func index(ofRune runeIndex: Int) -> Index?

Parameters

`runeIndex`		The zero-based codepoint index to resolve.

Returns

The index of that codepoint, or nil if the receiver holds fewer.

findFirstFinds the first occurrence of the specified substring within the receiver.

StringProtocol+StringZilla.swift:241 ↗

func findFirst<S>(substring needle: S) -> Index? where S : StringZillaViewable

func findFirst<S>(characterFrom characters: S) -> Index? where S : StringZillaViewable

Finds the first occurrence of the specified character-set members within the receiver.

func findFirst<S>(characterNotFrom characters: S) -> Index? where S : StringZillaViewable

Finds the first occurrence of a character outside of the the given character-set within the receiver.

Parameters

`needle`		The substring to search for.
`characters`		A string-like collection of characters to match.

Returns

The index of the found occurrence, or nil if not found.

findLastFinds the last occurrence of the specified substring within the receiver.

StringProtocol+StringZilla.swift:262 ↗

func findLast<S>(substring needle: S) -> Index? where S : StringZillaViewable

func findLast<S>(characterFrom characters: S) -> Index? where S : StringZillaViewable

Finds the last occurrence of the specified character-set members within the receiver.

func findLast<S>(characterNotFrom characters: S) -> Index? where S : StringZillaViewable

Finds the last occurrence of a character outside of the the given character-set within the receiver.

Parameters

`needle`		The substring to search for.
`characters`		A string-like collection of characters to match.

Returns

The index of the found occurrence, or nil if not found.

utf8UncasedFoldedBytesApplies full Unicode case folding to the content's UTF-8 bytes.

StringProtocol+StringZilla.swift:354 ↗

func utf8UncasedFoldedBytes() -> [UInt8]

The returned bytes are UTF-8 and may be longer than the input, as "ß" → "ss" is.

utf8NormalizedProduces the UTF-8 bytes of the receiver after applying a Unicode normalization form.

StringProtocol+StringZilla.swift:388 ↗

func utf8Normalized(_ form: StringZillaNormalizationForm = .nfc) -> [UInt8]

The output may be longer than the input; the worst-case expansion is 18× per source byte, under NFKD.

Parameters

`form`		The normalization form to apply, defaulting to `.nfc`.

Returns

The normalized UTF-8 bytes.

utf8NormalizationViolationReturns the index of the first byte violating the given normalization form, or nil if already normalized.

StringProtocol+StringZilla.swift:423 ↗

func utf8NormalizationViolation(_ form: StringZillaNormalizationForm) -> Index?

Parameters

`form`		The normalization form to test.

Returns

The Index of the first non-conforming byte, or nil if the content is already in form.

isUtf8NormalizedReturns true if the content is already in the given Unicode normalization form.

StringProtocol+StringZilla.swift:447 ↗

func isUtf8Normalized(_ form: StringZillaNormalizationForm) -> Bool

Parameters

`form`		The normalization form to test.

Returns

true when no normalization violation is found.

utf8UncasedFindFinds the first uncased occurrence of needle using full Unicode case folding.

StringProtocol+StringZilla.swift:455 ↗

func utf8UncasedFind<S>(substring needle: S) -> Range<Index>? where S : StringZillaViewable

Returns a byte-accurate range into the receiver.

utf8WordsSplits the content into UAX-29 words per Unicode TR29, in order.

StringProtocol+StringZilla.swift:490 ↗

func utf8Words() -> [Range<Index>]

Unlike whitespace splitting, the words tile the input: every byte belongs to exactly one word.

Returns

Byte-accurate ranges into the receiver, one per word.

utf8LinesSplits the content on UTF-8 newline delimiters: the 7 line-break characters plus a CRLF pair.

StringProtocol+StringZilla.swift:532 ↗

func utf8Lines(skipEmpty: Bool = false) -> [Range<Index>]

The delimiters partition the text into the N+1 gaps between them, so a string with N newlines yields N+1 segments. By default empty segments are kept (skipEmpty: false), so "a\n\nb\n".utf8Lines() → ["a", "", "b", ""].

Parameters

`skipEmpty`		When `true`, zero-length segments are omitted, defaulting to `false`.

Returns

Byte-accurate ranges into the receiver, one per segment.

Note

This differs from the Swift standard library's split(omittingEmptySubsequences: true), which drops empty subsequences by default. Pass skipEmpty: true for that behavior.

utf8TokensSplits the content on UTF-8 whitespace delimiters: all 25 Unicode White_Space characters.

StringProtocol+StringZilla.swift:548 ↗

func utf8Tokens(skipEmpty: Bool = false) -> [Range<Index>]

The delimiters partition the text into the N+1 gaps between them, so a string with N whitespace characters yields N+1 segments. By default, with skipEmpty: false, empty segments are kept. Pass skipEmpty: true to drop runs of whitespace as separators, as in " hi ".utf8Tokens(skipEmpty: true) → ["hi"].

Parameters

`skipEmpty`		When `true`, zero-length segments are omitted, defaulting to `false`.

Returns

Byte-accurate ranges into the receiver, one per segment.

Note

This differs from the Swift standard library's split(omittingEmptySubsequences: true), which drops empty subsequences by default. Pass skipEmpty: true for that behavior.

compareLexicographic byte-order comparison, SIMD-accelerated via sz_order_best.

StringProtocol+StringZilla.swift:612 ↗

func compare<S>(_ other: S) -> StringZillaOrdering where S : StringZillaViewable

Parameters

`other`		The string to compare against.

Returns

.ascending, .equal, or .descending.

utf8UncasedOrderUncased comparison using full Unicode case folding, via sz_utf8_uncased_order_best.

StringProtocol+StringZilla.swift:631 ↗

func utf8UncasedOrder<S>(_ other: S) -> StringZillaOrdering where S : StringZillaViewable

Parameters

`other`		The string to compare against.

Returns

.ascending, .equal, or .descending.

equalsByte-level equality, SIMD-accelerated by sz_equal_best; unequal lengths never match.

StringProtocol+StringZilla.swift:658 ↗

func equals<S>(_ other: S) -> Bool where S : StringZillaViewable

Parameters

`other`		The string to compare against.

Returns

true if the byte contents are identical.

sha256Computes the SHA-256 cryptographic hash of the content.

StringProtocol+StringZilla.swift:848 ↗

func sha256() -> [UInt8]

Returns

A 32-byte array containing the SHA-256 digest.

EnumStatusWhy a call failed, one case per failing sz_status_t, which sz_status_name spells.1

StringProtocol+StringZilla.swift:922 ↗

enum Status

Values

`badAllocation`
`invalidUtf8`
`containsDuplicates`
`overflowRisk`
`unexpectedDimensions`
`missingGpu`
`deviceCodeMismatch`
`deviceMemoryMismatch`
`authenticationFailed`
`missingKernel`
`missingLibrary`
`unknown`

Conforms to

Equatable, Hashable, RawRepresentable, Sendable

nameThe C spelling, like "missing_gpu".

StringProtocol+StringZilla.swift:937 ↗

var name: String { get }

StructErrorOne failed call: a status every caller can branch on, and the detail the status cannot carry.3

StringProtocol+StringZilla.swift:942 ↗

struct Error

Conforms to

Error, CustomStringConvertible, Equatable, Sendable

statusThe failure identity, shared with the C library.

StringProtocol+StringZilla.swift:944 ↗

let status: Status

messageThis binding's detail when it rejected the call itself, else empty.

StringProtocol+StringZilla.swift:946 ↗

let message: String

description

StringProtocol+StringZilla.swift:948 ↗

var description: String { get }

StructString3

extension String : StringZillaViewable

Index

StringProtocol+StringZilla.swift:122 ↗

typealias Index = String.Index

withStringZillaScope

StringProtocol+StringZilla.swift:125 ↗

func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R

stringZillaByteOffset

StringProtocol+StringZilla.swift:133 ↗

func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index

StructSubstring.UTF8View2

extension Substring.UTF8View : StringZillaViewable

Index

StringProtocol+StringZilla.swift:141 ↗

typealias Index = Substring.UTF8View.Index

withStringZilla*× 2Executes a closure with a pointer to the UTF8View's contiguous storage of single-byte elements, the UTF-8 code units, copying them first when the storage is not contiguous, as for a lazily bridged NSString.

StringProtocol+StringZilla.swift:149 ↗

func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R

Parameters

`body`		A closure that takes a pointer to the contiguous storage and its size.

StructString.UTF8View1

extension String.UTF8View : StringZillaViewable

Index

StringProtocol+StringZilla.swift:168 ↗

typealias Index = String.UTF8View.Index