Преобразование строк из 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. Самый быстрый способ попробовать сопоставление API C — поместить все объявления C в файл interop.def без создания каких-либо .h или .c файлов вообще. Затем поместите объявления C в файл interop.def после специальной разделительной строки ---.

headers = lib.h
---

void pass_string(char* str) {
}

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

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.

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

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

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

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 = "6.7.1"
  distributionType = Wrapper.DistributionType.BIN
}

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

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 = '6.7.1'
  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/>?. Тип является необязательным, и вы можете просто передать 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 и преобразует ее в String. Вторая функция делает то же самое, но для широких строк 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.stringFromUtf8()
  println("Message from C: $copiedStringFromC")
}

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

Исправление кода

Теперь вы видели все определения, и пришло время исправить код. Запустите задачу runDebugExecutableNative Gradle в 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().stringFromUtf8()
  }

  println(copyFromC)
}

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

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

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

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

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

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