Картирование строк из C – учебник

Работа со строками C

В языке C нет специального типа для строк. Разработчик узнает из сигнатуры метода или документации, является ли данная char * строкой C в данном контексте. Строки в языке C имеют нулевую терминацию; нулевой символ \0 добавляется в конец последовательности байтов для обозначения конца строки. Обычно используются строки, закодированные в кодировке UTF-8. Кодировка UTF-8 использует символы переменной длины и обратно совместима с ASCII. Kotlin/Native по умолчанию использует кодировку UTF-8.

Лучший способ понять сопоставление между языками C и Kotlin — это попробовать это на небольшом примере. Создайте небольшие заголовки библиотек для этого. Сначала создайте файл lib.h со следующим объявлением функций, работающих со строками C:

#ifndef LIB2_H_INCLUDED
#define LIB2_H_INCLUDED

void pass_string(char* str);
char* return_string();
int copy_string(char* str, int size);

#endif

В примере вы видите наиболее распространённые способы передачи или получения строки на языке C. Внимательно относитесь к возвращаемому значению return_string. В целом, лучше убедиться, что вы используете правильную функцию для освобождения возвращаемого char* с помощью правильного вызова функции free(..).

Kotlin/Native поставляется со средством cinterop; это средство генерирует связи между языком C и Kotlin. Оно использует файл .def для указания C-библиотеки для импорта. Более подробная информация об этом содержится в учебнике Взаимодействие с C-библиотеками. Самый быстрый способ попробовать отображение C API — поместить все C-объявления в файл interop.def без создания каких-либо .h файлов .c вообще. Затем поместите C-объявления в файл interop.def после специальной разделительной строки ---:

headers = lib.h
---

void pass_string(char* str) {
}

char* return_string() {
  return "C string";
}

int copy_string(char* str, int size) {
  *str++ = 'C';
  *str++ = ' ';
  *str++ = 'K';
  *str++ = '/';
  *str++ = 'N';
  *str++ = 0;
  return 0;
}

Файла interop.def достаточно для компиляции и запуска приложения или открытия его в IDE. Теперь пришло время создать файлы проекта, открыть проект в IntelliJ IDEA и запустить его.

Просмотр сгенерированных Kotlin API для C-библиотеки

Хотя использовать командную строку, либо напрямую, либо комбинируя её со скриптовым файлом (таким как файл .sh или .bat), возможно, этот подход не масштабируется для больших проектов с сотнями файлов и библиотек. Тогда лучше использовать компилятор Kotlin/Native с системой сборки, так как он помогает загружать и кэшировать двоичные файлы и библиотеки компилятора Kotlin/Native с транзитивными зависимостями и запускать компилятор и тесты. Kotlin/Native может использовать систему сборки Gradle через плагин kotlin-multiplatform.

Основы настройки совместимого с IDE проекта с Gradle были рассмотрены в учебнике Простой Kotlin/Native-приложение. Пожалуйста, ознакомьтесь с ним, если вам нужны подробные начальные шаги и инструкции по началу нового проекта Kotlin/Native и его открытию в IntelliJ IDEA. В этом учебнике мы рассмотрим расширенные C-связанные применения Kotlin/Native и многоплатформенные сборки с Gradle с помощью плагина multiplatform.

Сначала создайте папку проекта. Все пути в этом учебнике будут относительными к этой папке. Иногда нужно создать отсутствующие каталоги перед добавлением новых файлов.

Используйте следующий файл сборки Gradle build.gradle(.kts):

plugins {
    kotlin("multiplatform") version "1.9.0"
}

repositories {
    mavenCentral()
}

kotlin {
  linuxX64("native") { // on Linux
  // macosX64("native") { // on x86_64 macOS
  // macosArm64("native") { // on Apple Silicon macOS
  // mingwX64("native") { // on Windows
    val main by compilations.getting
    val interop by main.cinterops.creating
    
    binaries {
      executable()
    }
  }
}

tasks.wrapper {
  gradleVersion = "7.6"
  distributionType = Wrapper.DistributionType.BIN
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.9.0'
}

repositories {
    mavenCentral()
}

kotlin {
  linuxX64('native') { // on Linux
  // macosX64("native") { // on x86_64 macOS
  // macosArm64("native") { // on Apple Silicon macOS
  // mingwX64('native') { // on Windows
    compilations.main.cinterops {
      interop 
    }
    
    binaries {
      executable()
    }
  }
}

wrapper {
  gradleVersion = '7.6'
  distributionType = 'BIN'
}

Файл проекта настраивает C-взаимодействие как дополнительный шаг сборки. Давайте переместим файл interop.def в каталог src/nativeInterop/cinterop. Gradle рекомендует использовать соглашения вместо конфигураций, например, файлы исходного кода должны находиться в папке src/nativeMain/kotlin. По умолчанию все символы из C импортируются в пакет interop, возможно, вам потребуется импортировать весь пакет в наши файлы .kt. Ознакомьтесь с документацией по плагину kotlin-multiplatform, чтобы узнать обо всех способах его настройки.

Давайте создадим файл-заглушку src/nativeMain/kotlin/hello.kt со следующим содержимым, чтобы увидеть, как объявления строк C видны из Kotlin:

import interop.*

fun main() {
  println("Hello Kotlin/Native!")
  
  pass_string(/*fix me*/)
  val useMe = return_string()
  val useMe2 = copy_string(/*fix me*/)
}

Теперь вы готовы открыть проект в IntelliJ IDEA и посмотреть, как исправить пример проекта. Делая это, посмотрите, как строки C отображаются в Kotlin/Native.

Строки в Kotlin

С помощью IntelliJ IDEA Перейти к | Объявлению или ошибок компилятора вы увидите следующий сгенерированный API для C-функций:

fun pass_string(str: CValuesRef<ByteVar /* = ByteVarOf<Byte> */>?)
fun return_string(): CPointer<ByteVar /* = ByteVarOf<Byte> */>?
fun copy_string(str: CValuesRef<ByteVar /* = ByteVarOf<Byte> */>?, size: Int): Int

Эти объявления выглядят понятно. Все указатели char * преобразуются в str: CValuesRef<ByteVar>? для параметров и в CPointer<ByteVar>? в типах возвращаемых значений. Kotlin преобразует тип char в тип kotlin.Byte, так как он обычно представляет собой 8-битовое знаковое значение.

В сгенерированных объявлениях Kotlin вы видите, что str представлен как CValuesRef<ByteVar/>?. Тип является nullable, и вы можете просто передать Kotlin null в качестве значения параметра.

Передать строку Kotlin в C

Давайте попробуем использовать API из Kotlin. Сначала вызовите pass_string:

fun passStringToC() {
  val str = "this is a Kotlin String"
  pass_string(str.cstr)
}

Передача строки Kotlin в C проста благодаря тому, что для этого есть String.cstr расширенное свойство в Kotlin. Также есть String.wcstr для случаев, когда вам нужны символы UTF-16 расширенной ширины.

Чтение строк C в Kotlin

На этот раз вы получите возвращаемое char * из функции return_string и преобразуете его в строку Kotlin. Для этого сделайте следующее в Kotlin:

fun passStringToC() {
  val stringFromC = return_string()?.toKString()
  
  println("Returned from C: $stringFromC")
}

В этом коде используется расширенная функция toKString() выше. Пожалуйста, не пропустите функцию toString(). У функции toKString() есть два перегруженных расширенных метода в Kotlin:

fun CPointer<ByteVar>.toKString(): String
fun CPointer<ShortVar>.toKString(): String

Первый расширенный метод принимает char * в качестве строки UTF-8 и преобразует её в строку. Второй метод делает то же самое, но для строк широкого формата UTF-16.

Получение байтов строки C из Kotlin

На этот раз мы попросим C-функцию записать нам строку C в заданный буфер. Функция называется copy_string. Она принимает указатель на место записи символов и допустимый размер буфера. Функция возвращает значение, указывающее на успех или неудачу. Предположим, 0 означает успех и предоставленного буфера достаточно:

fun sendString() {
  val buf = ByteArray(255)
  buf.usePinned { pinned ->
    if (copy_string(pinned.addressOf(0), buf.size - 1) != 0) {
      throw Error("Failed to read string from C")
    }
  }

  val copiedStringFromC = buf.decodeToString()
  println("Message from C: $copiedStringFromC")
}

Сначала вам нужно получить указатель на нативный буфер, чтобы передать его в C-функцию. Используйте расширенную функцию usePinned, чтобы временно прикрепить нативный адрес памяти массива байтов. C-функция заполняет массив байтов данными. Используйте другую расширенную функцию ByteArray.decodeToString(), чтобы преобразовать массив байтов в Kotlin String, предполагая кодировку UTF-8.

Исправить код

Теперь вы ознакомились со всеми определениями, и пришло время исправить код. Запустите задачу Gradle runDebugExecutableNative в IDE или используйте следующую команду для запуска кода:

./gradlew runDebugExecutableNative

Код в итоговом файле hello.kt может выглядеть следующим образом:

import interop.*
import kotlinx.cinterop.*

fun main() {
  println("Hello Kotlin/Native!")

  val str = "this is a Kotlin String"
  pass_string(str.cstr)

  val useMe = return_string()?.toKString() ?: error("null pointer returned")
  println(useMe)

  val copyFromC = ByteArray(255).usePinned { pinned ->

    val useMe2 = copy_string(pinned.addressOf(0), pinned.get().size - 1)
    if (useMe2 != 0) throw Error("Failed to read string from C")
    pinned.get().decodeToString()
  }

  println(copyFromC)
}

Следующие шаги

Продолжайте изучать другие типы языка C и их представление в Kotlin/Native в наших других учебниках:

• Картирование примитивных типов данных из C

• Картирование структур и объединений из C

• Картирование указателей на функции из C

Документация по C Interop описывает более сложные сценарии взаимодействия.