QkObs

QkObs *qk_obs_zero(uint32_t num_qubits)

(조건 없이) 영 관측값을 구축합니다.

예

QkObs *zero = qk_obs_zero(100);

매개변수

• 숫자_큐비트 - 관측 항목이 정의된 큐비트 수입니다.

리턴

생성된 관찰 가능 항목에 대한 포인터입니다.

QkObs *qk_obs_identity(uint32_t num_qubits)

관찰 가능한 아이덴티티를 구축합니다.

예

QkObs *identity = qk_obs_identity(100);

매개변수

• 숫자_큐비트 - 관측 항목이 정의된 큐비트 수입니다.

리턴

생성된 관찰 가능 항목에 대한 포인터입니다.

QkObs *qk_obs_new(uint32_t num_qubits, uint64_t num_terms, uint64_t num_bits, QkComplex64 *coeffs, QkBitTerm *bit_terms, uint32_t *indices, size_t *boundaries)

원시 데이터에서 새로운 관측값을 생성합니다.

포인터 인자 중 어느 것이든 해당 길이가 0일 때에만 NULL 해당할 수 있다.

예

// define the raw data for the 100-qubit observable |01><01|_{0, 1} - |+-><+-|_{98, 99}
uint32_t num_qubits = 100;
uint64_t num_terms = 2;  // we have 2 terms: |01><01|, -1 * |+-><+-|
uint64_t num_bits = 4; // we have 4 non-identity bits: 0, 1, +, -
QkComplex64 coeffs[] = {{1, 0}, {-1, 0}};
QkBitTerm bits[4] = {QkBitTerm_Zero, QkBitTerm_One, QkBitTerm_Plus, QkBitTerm_Minus};

uint32_t indices[4] = {0, 1, 98, 99};  // <-- e.g. {1, 0, 99, 98} would be invalid
size_t boundaries[3] = {0, 2, 4};
QkObs *obs = qk_obs_new(
    num_qubits, num_terms, num_bits, coeffs, bits, indices, boundaries
);
qk_obs_free(obs);

안전

다음 조건 중 하나라도 위반하면 동작이 정의되지 않습니다:

• coeffs 는 QkComplex64 길이의 배열에 대한 포인터입니다 num_terms
• bit_terms 는 길이가 유효한 QkBitTerm 요소의 배열에 대한 포인터입니다 num_bits
• indices 는 길이 num_bits 의 uint32_t 배열에 대한 포인터로, 엄격한 오름차순으로 정렬되며 모든 요소는 다음보다 작습니다 num_qubits
• boundaries 는 오름차순으로 정렬된 num_terms + 1 길이의 size_t 배열에 대한 포인터로, 첫 번째 요소는 0이고 마지막 요소는 다음보다 작습니다 num_terms

매개변수

• 숫자_큐비트 - 관측 항목이 정의된 큐비트 수입니다.
• num_terms - 학기 수입니다.
• num_bits - 비식별 비트 용어의 총 개수입니다.
• coeffs - 길이가 num_terms 인 계수 배열의 첫 번째 요소에 대한 포인터입니다.
• bit_terms - 비트 용어 배열의 첫 번째 요소에 대한 포인터로, 길이가 num_bits 입니다.
• 인덱스 - 길이가 num_bits 인 인덱스 배열의 첫 번째 요소에 대한 포인터입니다. 용어별로 점진적으로 정렬해야 한다는 점에 유의하세요.
• 경계 - 길이가 num_terms + 1 인 경계 배열의 첫 번째 요소에 대한 포인터입니다.

리턴

입력 데이터가 일관되고 구성이 성공적이었다면, 그 결과는 관찰 가능성에 대한 포인터가 됩니다. 그렇지 않으면 널 포인터가 반환됩니다.

void qk_obs_free(QkObs *obs)

관찰 가능한 것을 해제하세요.

예

QkObs *obs = qk_obs_zero(100);
qk_obs_free(obs);

안전

obs 이 null이 아니거나 QkObs 에 대한 유효한 포인터가 아닌 경우 동작이 정의되지 않습니다.

매개변수

• obs - 관찰할 수 있는 무료에 대한 포인터입니다.

QkExitCode qk_obs_add_term(QkObs *obs, const QkObsTerm *cterm)

관찰 가능 항목에 용어를 추가합니다.

예

uint32_t num_qubits = 100;
QkObs *obs = qk_obs_zero(num_qubits);

QkComplex64 coeff = {1, 0};
QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
uint32_t indices[3] = {0, 1, 2};
QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};

QkExitCode exit_code = qk_obs_add_term(obs, &term);

안전

다음 중 하나라도 위반하면 동작이 정의되지 않습니다:

• obs 는 널이 아닌 유효한 포인터입니다 QkObs
• cterm 는 널이 아닌 유효한 포인터입니다 QkObsTerm

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.
• 학기 - 추가할 학기에 대한 포인터입니다.

리턴

종료 코드입니다. 용어가 일관성이 없거나 용어 추가에 실패한 경우 >0 입니다.

QkExitCode qk_obs_term(QkObs *obs, uint64_t index, QkObsTerm *out)

참조로 관찰 가능한 용어를 가져옵니다.

QkObsTerm 에는 해당 용어의 인덱스와 비트 용어에 대한 포인터가 포함되어 있으며, 이 포인터는 옵저버블의 내부 데이터를 수정하는 데 사용할 수 있습니다. 이렇게 하면 관찰 가능한 내용이 일관성 없는 상태로 남을 수 있으므로 세심한 주의를 기울이지 않는 한 피해야 합니다. 일반적으로 제자리에서 수정을 시도하는 대신 새 관측값을 만드는 것이 더 안전합니다.

예

QkObs *obs = qk_obs_identity(100);
QkObsTerm term;
QkExitCode exit_code = qk_obs_term(obs, 0, &term);
// out-of-bounds indices return an error code
// QkExitCode error = qk_obs_term(obs, 12, &term);

안전

다음 중 하나라도 위반하는 경우 동작이 정의되지 않습니다

• obs 는 널이 아닌 유효한 포인터입니다 QkObs
• out 는 널이 아닌 유효한 포인터입니다 QkObsTerm

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.
• 색인 - 가져올 용어의 색인입니다.
• out - 관찰 가능한 용어를 반환하는 데 사용되는 QkObsTerm 포인터입니다.

리턴

종료 코드입니다.

size_t qk_obs_num_terms(const QkObs *obs)

관찰 가능한 용어의 개수를 가져옵니다.

예

QkObs *obs = qk_obs_identity(100);
size_t num_terms = qk_obs_num_terms(obs);  // num_terms==1

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

관찰 가능한 용어의 수입니다.

uint32_t qk_obs_num_qubits(const QkObs *obs)

옵저버블이 정의된 큐비트 수를 가져옵니다.

예

QkObs *obs = qk_obs_identity(100);
uint32_t num_qubits = qk_obs_num_qubits(obs);  // num_qubits==100

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

옵저버블이 정의된 큐비트 수입니다.

size_t qk_obs_len(const QkObs *obs)

옵저버블의 비트 텀/인덱스 수를 가져옵니다.

예

QkObs *obs = qk_obs_identity(100);
size_t len = qk_obs_len(obs);  // len==0, as there are no non-trivial bit terms

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

관찰 가능한 용어의 수입니다.

QkComplex64 *qk_obs_coeffs(QkObs *obs)

계수에 대한 포인터를 가져옵니다.

관측값의 계수를 읽고 수정하는 데 사용할 수 있습니다. 결과 포인터는 QkComplex64 의 qk_obs_num_terms(obs) 요소에 대해 읽을 수 있습니다.

예

QkObs *obs = qk_obs_identity(100);
size_t num_terms = qk_obs_num_terms(obs);
QkComplex64 *coeffs = qk_obs_coeffs(obs);

for (size_t i = 0; i < num_terms; i++) {
    printf("%f + i%f\n", coeffs[i].re, coeffs[i].im);
}

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

계수에 대한 포인터입니다.

uint32_t *qk_obs_indices(QkObs *obs)

인덱스에 대한 포인터를 가져옵니다.

옵저버블의 인덱스를 읽고 수정하는 데 사용할 수 있습니다. 결과 포인터는 uint32_t 크기의 qk_obs_len(obs) 요소에 대해 읽을 수 있습니다.

예

uint32_t num_qubits = 100;
QkObs *obs = qk_obs_zero(num_qubits);

QkComplex64 coeff = {1, 0};
QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
uint32_t term_indices[3] = {0, 1, 2};
QkObsTerm term = {coeff, 3, bit_terms, term_indices, num_qubits};
qk_obs_add_term(obs, &term);

size_t len = qk_obs_len(obs);
uint32_t *indices = qk_obs_indices(obs);

for (size_t i = 0; i < len; i++) {
    printf("index %i: %i\n", i, indices[i]);
}

qk_obs_free(obs);

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

인덱스에 대한 포인터입니다.

size_t *qk_obs_boundaries(QkObs *obs)

경계라는 용어에 대한 포인터를 가져옵니다.

옵저버블의 용어 경계를 읽고 수정하는 데 사용할 수 있습니다. 결과 포인터는 size_t 크기의 qk_obs_num_terms(obs) + 1 요소에 대해 읽을 수 있습니다.

예

uint32_t num_qubits = 100;
QkObs *obs = qk_obs_zero(num_qubits);

QkComplex64 coeff = {1, 0};
QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
uint32_t indices[3] = {0, 1, 2};
QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};
qk_obs_add_term(obs, &term);

size_t num_terms = qk_obs_num_terms(obs);
size_t *boundaries = qk_obs_boundaries(obs);

for (size_t i = 0; i < num_terms + 1; i++) {
    printf("boundary %i: %i\n", i, boundaries[i]);
}

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

경계를 가리키는 포인터입니다.

QkBitTerm *qk_obs_bit_terms(QkObs *obs)

비트 용어에 대한 포인터를 가져옵니다.

옵저버블의 비트 용어를 읽고 수정하는 데 사용할 수 있습니다. 결과 포인터는 uint8_t 크기의 qk_obs_len(obs) 요소에 대해 읽을 수 있습니다.

예

uint32_t num_qubits = 100;
QkObs *obs = qk_obs_zero(num_qubits);

QkComplex64 coeff = {1, 0};
QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
uint32_t indices[3] = {0, 1, 2};
QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};
qk_obs_add_term(obs, &term);

size_t len = qk_obs_len(obs);
QkBitTerm *bits = qk_obs_bit_terms(obs);

for (size_t i = 0; i < len; i++) {
    printf("bit term %i: %i\n", i, bits[i]);
}

qk_obs_free(obs);

안전

'Behavior is undefined'는 유효하지 obs 않거나 null이 아닌 포인터가 아니거나, 결과 QkBitTerm 포인터에 유효하지 QkObs 않은 값이 기록된 경우입니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

비트 용어에 대한 포인터입니다.

QkObs *qk_obs_multiply(const QkObs *obs, const QkComplex64 *coeff)

관측 가능 항목에 복소수 계수를 곱합니다.

예

QkObs *obs = qk_obs_identity(100);
QkComplex64 coeff = {2, 0};
QkObs *result = qk_obs_multiply(obs, &coeff);

안전

다음 중 하나라도 위반하는 경우 동작이 정의되지 않습니다

• obs 는 널이 아닌 유효한 포인터입니다 QkObs
• coeff 는 널이 아닌 유효한 포인터입니다 QkComplex64

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.
• coeff - 관측값에 곱할 계수입니다.

리턴

결과에 대한 obs * coeff포인터.

void qk_obs_multiply_inplace(QkObs *obs, const QkComplex64 *coeff)

현재 위치의 관측값에 복소수 계수를 곱합니다.

예

QkObs *obs = qk_obs_identity(100);
QkComplex64 coeff = {2, 0};
qk_obs_multiply_inplace(obs, &coeff);

안전

다음 중 하나라도 위반하는 경우 동작이 정의되지 않습니다

• obs 는 널이 아닌 유효한 포인터입니다 QkObs
• coeff 는 널이 아닌 유효한 포인터입니다 QkComplex64

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.
• coeff - 관측값에 곱할 계수입니다.

QkObs *qk_obs_add(const QkObs *left, const QkObs *right)

두 개의 관찰 항목을 추가합니다.

예

QkObs *left = qk_obs_identity(100);
QkObs *right = qk_obs_zero(100);
QkObs *result = qk_obs_add(left, right);

안전

left 또는 right 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 왼쪽 - 왼쪽 관찰 가능 영역에 대한 포인터입니다.
• 오른쪽 - 오른쪽 관찰 가능 영역에 대한 포인터입니다.

리턴

결과에 대한 포인터 left + right.

void qk_obs_add_inplace(QkObs *left, const QkObs *right)

기존의 observable에 새로운 observable을 추가합니다.

예

QkObs *left = qk_obs_identity(100);
QkObs *right = qk_obs_zero(100);
qk_obs_add_inplace(left, right);

안전

left 또는 right 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 왼쪽 - 왼쪽 관찰 가능 영역에 대한 포인터입니다.
• 오른쪽 - 오른쪽 관찰 가능 영역에 대한 포인터입니다.

QkObs *qk_obs_scaled_add(const QkObs *left, const QkObs *right, const QkComplex64 *factor)

두 개의 관측 변수를 추가하고, 오른쪽 관측 변수의 계수를 조정합니다.

예

QkObs *left = qk_obs_zero(100);
QkObs *right = qk_obs_identity(100);
QkComplex64 factor = {2, 0};
QkObs *result = qk_obs_scaled_add(left, right, &factor);

안전

left 또는 right 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 왼쪽 - 왼쪽 관찰 가능 영역에 대한 포인터입니다.
• 오른쪽 - 오른쪽 관찰 가능 영역에 대한 포인터입니다.
• 계수 – 계수에 곱할 계수.

리턴

결과를 가리키는 소유 left + factor * right 포인터.

void qk_obs_scaled_add_inplace(QkObs *left, const QkObs *right, const QkComplex64 *factor)

기존의 관측 가능 객체에 스케일링된 관측 가능 객체를 추가합니다.

예

QkObs *left = qk_obs_zero(100);
QkObs *right = qk_obs_identity(100);
QkComplex64 factor = {2, 0};
qk_obs_scaled_add_inplace(left, right, &factor);

안전

left 또는 right 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 왼쪽 - 왼쪽 관찰 가능 영역에 대한 포인터입니다.
• 오른쪽 - 오른쪽 관찰 가능 영역에 대한 포인터입니다.
• 계수 – 계수에 곱할 계수.

QkObs *qk_obs_compose(const QkObs *first, const QkObs *second)

두 개의 관측값을 구성(곱하기)합니다.

예

QkObs *first = qk_obs_zero(100);
QkObs *second = qk_obs_identity(100);
QkObs *result = qk_obs_compose(first, second);

안전

first 또는 second 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 첫째 - 하나의 관찰 가능.
• 둘째 - 다른 관찰 가능.

리턴

first.compose(second) 는 행렬 곱셈의 관점에서 관찰 가능한 result = second @ first, @ 과 동일합니다.

QkObs *qk_obs_compose_map(const QkObs *first, const QkObs *second, const uint32_t *qargs)

사용자 지정 큐비트 순서에 따라 두 개의 관측값을 구성(곱하기)합니다.

특히, 크기가 다른 두 개의 관측값을 구성할 수 있습니다.

예

QkObs *first = qk_obs_zero(100);
QkObs *second = qk_obs_identity(100);
QkObs *result = qk_obs_compose(first, second);

안전

이 함수를 안전하게 호출하려면

• first 와 second 는 QkObs\ s에 대한 널이 아닌 유효한 포인터여야 합니다
• qargs 는 qk_obs_num_qubits(second) 요소( second 의 큐비트 수를 의미)에 대해 읽을 수 있는 uint32_t 배열을 가리켜야 합니다

매개변수

• 첫째 - 하나의 관찰 가능.
• 둘째 - 다른 관찰 가능. 큐비트 수는 qargs 의 길이와 일치해야 합니다.
• qargs - second 의 인덱스와 연결할 first 의 인덱스를 지정하는 쿼비트 인자입니다.

리턴

first.compose(second) 는 행렬 곱셈의 관점에서 관찰 가능한 result = second @ first, @ 과 동일합니다.

QkExitCode qk_obs_apply_layout(QkObs *obs, const uint32_t *layout, uint32_t num_qubits)

옵저버블에 새 큐비트 레이아웃을 적용합니다.

레이아웃은 새 인덱스의 배열 layout 로 설정되며, 현재 인덱스 i 의 큐비트가 인덱스 layout[i] 로 레이블이 변경되도록 지정합니다. 옵저버블이 작동하는 큐비트 수는 현재 옵저버블보다 큰 num_qubits 을 설정하여 확장할 수 있습니다.

예

이 인터페이스를 사용하면 큐비트 인덱스의 레이블을 다시 지정하고 확장할 수 있습니다:

QkObs *obs = qk_obs_zero(4);

// add a term to the observable
QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};
uint32_t qubits[3] = {1, 2, 3};
complex double coeff = 1;
QkObsTerm term = {coeff, 3, bit_terms, qubits, 4};
qk_obs_add_term(obs, &term);

uint32_t layout[3] = {0, 10, 9};  // qubit mapping is: 0->0, 1->10, 2->9
uint32_t num_output_qubits = 11;
QkExitCode exit = qk_obs_apply_layout(obs, layout, num_output_qubits);

컴파일러 워크플로에서 이 함수는 트랜스파일러 패스에서 얻은 QkTranspileLayout* (다음 예제에서는 transpile_layout )를 적용하는 데 편리하게 사용할 수 있습니다:

// get the number of output qubits
uint32_t num_output_qubits = qk_transpile_layout_num_output_qubits(transpile_layout);

// get the layout including the ancillas (hence the ``false`` in the function call)
uint32_t *layout = malloc(sizeof(uint32_t) * num_output_qubits);
qk_transpile_layout_final_layout(transpile_layout, false, layout);

// apply the layout
QkExitCode exit = qk_obs_apply_layout(obs, layout, num_output_qubits);

// free the layout array
free(layout);

안전

obs 가 QkObs 에 대한 유효하고 널이 아닌 포인터가 아니거나 layout 가 qk_obs_num_qubits(obs) 의 연속된 요소 시퀀스에 대한 유효하고 널이 아닌 포인터가 아닌 경우 동작이 정의되지 않습니다 uint32_t.

매개변수

• obs - 관찰 가능 항목에 대한 포인터로, 성공 시 이 관찰 가능 항목이 제자리에서 수정됩니다. 종료 코드를 확인하여 레이아웃이 올바르게 적용되었는지 확인합니다.
• 레이아웃 - 레이아웃에 대한 포인터입니다. 포인터는 uint32_t 유형의 qk_obs_num_qubits(obs) 요소에 대한 배열을 가리켜야 합니다. 각 요소는 [0, num_qubits) 의 값을 가져야 합니다.
• 숫자_큐비트 - 출력 큐비트 수입니다.

리턴

종료 코드입니다.

• QkExitCode_Success 성공 시
• QkExitCode_DuplicteIndexError 중복 큐비트 인덱스가 발견된 경우
• QkExitCode_MismatchedQubits num_qubits 이 관찰 가능한 큐비트 수보다 작으면
• QkExitCode_IndexError 의 유효하지 않은 값과 같은 다른 인덱스 오류를 확인하려면 layout.

QkObs *qk_obs_canonicalize(const QkObs *obs, double tol)

관측 가능 영역의 정식 표현을 계산합니다.

예

QkObs *iden = qk_obs_identity(100);
QkObs *two = qk_obs_add(iden, iden);

double tol = 1e-6;
QkObs *canonical = qk_obs_canonicalize(two, tol);

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.
• tol - 계수가 0으로 간주되는 허용 오차 범위입니다.

리턴

관측 가능 영역의 정식 표현입니다.

QkObs *qk_obs_copy(const QkObs *obs)

관찰 항목을 복사합니다.

예

QkObs *original = qk_obs_identity(100);
QkObs *copied = qk_obs_copy(original);

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

매개변수

• obs - 관찰 가능 항목에 대한 포인터입니다.

리턴

관찰 가능 항목의 복사본에 대한 포인터입니다.

bool qk_obs_equal(const QkObs *obs, const QkObs *other)

두 관측값의 동일성을 비교합니다.

이는 수학적 동등성을 비교하는 것이 아니라 데이터 동등성을 비교한다는 점에 유의하세요. 즉, 두 관측값은 동일한 관측값을 나타내지만 동일하게 비교할 수는 없습니다.

예

QkObs *observable = qk_obs_identity(100);
QkObs *other = qk_obs_identity(100);
bool are_equal = qk_obs_equal(observable, other);

안전

obs 또는 other 이 QkObs\ s에 대한 유효하지 않은 널이 아닌 포인터인 경우 동작이 정의되지 않습니다.

매개변수

• 관찰 - 하나의 관찰 가능 항목에 대한 포인터입니다.
• 기타 - 다른 관찰 가능 항목에 대한 포인터입니다.

리턴

true 관측값이 같으면 false , 그렇지 않으면.

char *qk_obs_str(const QkObs *obs)

QkObs 의 문자열 표현을 반환합니다.

예

QkObs *obs = qk_obs_identity(100);
char *string = qk_obs_str(obs);
qk_str_free(string);
qk_obs_free(obs);

안전

동작이 정의되지 않았습니다 obs 은 QkObs 에 대한 유효한 널이 아닌 포인터가 아닙니다.

문자열은 일반적인 C 해제로는 해제할 수 없으며 qk_str_free 을 사용하여 문자열이 사용하는 메모리를 해제해야 합니다. qk_str_free 을 호출하지 않으면 메모리 누수가 발생할 수 있습니다.

값을 변경할 수는 있지만 문자열이 반환된 후에는 문자열 내부 어딘가에 널 바이트를 쓰거나 마지막 바이트를 제거하여 문자열의 길이를 변경하지 마세요.

매개변수

• 관찰 - 문자열을 가져올 QkObs 에 대한 포인터입니다.

리턴

에 대한 문자열 표현의 널로 끝나는 문자 배열에 대한 포인터입니다 obs

void qk_str_free(char *string)

문자열 표현을 해제합니다.

안전

str 가 qk_obs_str 또는 qk_obsterm_str 에서 반환하는 포인터가 아닌 경우 동작이 정의되지 않습니다.

매개변수

• 문자열 - qk_obs_str 또는 qk_obsterm_str 에서 반환된 문자열 표현에 대한 포인터입니다.

PyObject *qk_obs_to_python(QkObs *obs)

객체의 QkObs 소유권을 Python 에 전달합니다.

이 함수를 호출한 후에는 QkObs 포인터를 사용하는 것이 안전하지 않습니다. 특히, 이를 지우거나 해제하려고 시도해서는 안 됩니다. 호출자는 해당 객체를 소유하고 QkObs있어야 하며, 빌린 참조를 가지고 있어서는 안 됩니다(예를 들어 qk_obs_borrow_from_python , 에서 가져온 QkObs * 객체는 소유권이 없습니다).

안전

호출자는 Python 인터프리터에 연결되어 있어야 합니다. 가 초기화되고 소유권이 있는 에 대한 유효한 비공백 포인터가 QkObs 아닌 obs 경우 동작이 정의되지 않습니다.

매개변수

• obs – 소유된 객체.

리턴

해당 객체에 대한 Python 참조.

QkObs *qk_obs_borrow_from_python(PyObject *ob)

Python 객체에서 QkObs 포인터를 가져옵니다.

이 코드는 Python 참조를 가져와, 해당 참조가 올바른 유형일 경우 그 QkObs 포인터를 추출합니다. 반환된 포인터는 해당 ob 포인터에서 빌려온 것입니다. 의 유형이 올바르지 않은 PyObject 경우, 반환 값은 이 NULL 되며 Python 인터프리터의 예외 상태가 설정됩니다.

이 함수를 호출하려면 Python 인터프리터가 연결되어 있어야 합니다.

또한 를 사용할 수도 있습니다 qk_obs_convert_from_python. 이는 논리적으로는 이 함수와 완전히 동일하지만, Python 변환 함수 계열에 PyArg_Parse* 대한 “변환기” 함수로 직접 사용할 수 있습니다.

안전

호출자는 Python 인터프리터에 연결되어 있어야 합니다. 가 Python 객체를 가리키는 유효한 비공백 포인터가 아닌 ob 경우 동작이 정의되지 않습니다.

매개변수

• ob – 차용된 Python 객체.

리턴

네이티브 객체에 대한 포인터이거나, NULLPython 객체의 유형이 올바르지 않은 경우.

int qk_obs_convert_from_python(PyObject *object, void *address)

Python 객체에서 QkObs 포인터를 가져옵니다.

이 코드는 Python 참조를 가져와, 해당 QkObs 포인터가 올바른 유형인 경우 이를 address``로 추출합니다. 반환된 포인터는 해당 object 포인터에서 빌려온 것입니다. 의 PyObject 유형이 올바르지 않은 경우, 반환 값은 1이 되며, Python 인터프리터의 예외 상태가 설정되고 는 변경되지 address 않습니다.

이 함수를 호출하려면 Python 인터프리터가 연결되어 있어야 합니다.

또한 를 qk_obs_borrow_from_python사용할 수도 있는데, 이는 논리적으로는 이와 완전히 동일하지만 직접 사용할 때 더 자연스러운 시그니처를 갖습니다.

안전

호출자는 Python 인터프리터에 연결되어 있어야 합니다. 가 유효한 null이 아닌 Python 객체 포인터가 object 아니거나, 가 올바른 유형의 쓰기 가능한 address 데이터에 대한 포인터가 아닌 경우 동작이 정의되지 않습니다.

매개변수

• 객체 – 빌려온 Python 객체.
• 주소 – 출력을 기록할 위치.

리턴

성공 시 1, 실패 시 0.