String

struct String

An owned Unicode string with copy-on-write UTF-8 storage.

Bytes in storage[0..<byte_count] are valid UTF-8 and byte_count <= capacity. Byte-oriented access lives on UTF8View; ordinary iteration and the deep text APIs operate on extended grapheme clusters.

Properties

let byte_count: Int

The number of bytes in the encoded representation.

let capacity: Int

The number of bytes that fit without reallocating.

Methods

func to_string() -> String

Returns an independent owned copy of this string.

The copy receives exactly byte_count capacity and does not share the original buffer, unlike ordinary implicit copy-on-write sharing.

View Source
pub func to_string() -> String {
	let base: RawPtr = _alloc<Byte>(count: self.byte_count)
	_copy(from: self.storage.base, to: base, length: self.byte_count)
	String(
		base: ByteStorage(base: base),
		byte_count: self.byte_count,
		capacity: self.byte_count
	)
}

static func from_bytes(bytes: &[Byte]) -> String

The bytes are copied into a fresh buffer, so byte-level string building needs no raw allocation at the call site (ADR 0043 stage 0: the frontend source set may not use #_ir).

View Source
pub static func from_bytes(bytes: &[Byte]) -> String {
	let count: Int = bytes.count
	let base: RawPtr = _alloc<Byte>(count: count)
	let i = 0
	loop i < count {
		let ptr: RawPtr = _ptr_add(ptr: base, offset: i)
		_store<Byte>(ptr: ptr, value: bytes.get(i))
		i = i + 1
	}
	String(base: ByteStorage(base: base), byte_count: count, capacity: count)
}

static func decoding_utf8(_ bytes: [Byte]) -> Result<String, UTF8Error>

Validates an entire byte array and copies it into an owned string.

The first malformed subsequence returns error with its starting byte offset; no partial string escapes. Compare with decoding_utf8_lossy, which always succeeds by inserting U+FFFD.

View Source
pub static func decoding_utf8(_ bytes: [Byte]) -> Result<String, UTF8Error> {
	let output: [Byte] = []
	let i = 0
	loop i < bytes.count {
		let remaining = bytes.count - i
		let b0 = bytes.get(i)._toInt()
		let b1 = if remaining > 1 {
			bytes.get(i + 1)._toInt()
		} else {
			0 - 1
		}
		let b2 = if remaining > 2 {
			bytes.get(i + 2)._toInt()
		} else {
			0 - 1
		}
		let b3 = if remaining > 3 {
			bytes.get(i + 3)._toInt()
		} else {
			0 - 1
		}
		let size = _valid_utf8_values(
			b0: b0,
			b1: b1,
			b2: b2,
			b3: b3,
			remaining: remaining
		)
		if size < 1 { return .error(UTF8Error(offset: i)) }
		let j = 0
		loop j < size {
			output.push(bytes.get(i + j))
			j = j + 1
		}
		i = i + size
	}
	.ok(_copy_byte_array(bytes: output))
}

static func decoding_utf8_lossy(_ bytes: [Byte]) -> String

Decodes all bytes, replacing each maximal malformed subsequence with U+FFFD.

The returned string is always valid UTF-8. Use decoding_utf8 when the caller needs to reject input or report the exact failing byte offset.

View Source
pub static func decoding_utf8_lossy(_ bytes: [Byte]) -> String {
	let output: [Byte] = []
	let i = 0
	loop i < bytes.count {
		let remaining = bytes.count - i
		let b0 = bytes.get(i)._toInt()
		let b1 = if remaining > 1 {
			bytes.get(i + 1)._toInt()
		} else {
			0 - 1
		}
		let b2 = if remaining > 2 {
			bytes.get(i + 2)._toInt()
		} else {
			0 - 1
		}
		let b3 = if remaining > 3 {
			bytes.get(i + 3)._toInt()
		} else {
			0 - 1
		}
		let size = _valid_utf8_values(
			b0: b0,
			b1: b1,
			b2: b2,
			b3: b3,
			remaining: remaining
		)
		if size > 0 {
			let j = 0
			loop j < size {
				output.push(bytes.get(i + j))
				j = j + 1
			}
			i = i + size
		} else {
			output.push(239._toByte())
			output.push(191._toByte())
			output.push(189._toByte())
			i = i + (0 - size)
		}
	}
	_copy_byte_array(bytes: output)
}

func encoded_utf8() -> [Byte]

Copies the string's initialized UTF-8 bytes into an array.

This is the owned counterpart to the borrowed utf8() view; modifying the returned array cannot affect the string.

View Source
pub func encoded_utf8() -> [Byte] {
	let result: [Byte] = []
	let i = 0
	loop i < self.byte_count {
		result.push(self.storage.get(i))
		i = i + 1
	}
	result
}