# Types > StringZilla for Swift `import StringZilla` ## StringZillaViewable Protocol defining the interface for StringZilla-compatible byte-spans. ```swift 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`](#String), [`Substring.UTF8View`](#Substring.UTF8View), [`String.UTF8View`](#String.UTF8View) ## withStringZillaScope A type that represents a position in the collection. ```swift func withStringZillaScope(_ 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. - `body`: A closure that takes a pointer to a C string and its length. Throws: Can throw an error. ## stringZillaByte* Calculates the offset index for a given byte pointer relative to a start pointer. ```swift func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index ``` - `bytePointer`: A pointer to the byte for which the offset is calculated. - `startPointer`: The starting pointer, as obtained from [`withStringZillaScope`](#withStringZillaScope). ## hash Computes a 64-bit hash of the string content using StringZilla's fast hash algorithm. ```swift func hash(seed: UInt64 = 0) -> UInt64 ``` - `seed`: Optional seed value for the hash function, defaulting to 0. ## countRunes Counts the Unicode codepoints in the receiver's UTF-8 bytes. ```swift func countRunes() -> Int ``` ## index Resolves a zero-based codepoint index to a position in the receiver. ```swift func index(ofRune runeIndex: Int) -> Index? ``` - `runeIndex`: The zero-based codepoint index to resolve. ## findFirst Finds the first occurrence of the specified substring within the receiver. ```swift func findFirst(substring needle: S) -> Index? where S : StringZillaViewable ``` ```swift func findFirst(characterFrom characters: S) -> Index? where S : StringZillaViewable ``` Finds the first occurrence of the specified character-set members within the receiver. ```swift func findFirst(characterNotFrom characters: S) -> Index? where S : StringZillaViewable ``` Finds the first occurrence of a character outside of the the given character-set within the receiver. - `needle`: The substring to search for. - `characters`: A string-like collection of characters to match. ## findLast Finds the last occurrence of the specified substring within the receiver. ```swift func findLast(substring needle: S) -> Index? where S : StringZillaViewable ``` ```swift func findLast(characterFrom characters: S) -> Index? where S : StringZillaViewable ``` Finds the last occurrence of the specified character-set members within the receiver. ```swift func findLast(characterNotFrom characters: S) -> Index? where S : StringZillaViewable ``` Finds the last occurrence of a character outside of the the given character-set within the receiver. - `needle`: The substring to search for. - `characters`: A string-like collection of characters to match. ## utf8UncasedFoldedBytes Applies full Unicode case folding to the content's UTF-8 bytes. ```swift func utf8UncasedFoldedBytes() -> [UInt8] ``` The returned bytes are UTF-8 and may be longer than the input, as "ß" → "ss" is. ## utf8Normalized Produces the UTF-8 bytes of the receiver after applying a Unicode normalization form. ```swift 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. - `form`: The normalization form to apply, defaulting to `.nfc`. ## utf8NormalizationViolation Returns the index of the first byte violating the given normalization form, or `nil` if already normalized. ```swift func utf8NormalizationViolation(_ form: StringZillaNormalizationForm) -> Index? ``` - `form`: The normalization form to test. ## isUtf8Normalized Returns `true` if the content is already in the given Unicode normalization form. ```swift func isUtf8Normalized(_ form: StringZillaNormalizationForm) -> Bool ``` - `form`: The normalization form to test. ## utf8UncasedFind Finds the first uncased occurrence of `needle` using full Unicode case folding. ```swift func utf8UncasedFind(substring needle: S) -> Range? where S : StringZillaViewable ``` Returns a byte-accurate range into the receiver. ## utf8Words Splits the content into UAX-29 words per Unicode TR29, in order. ```swift func utf8Words() -> [Range] ``` Unlike whitespace splitting, the words tile the input: every byte belongs to exactly one word. ## utf8Lines Splits the content on UTF-8 newline delimiters: the 7 line-break characters plus a CRLF pair. ```swift func utf8Lines(skipEmpty: Bool = false) -> [Range] ``` 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", ""]`. - `skipEmpty`: When `true`, zero-length segments are omitted, defaulting to `false`. Note: This differs from the Swift standard library's `split(omittingEmptySubsequences: true)`, which drops empty subsequences by default. Pass `skipEmpty: true` for that behavior. ## utf8Tokens Splits the content on UTF-8 whitespace delimiters: all 25 Unicode `White_Space` characters. ```swift func utf8Tokens(skipEmpty: Bool = false) -> [Range] ``` 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"]`. - `skipEmpty`: When `true`, zero-length segments are omitted, defaulting to `false`. Note: This differs from the Swift standard library's `split(omittingEmptySubsequences: true)`, which drops empty subsequences by default. Pass `skipEmpty: true` for that behavior. ## compare Lexicographic byte-order comparison, SIMD-accelerated via `sz_order_best`. ```swift func compare(_ other: S) -> StringZillaOrdering where S : StringZillaViewable ``` - `other`: The string to compare against. ## utf8UncasedOrder Uncased comparison using full Unicode case folding, via `sz_utf8_uncased_order_best`. ```swift func utf8UncasedOrder(_ other: S) -> StringZillaOrdering where S : StringZillaViewable ``` - `other`: The string to compare against. ## equals Byte-level equality, SIMD-accelerated by `sz_equal_best`; unequal lengths never match. ```swift func equals(_ other: S) -> Bool where S : StringZillaViewable ``` - `other`: The string to compare against. ## sha256 Computes the SHA-256 cryptographic hash of the content. ```swift func sha256() -> [UInt8] ``` ## Status Why a call failed, one case per failing `sz_status_t`, which `sz_status_name` spells. ```swift enum Status ``` - `badAllocation` - `invalidUtf8` - `containsDuplicates` - `overflowRisk` - `unexpectedDimensions` - `missingGpu` - `deviceCodeMismatch` - `deviceMemoryMismatch` - `authenticationFailed` - `missingKernel` - `missingLibrary` - `unknown` Conforms to: `Equatable`, `Hashable`, `RawRepresentable`, `Sendable` ## name The C spelling, like "missing_gpu". ```swift var name: String { get } ``` ## Error One failed call: a status every caller can branch on, and the detail the status cannot carry. ```swift struct Error ``` Conforms to: [`Error`](#Error), `CustomStringConvertible`, `Equatable`, `Sendable` ## status The failure identity, shared with the C library. ```swift let status: Status ``` ## message This binding's detail when it rejected the call itself, else empty. ```swift let message: String ``` ## description ```swift var description: String { get } ``` ## String ```swift extension String : StringZillaViewable ``` ## Index ```swift typealias Index = String.Index ``` ## withStringZillaScope ```swift func withStringZillaScope(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R ``` ## stringZillaByteOffset ```swift func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index ``` ## Substring.UTF8View ```swift extension Substring.UTF8View : StringZillaViewable ``` ## Index ```swift typealias Index = Substring.UTF8View.Index ``` ## withStringZilla* Executes 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`. ```swift func withStringZillaScope(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R ``` - `body`: A closure that takes a pointer to the contiguous storage and its size. ## String.UTF8View ```swift extension String.UTF8View : StringZillaViewable ``` ## Index ```swift typealias Index = String.UTF8View.Index ```