Topazdocs
표준 라이브러리와 런타임

코어 라이브러리

출력, 타입 변환, 문자열, `Option`/`Result`, 기본 컬렉션 함수.

코어 라이브러리는 값 생성, 명시적 타입 변환, 문자열 스칼라 접근, 고차 컬렉션 함수, Option/Result 도우미를 제공합니다.

정식 계약

Some, None, Ok, Err는 기본 생성자입니다. print는 문자열을 받습니다. toInt, toFloat는 파싱에 실패하면 빈 값을 돌려주고, toString은 지원되는 값을 결정적인 형식으로 표시합니다. map, filter, reduce는 배열을 왼쪽에서 오른쪽으로 순회합니다.

공개 표면

toIntRadix, fromCodePoint, input, Math, 문자열 검색·자르기·치환, Option.okOr/map/flatMap, Result.map/flatMap, 불변 Bytes, 고정 길이 변경 가능 ByteBuffer, Encoding, JSON과 구조화 형식 도우미, 날짜, BigInt, Decimal을 사용할 수 있습니다. 테스트 함수는 테스트 프로필에서만 노출됩니다.

관찰 가능한 동작

변환 함수는 암묵적 타입 승격을 만들지 않습니다. 문자열 함수는 스칼라 위치를 사용합니다. Option/Result 도우미는 스스로 값을 복구하거나 예외로 바꾸지 않고 생성자 구조를 유지합니다. 콜백은 컬렉션 순서대로 호출됩니다.

바이너리 조립

한 개의 연속된 고정 길이 값에 많은 바이트를 써야 하는 알고리즘에서는 ByteBuffer.allocate(length, value = 0)를 사용합니다. set, fill, copy의 수신자 루트는 let mut이어야 합니다. 인덱스, 범위, 바이트 값(0..255)은 쓰기 전에 모두 검사되므로 잘못된 연산은 버퍼를 일부만 바꾸지 않고 실행 오류를 냅니다. 대입하면 같은 가변 값을 공유하지만, ByteBuffer.fromBytes는 새 버퍼로 복사하고 toBytes()는 불변 스냅샷을 만듭니다.

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()

ByteBuffer 자체는 Web export를 통과할 수 없고, 동등성·순서 비교, Map/Set 키, 문자열·템플릿 보간, JSON 인코딩에도 사용할 수 없습니다. 텍스트나 ABI 경계에서는 Bytes로 스냅샷을 만든 뒤 명시적으로 인코딩하세요. 릴리스 검증은 최적화된 Web 기준 환경에서 처리량을 측정하지만, 그 장비별 기준값이 모든 브라우저와 기기의 실행 시간을 보장하지는 않습니다.

CRC-32 무결성 검사

Hash.crc32(data)는 0..4294967295 범위의 부호 없는 CRC-32/ISO-HDLC 값을 반환합니다. 파일 형식과 전송 데이터의 무결성 필드에 사용할 수 있지만 암호학적 다이제스트가 아니므로 인증이나 적대적 변조 방지에 사용하면 안 됩니다.

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

이 예제는 3421780262를 출력합니다. 해석기·생성 Rust·생성 Python·raw Web·Web Worker·플레이그라운드는 같은 부호 없는 정수를 만듭니다. std.hash.crc32도 같은 연산을 제공합니다.

결정적 고정 DEFLATE

파일 형식에 정본 raw 고정 허프만 DEFLATE 블록 하나가 필요하면 Codec.deflateFixedCompress(bytes)를 사용하세요. 결과에는 zlib·gzip 헤더나 검사합이나 트레일러가 붙지 않습니다. 탐색과 메모리 사용량은 제한되며, 입력이 256 MiB를 넘으면 Err를 반환합니다.

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

해석기·생성 Rust·raw Web·Web Worker·플레이그라운드는 같은 바이트를 만듭니다. 생성 Python은 산출물을 쓰기 전에 이 함수를 명시적으로 거절합니다.

결정적 고정 zlib

파일 형식에 raw DEFLATE가 아니라 완성된 결정적 zlib 스트림이 필요하면 Codec.zlibFixedCompress(bytes)를 사용하세요. 이 함수는 고정 78 01 헤더, 위에서 설명한 정확한 고정 허프만 스트림, 원본 입력의 Adler-32 트레일러를 차례로 씁니다. 입력이 256 MiB를 넘으면 Err를 반환합니다.

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

이 예제는 7801cb48cdc9c90700062c0215를 출력합니다. 해석기·생성 Rust·raw Web·Web Worker·플레이그라운드는 같은 바이트를 만들고, 생성 Python은 산출물을 쓰기 전에 이 함수를 거절합니다. 이 연산은 범용 Adler-32·압축 해제·압축 단계·사전·스트리밍을 추가하지 않습니다.

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개 조각을 사용할 수 있습니다. 이 함수는 보호 바이트만 만들며 오류를 탐지하거나 고치지 않습니다. 해석기·생성 Rust·raw Web·Web Worker·플레이그라운드는 정확히 같은 결과를 냅니다. 생성 Python은 산출물을 쓰기 전에 이 함수를 거절합니다.

현재 지원

현재 검사기는 여기에 나열한 함수와 멤버의 매개변수·반환 타입을 확인합니다. 각 대상은 지원하지 않는 기능을 다른 결과로 대체하지 않고 산출물 생성 전에 거부합니다.

제약과 제외

잘못된 숫자 문자열, 유효하지 않은 코드 포인트, 지원하지 않는 타입의 문자열 변환, 타입이 맞지 않는 콜백은 명시적으로 실패합니다. 호스트의 로케일, 정수 래핑, 임의 예외 처리를 암묵적으로 따르지 않습니다.

예제

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}")

관련 정책