코어 라이브러리

코어 라이브러리는 작은 프로그램 대부분에 필요한 작업을 담당합니다. 텍스트 출력, 값 변환, 유니코드 확인, 값의 부재와 실패 표현, 컬렉션 변환이 여기에 속합니다. 특수한 이름공간을 찾아보기 전에 이 기능부터 고르세요.

일상 도우미 선택하기

하려는 일	사용할 기능	결과
한 줄 출력	`print("text")`	`()`
텍스트를 정수로 해석	`toInt(text)`	`Option<int>`
2진수부터 36진수까지 밑을 지정해 해석	`toIntRadix(text, radix)`	`Option<int>`
`int`를 `float`로 변환	`toFloat(value)`	`float`
코드 포인트에서 유니코드 스칼라 생성	`fromCodePoint(value)`	`Option<string>`
문자열을 유니코드 스칼라 단위로 확인	`text.scalars()`	`Array<string>`
순회 가능한 값을 변환·선택·누적	`map`, `filter`, `reduce`	새 값

Some, None, Ok, Err는 기본 범위의 생성자입니다. 타입 추론이 타입 인수를 모두 정하지 못하면 기대 타입이 필요합니다. None, Ok, Err와 빈 컬렉션이 그런 경우입니다.

값을 해석하고 변환하기

다음 프로그램은 변환할 수 없는 텍스트를 None으로 남깁니다. 한국어 텍스트는 바이트 수가 아니라 유니코드 스칼라 수를 셉니다.

TOPAZ

function parseAll(values: Array<string>) -> Array<Option<int>> {
    return map(values, value => toInt(value))
}

let scalars = "토파즈".scalars()
let parsed = parseAll(["1", "x", "3"])
print("{scalars.length}:{parsed}")

출력

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가 하나 더 생기지는 않습니다.

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

길이가 고정된 연속 값 하나에 바이트를 여러 번 써야 한다면 ByteBuffer.allocate(length, value = 0)를 사용합니다. set, fill, copy의 수신자 루트는 let mut이어야 합니다. 모든 범위와 바이트 값은 첫 쓰기 전에 검사합니다. 그래서 실행 오류가 나도 대상의 일부만 바뀌지 않습니다.

TOPAZ

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

let mut frame = ByteBuffer.allocate(12)
frame.copy(row, 0, 2, 8)
let payload = frame.toBytes()
print(payload.toHex())

출력

000089ffffffffffffff0000

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

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

Hash.crc32(data)는 부호 없는 CRC-32/ISO-HDLC 값을 반환합니다. 파일 형식의 무결성 필드에는 알맞습니다. 인증이나 적대적 변조 방지에는 쓰면 안 됩니다.

TOPAZ

let checksum = Hash.crc32(Bytes.encodeUtf8("123456789"))
print("{checksum}")

출력

3421780262

고정된 표준 모듈 표면의 std.hash.crc32도 같은 연산을 제공합니다.

결정적인 고정 DEFLATE 만들기

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

TOPAZ

match Codec.deflateFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(compressed) => print(compressed.toHex())
  case Err(error) => print(error)
}

출력

cb48cdc9c90700

탐색과 메모리 사용량에는 제한이 있습니다. 256 MiB를 넘는 입력은 Err를 반환합니다. 생성 Python에는 이 Codec 멤버가 없습니다. 산출물을 쓰기 전에 해당 대상을 거부합니다.

결정적인 고정 zlib 만들기

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

TOPAZ

match Codec.zlibFixedCompress(Bytes.encodeUtf8("hello")) {
  case Ok(compressed) => print(compressed.toHex())
  case Err(error) => print(error)
}

출력

7801cb48cdc9c90700062c0215

256 MiB를 넘는 입력은 Err입니다. 생성 Python에는 이 Codec 멤버가 없습니다. 산출물을 만들기 전에 해당 대상을 거부합니다. 이 연산은 압축 해제, 압축 단계, 사전, 스트리밍, 범용 Adler-32 API를 추가하지 않습니다.

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

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

TOPAZ

match Codec.reedSolomon255223Protect(Bytes.encodeUtf8("hello")) {
  case Ok(protected) => print("{protected.length()}")
  case Err(error) => print(error)
}

출력

원래 논리 길이는 호출자가 보관합니다. 입력은 비어 있으면 안 됩니다. 조각은 최대 65,535개까지 쓸 수 있습니다. 이 함수는 보호 바이트를 만들 뿐 손상을 탐지하거나 고치지 않습니다. 생성 Python에는 이 Codec 멤버가 없습니다. 산출물을 만들기 전에 해당 대상을 거부합니다.

정확한 경계

별도 바이트 표기가 없으면 문자열 연산은 스칼라 위치를 사용합니다.
Option.map은 정상적인 부재를 그대로 둡니다. Result.map은 실행 오류를 잡지 않습니다.
map, filter, reduce는 정해진 순회 가능 타입만 받습니다.
타입 지정 JSON에는 완전히 알려진 대상 타입 하나가 필요하고, 자료 오류는 $로 시작하는 경로를 돌려줍니다.
input과 print는 해당 호스트 기능을 제공하는 환경이 필요합니다.
assert는 테스트 프로필의 함수일 뿐 언어 키워드가 아닙니다.

표준 라이브러리 개요, Null·Option·결과·실행 오류, 실행 환경 동작으로 이어서 살펴보세요.