코어 라이브러리

코어 라이브러리는 대부분의 소규모 프로그램에 필요한 공통 작업을 처리합니다. 텍스트 출력, 값 변환, 유니코드 확인, 값의 부재 및 실패 표현, 컬렉션 변환 등이 이에 해당합니다. 별도의 네임스페이스를 탐색하기 전에 이 기능들을 우선 선택하세요.

일상 도우미 선택하기

Some, None, Ok, Err는 기본 스코프의 생성자입니다. 타입 추론이 타입 인자를 모두 결정하지 못하는 경우에는 명시적인 기대 타입이 필요합니다. None, Ok, Err 및 빈 컬렉션이 그러한 예입니다.

값을 해석하고 변환하기

다음 프로그램은 변환할 수 없는 텍스트를 None으로 처리합니다. 한국어 텍스트는 바이트 수가 아닌 유니코드 스칼라 개수를 기준으로 셉니다.

function 모두해석(값들: Array<string>) -> Array<Option<int>> {
    return map(값들, 값 => toInt(값))
}

let 스칼라들 = "토파즈".scalars()
let 해석값 = 모두해석(["1", "x", "3"])
print("{스칼라들.length}:{해석값}")

3:[Some(1), None, Some(3)]

print는 문자열을 받으므로 보간식을 통해 결과를 출력합니다. toInt는 "x"와 같이 해석할 수 없는 입력에서 None을 반환합니다. map은 이러한 정상적인 부재를 런타임 에러로 전환하지 않습니다. 호출자에게 실패 원인을 전달해야 한다면 match로 부재를 원인이 담긴 Result로 변환하세요.

흔한 수정: toFloat는 int를 변환할 뿐 문자열을 해석하지 않습니다. 범용 독립 함수 toString, len, println, type_of도 제공되지 않습니다. 문자열 보간, .length처럼 해당 타입에 선언된 정확한 멤버, 또는 문서에 명시된 변환 헬퍼를 사용하세요.

공개 표면

일반적인 작업에는 다음 식별자를 그대로 사용합니다.

• print(string) -> ()는 한 줄을 출력합니다. input() -> string은 실행 시 호스트가 전달한 텍스트 입력 전체를 반환합니다. 단일 줄만 읽지 않으며, 호출할 때마다 동일한 문자열이 반환됩니다.
• toInt(string) -> Option<int>와 toIntRadix(string, int) -> Option<int>는 정수를 해석합니다.
• toFloat(int) -> float는 정수를 변환하며, 텍스트를 해석하는 함수가 아닙니다.
• fromCodePoint(int) -> Option<string>은 유효한 유니코드 스칼라 하나를 생성합니다.
• text.scalars() -> Array<string>는 문자열을 유니코드 스칼라 단위로 나눈 배열을 반환합니다.
• Some과 None은 Option, Ok와 Err는 Result를 생성합니다.
• option.okOr(error: E) -> Result<T, E>는 에러 값을 즉시 평가합니다. option.okOrElse(f: () -> E) -> Result<T, E>는 None일 때만 f를 호출합니다.
• option.map(f: (T) -> U) -> Option<U>는 Some 내부의 값을 변환합니다. option.flatMap(f: (T) -> Option<U>) -> Option<U>는 Option이 중첩되지 않도록 합니다. 두 메서드 모두 None이면 f를 호출하지 않습니다.
• result.map(f: (T) -> U) -> Result<U, E>는 Ok 내부의 값을 변환합니다. result.flatMap(f: (T) -> Result<U, E>) -> Result<U, E>는 Result가 중첩되지 않도록 합니다. 두 메서드 모두 Err이면 f를 호출하지 않습니다.
• 독립 함수 map, filter, reduce는 순회 가능한 값을 변환합니다. 이는 메서드 형태의 수신자 헬퍼와는 다른 기능입니다. 두 방식 모두 런타임 에러를 포착하지 않습니다.

아래 Bytes, ByteBuffer, Hash, Codec 절은 전체 API 목록이 아니며, 제한된 표면에서 선정된 기능만 다룹니다. 해당 절에 실제로 명시된 멤버만 사용 가능하다고 간주하세요. 특정 런타임이나 생성 타깃에 유사한 내부 헬퍼가 존재하더라도 토파즈 API가 추가되는 것은 아닙니다.

바이트를 제자리에서 조립하기

고정된 길이에 바이트를 여러 번 기록해야 한다면 ByteBuffer.allocate(length, value = 0)를 사용합니다. set, fill, copy의 수신자 루트는 let mut이어야 합니다. 모든 범위와 바이트 값은 첫 쓰기 작업 전에 검사되므로, 런타임 에러가 발생하더라도 타깃 버퍼의 일부만 변경되지 않습니다.

let mut 행 = ByteBuffer.allocate(8)
행.fill(0, 8, 255)
행.set(0, 137)

let mut 프레임 = ByteBuffer.allocate(12)
프레임.copy(행, 0, 2, 8)
let 페이로드 = 프레임.toBytes()
print(페이로드.toHex())

000089ffffffffffffff0000

ByteBuffer를 대입하면 동일한 가변 참조를 공유합니다. ByteBuffer.fromBytes는 내용을 새 버퍼로 복사합니다. toBytes()는 불변 스냅샷을 만듭니다. ByteBuffer 자체는 Web export, 동등성·순서 비교, Map/Set 키, 텍스트·JSON 경계에 사용할 수 없습니다.

CRC-32 무결성 필드 계산하기

Hash.crc32(data)는 부호 없는 CRC-32/ISO-HDLC 값을 반환합니다. 파일 포맷의 무결성 검증 필드에 적합하며, 인증이나 악의적인 변조 방지 목적으로는 사용할 수 없습니다.

let 검사합 = Hash.crc32(Bytes.encodeUtf8("123456789"))
print("{검사합}")

3421780262

고정된 표준 모듈 인터페이스의 std.hash.crc32도 동일한 연산을 제공합니다.

결정론적인 고정 DEFLATE 만들기

zlib·gzip 프레이밍이 없는 순수 raw 고정 허프만 DEFLATE 블록 하나가 필요하다면 Codec.deflateFixedCompress(bytes)를 사용합니다.

match Codec.deflateFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(압축됨) => print(압축됨.toHex())
  case Err(오류) => print(오류)
}

cb48cdc9c90700

탐색 거리와 메모리 사용량에는 제한이 있습니다. 256 MiB를 초과하는 입력은 Err를 반환합니다. 생성 Python 환경에는 이 Codec 멤버가 없으므로, 아티팩트를 출력하기 전에 해당 타깃을 거부합니다.

결정론적인 고정 zlib 만들기

완성된 zlib 스트림이 필요하다면 Codec.zlibFixedCompress(bytes)를 사용합니다. 고정 78 01 헤더, 고정 허프만 페이로드, Adler-32 트레일러를 순차적으로 만듭니다.

match Codec.zlibFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(압축됨) => print(압축됨.toHex())
  case Err(오류) => print(오류)
}

7801cb48cdc9c90700062c0215

256 MiB를 초과하는 입력은 Err를 반환합니다. 생성 Python 환경에는 이 Codec 멤버가 없으므로, 아티팩트를 만들기 전에 해당 타깃을 거부합니다. 이 연산은 압축 해제, 압축 단계, 사전, 스트리밍, 범용 Adler-32 API를 추가하지 않습니다.

Reed–Solomon 보호 바이트 추가하기

Codec.reedSolomon255223Protect(bytes)는 systematic RS(255,223) 코드워드를 만듭니다. 223바이트 데이터 조각 뒤에 32바이트 패리티를 붙이며, 마지막 데이터 조각은 0으로 채웁니다.

match Codec.reedSolomon255223Protect(Bytes.encodeUtf8("hello")) {
  case Ok(보호됨) => print("{보호됨.length()}")
  case Err(오류) => print(오류)
}

255

원래 논리적 길이는 호출자가 보관해야 합니다. 입력은 비어 있어서는 안 되며, 조각은 최대 65,535개까지 처리할 수 있습니다. 이 함수는 보호 바이트를 생성할 뿐 손상을 탐지하거나 복구하지 않습니다. 생성 Python 환경에는 이 Codec 멤버가 없으므로, 아티팩트를 만들기 전에 해당 타깃을 거부합니다.

정확한 경계

• 별도 바이트 표기가 없으면 문자열 연산은 스칼라 위치를 사용합니다.
• Option.map은 정상적인 부재를 그대로 유지하고, Result.map은 런타임 에러를 포착하지 않습니다.
• map, filter, reduce는 지정된 순회 가능 타입만 받습니다.
• 타입 지정 JSON에는 명확히 정의된 타깃 타입 하나가 필요하며, 데이터 오류 시 $로 시작하는 경로를 반환합니다.
• input과 print는 해당 호스트 기능을 제공하는 환경이 필요합니다.
• assert는 테스트 프로필 전용 함수일 뿐 언어 키워드가 아닙니다.

표준 라이브러리 개요, Null·Option·결과·fault, 런타임 동작으로 이어서 살펴보세요.