Класс QCborValue

Класс QCborValue инкапсулирует значение в CBOR. Подробнее...

Этот класс был представлен в Qt 5.12.

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Общедоступные типы

Общедоступные функции

Статические публичные члены

Подробное описание

Этот класс может использоваться для хранения одного из многих типов, доступных в CBOR. CBOR — это компактное двоичное представление объектов, очень компактный формат двоичного кодирования данных, представляющий собой надмножество JSON. Он был создан рабочей группой IETF Constrained RESTful Environments (CoRE), которая использовала его во многих новых RFC. Он предназначен для совместного использования с протоколом CoAP.

CBOR имеет три группы встроенных типов:

• Основные типы: целые числа, числа с плавающей точкой (double), логические значения, null и т. д.
• Типы, подобные строкам: строки и массивы байтов
• Контейнеры: массивы и карты

Кроме того, CBOR поддерживает форму расширяемости типов, связывая «метку» с одним из вышеперечисленных типов, чтобы передать больше информации. Например, UUID представлен меткой и массивом байтов, содержащим 16 байтов содержимого UUID. QCborValue поддерживает прямое создание и декодирование нескольких из этих расширенных типов с помощью классов Qt (например, QUuid).

Полный список см. в QCborValue::Type. Тип QCborValue можно запросить с помощью type() или одной из функций «isXxxx».

Расширенные типы и помеченные значения

Помеченное значение — это обычный QCborValue, который связан с числом, представляющим его метку. См. QCborKnownTags для получения дополнительной информации о метках в API, а также о полном официальном списке. Такие комбинации образуют расширенные типы.

QCborValue поддерживает определенные расширенные типы в API, такие как URL (с QUrl) и UUID (с QUuid). Другие расширенные типы, не поддерживаемые в API, представлены QCborValue типа Tag. Метку позже можно получить с помощью tag(), а помеченное значение — с помощью taggedValue().

Для обеспечения обратной совместимости QCborValue, содержащие расширенные типы Qt, сравниваются по значению с типом метки с тем же содержимым. Другими словами, следующее выражение истинно:

    QCborValue(uuid) == QCborValue(QCborKnownTags::Uuid, uuid.toRfc4122());

Неопределенные и null-значения

QCborValue может содержать значение «null», которое не является какого-либо определенного типа. Оно напоминает C++ std::nullptr_t тип, единственное возможное значение которого — nullptr. QCborValue имеет конструктор, принимающий такой тип, и создаёт null QCborValue.

Null-значения используются для обозначения того, что необязательное значение отсутствует. В этом аспекте оно аналогично типу C++ Стандартной библиотеки std::optional, когда он отключён. В отличие от C++ типа, CBOR null-значения имеют просто тип «Null», и определить, какой конкретный тип он замещает, нельзя.

QCborValue также может иметь тип «undefined», представляющий значение «undefined». Фактически, именно это создаёт конструктор QCborValue по умолчанию.

Неопределённые значения отличаются от null-значений. В то время как null-значения используются для обозначения необязательного значения, которое не предоставлено, Undefined обычно используется для обозначения того, что ожидаемое значение не может быть предоставлено, обычно из-за ошибки или условия, которое не может быть выполнено.

Такие значения полностью допустимы и могут появляться в потоках CBOR, в отличие от содержимого JSON и QJsonValue«undefined» бит. Но, как и undefined в QJsonValue, он возвращается методом value() или оператором [] для некорректных запросов (выход за пределы диапазона для QCborArray или отсутствующий ключ для QCborMap). Нельзя отличить такой случай от значения Undefined, поэтому, если это требуется, проверьте размер QCborArray и используйте API итератора QCborMap.

Простые типы

CBOR поддерживает дополнительные простые типы, которые, как Null и Undefined, не несут никакого другого значения. Они называются взаимозаменяемо «Простые типы» и «Простые значения». CBOR кодирует булевы значения как два различных типа (один для true и один для false), но QCborValue имеет удобный API для них.

В настоящее время нет других определённых простых типов CBOR. QCborValue поддерживает их просто по их номеру с API, таким как isSimpleType() и toSimpleType(), доступными для совместимости с будущими спецификациями до обновления API Qt. Их использование до такой спецификации не рекомендуется, так как другие реализации CBOR могут не поддерживать их полностью.

Поддержка CBOR

QCborValue поддерживает все функции CBOR, необходимые для создания канонических и строгих потоков. Он реализует почти все функции, указанные в RFC 7049.

В следующей таблице перечислены функции CBOR, которые поддерживает QCborValue.

Целые числа в QCborValue ограничены диапазоном типа qint64. То есть, от -9 223 372 036 854 775 808 (-2⁶³) до 9 223 372 036 854 775 807 (2⁶³ - 1). Сам CBOR может представлять целые значения за пределами этого диапазона, чего QCborValue не поддерживает. При декодировании потока с помощью fromCbor() содержащего одно из таких значений, QCborValue автоматически преобразует его в Double, но это может привести к потере до 11 бит точности.

fromCbor() может декодировать разбиение строк, но всегда объединяет куски в одно QCborValue. По этой причине, он всегда записывает неразбитые строки при использовании toCbor() (что необходимо для канонического формата).

QCborValue всегда преобразует значения с плавающей точкой одинарной и полуточной точности в потоке CBOR в значения двойной точности. Функция toCbor() может принимать параметр, указывающий на необходимость их восстановления.

QCborValueRef

QCborValueRef — вспомогательный класс для QCborArray и QCborMap. Это тип, который вы получаете при использовании одного из методов изменения в этих классах. В отличие от QCborValue, в этот класс можно назначать новые значения. При этом массив или словарь, на который он ссылается, будут изменены с новым значением. Во всех других аспектах его API идентичен QCborValue.

QJsonValue, QJsonDocument

См. также QCborArray, QCborMap, QCborStreamReader и QCborStreamWriter.

Документация типов членов

enum QCborValue::DiagnosticNotationOptionflags QCborValue::DiagnosticNotationOptions

Этот перечисление используется в аргументе options функции toDiagnosticNotation() для изменения формата вывода.

В настоящее время ExtendedFormat изменяет способ представления массивов байтов. Без него они всегда кодируются в шестнадцатеричном формате без пробелов. С ним QCborValue::toCbor() будет использовать шестнадцатеричное кодирование с пробелами, base64 или base64url кодирование, в зависимости от контекста.

Тип DiagnosticNotationOptions является псевдонимом для QFlags<DiagnosticNotationOption>. Он хранит комбинацию значений DiagnosticNotationOption, объединенных операцией ИЛИ.

См. также toDiagnosticNotation().

enum QCborValue::EncodingOptionflags QCborValue::EncodingOptions

Это перечисление используется в аргументе options функции toCbor(), изменяя поведение кодировщика.

Использование UseFloat16 необходимо для кодирования потока в каноническом формате, но не обязательно в других случаях.

Тип EncodingOptions является псевдонимом для QFlags<EncodingOption>. Он хранит комбинацию значений EncodingOption, объединенных операцией ИЛИ.

См. также toCbor().

enum QCborValue::Type

Это перечисление представляет тип QCborValue. Оно возвращается функцией type().

Встроенные типы CBOR:

Кроме того, QCborValue может представлять расширенные типы:

См. также type().

Документация функций-членов

Это перегруженная функция.

Преобразует len байтов data в QByteArray и затем вызывает перегрузку этой функции, принимающую QByteArray, также передавая error, если он предоставлен.

Возвращает значение словаря, хранящееся в этом QCborValue, если оно является словарем. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QCborMap.

См. также isMap(), isArray(), isContainer(), и toArray().

Возвращает значение массива, хранящееся в этом объекте QCborValue, если оно является массивом. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QCborArray.

См. также isArray(), isByteArray(), isMap(), isContainer(), и toMap().

Создаёт QCborValue для расширенного типа, представленного значением тега t, с тегом значения tv. Тег можно получить позднее с помощью tag(), а значение с тегом — с помощью taggedValue().

См. также isTag(), tag(), taggedValue(), и QCborKnownTags.

Создаёт QCborValue с картой m. Карту можно получить позднее с помощью toMap().

См. также toMap(), isMap(), и isArray().

Создаёт QCborValue с массивом a. Массив можно получить позднее с помощью toArray().

См. также toArray(), isArray(), и isMap().

QCborValue::QCborValue(QCborValue &&other)

Это перегруженная функция.

Перемещает содержимое объекта other QCborValue в текущий объект и освобождает ресурсы текущего объекта.

QCborValue::QCborValue(const QCborValue &other)

Копирует содержимое other в текущий объект.

QCborValue::QCborValue(const QUuid &uuid)

Создаёт объект QCborValue расширенного типа UUID, содержащий значение, представленное uuid. Значение можно получить позднее с помощью toUuid().

Тип CBOR UUID — это расширенный тип, представленный массивом байтов с тегом Uuid.

См. также toUuid(), isUuid(), и taggedValue().

QCborValue::QCborValue(const QRegularExpression &rx)

Создаёт объект QCborValue расширенного типа шаблона регулярного выражения, содержащий значение, представленное rx. Значение можно получить позднее с помощью toRegularExpression().

Тип CBOR регулярного выражения — это расширенный тип, представленный строкой, помеченной как RegularExpression. Обратите внимание, что CBOR регулярные выражения хранят только шаблоны, поэтому любые флаги, которые может содержать объект QRegularExpression, будут потеряны.

См. также toRegularExpression(), isRegularExpression(), и taggedValue().

QCborValue::QCborValue(const QUrl &url)

Создаёт объект QCborValue расширенного типа URL, содержащий значение, представленное url. Значение можно получить позднее с помощью toUrl().

Тип CBOR URL — это расширенный тип, представленный строкой, помеченной как Url.

См. также toUrl(), isUrl(), и taggedValue().

QCborValue::QCborValue(const QDateTime &dt)

Создаёт объект QCborValue расширенного типа дата/время, содержащий значение, представленное dt. Значение можно получить позднее с помощью toDateTime().

Типы CBOR дата/время — это расширенные типы с использованием тегов: либо строка (в формате даты ISO) с тегом DateTime, либо число (количество секунд с начала 1970 года, UTC) с тегом UnixTime_t. При парсинге потоков CBOR, QCborValue будет преобразовывать UnixTime_t в строковый тип.

См. также toDateTime(), isDateTime(), и taggedValue().

QCborValue::QCborValue(QLatin1String s)

Это перегруженная функция.

Создаёт QCborValue со строковым значением s. Значение можно получить позднее с помощью toString().

См. также toString(), isString(), и isByteArray().

QCborValue::QCborValue(const QString &s)

Создаёт QCborValue со строковым значением s. Значение можно получить позднее с помощью toString().

См. также toString(), isString(), и isByteArray().

QCborValue::QCborValue(const QByteArray &ba)

Создаёт QCborValue с массивом байтов ba. Значение можно получить позднее с помощью toByteArray().

См. также toByteArray(), isByteArray(), и isString().

QCborValue::QCborValue(QCborSimpleType st)

Создаёт QCborValue простого типа st. Тип можно получить позднее с помощью toSimpleType(), а также isSimpleType(st).

Простые типы CBOR — это типы, не имеющие связанного значения, например, тип C++ std::nullptr_t, единственным возможным значением которого является nullptr.

Если st равно QCborSimpleType::Null, результирующий QCborValue будет типа Null, и аналогично для QCborSimpleType::Undefined. Если st равно QCborSimpleType::False или QCborSimpleType::True, создаваемый QCborValue будет булевым значением, содержащим false или true соответственно.

Эта функция может использоваться с простыми типами, не определёнными в API. Например, чтобы создать QCborValue с простым типом 12, можно написать:

    QCborValue value(QCborSimpleType(12));

Простые типы не следует использовать до публикации спецификации для них, так как другие реализации могут не поддерживать их должным образом. Простые типы с 24 по 31 зарезервированы и не должны использоваться.

isSimpleType(), isNull(), isUndefined(), isTrue(), isFalse()

QCborValue::QCborValue(double d)

Создаёт QCborValue с плавающей точкой значением d. Значение можно получить позднее с помощью toDouble().

Значения с плавающей точкой CBOR отличаются от целочисленных значений. Следовательно, объекты QCborValue с целыми числами будут сравниваться по-разному с объектами QCborValue, содержащими числа с плавающей точкой, даже если значения, содержащиеся в объектах, эквивалентны.

См. также toDouble(), isDouble(), и isInteger().

QCborValue::QCborValue(qint64 i)

Создаёт QCborValue со значением целого типа i. Значение можно получить позднее с помощью toInteger().

Целочисленные значения CBOR отличаются от значений с плавающей точкой. Поэтому объекты QCborValue с целыми числами будут сравниваться по-другому с объектами QCborValue, содержащими значения с плавающей точкой, даже если значения, содержащиеся в объектах, эквивалентны.

См. также toInteger(), isInteger() и isDouble().

QCborValue::QCborValue(bool b)

Создаёт QCborValue с логическим значением b. Значение можно получить позднее с помощью toBool().

Внутренне, булевы значения CBOR представляются парой типов, один для true и один для false. По этой причине, булевые QCborValues вернут true для isSimpleType() и одного из isSimpleType(QCborSimpleType::False) или isSimpleType(QCborSimpleType::True).

См. также toBool(), isBool(), isTrue(), isFalse() и isSimpleType().

QCborValue::QCborValue(std::nullptr_t)

Создаёт QCborValue типа Null.

Значения CBOR null используются для обозначения необязательных значений, которые не были предоставлены. Они отличаются от неопределённых значений тем, что значения null обычно не являются результатом предыдущей ошибки или проблемы.

См. также isNull(), isUndefined() и isSimpleType().

QCborValue::QCborValue(QCborValue::Type t_)

Создаёт QCborValue типа t_. Значение, связанное с таким типом (если оно есть), будет создано по умолчанию.

См. также type().

QCborValue::QCborValue()

Создаёт QCborValue типа Undefined.

Значения CBOR undefined используются для обозначения отсутствующей информации, обычно в результате предыдущей операции, которая не завершилась как ожидалось. Они также используются API QCborArray и QCborMap для обозначения того, что искомый элемент не был найден.

Значения undefined представлены простым типом Undefined. Из-за этого QCborValues с неопределёнными значениями также вернут true для isSimpleType() и isSimpleType(QCborSimpleType::Undefined).

Значения undefined отличаются от значений null.

Объекты QCborValue с неопределёнными значениями также отличаются от недействительных объектов QCborValue. API не будет создавать недействительные QCborValues, но они могут существовать в результате ошибки парсинга.

См. также isUndefined(), isNull() и isSimpleType().

QCborValue &QCborValue::operator=(QCborValue &&other)

Это перегруженный метод.

Перемещает содержимое объекта other QCborValue в этот и освобождает ресурсы этого. Возвращает ссылку на этот объект.

QCborValue &QCborValue::operator=(const QCborValue &other)

Заменяет содержимое этого QCborObject копией other.

QCborValue::~QCborValue()

Удаляет текущий объект QCborValue и освобождает все связанные ресурсы.

int QCborValue::compare(const QCborValue &other) const

Сравнивает это значение и other и возвращает целое число, которое указывает, должно ли это значение сортироваться перед (если результат отрицательный) или после other (если результат положительный). Если функция возвращает 0, два значения равны и содержат одинаковое содержимое.

Если каждый QCborValue содержит массив или карту, сравнение происходит рекурсивно для элементов, содержащихся в них.

Расширенные типы

QCborValue сравнивается как равный QCborValue, содержащий расширенный тип, например, Url и Url, и его эквивалентное обозначенное представление. Таким образом, например, следующее выражение истинно:

    QCborValue(QUrl("https://example.com")) == QCborValue(QCborKnownTags::Url, "https://example.com");

Обратите внимание, что типы Qt, такие как QUrl и QDateTime, будут нормализовывать и иным образом изменять свои аргументы. Вышеприведенное выражение истинно только потому, что строка в правой части - это нормализованное значение, которое QCborValue слева принял бы. Если, например, часть "https" была бы заглавной как в обеих частях, сравнение было бы неудачным. Для получения информации о нормализации, выполняемой QCborValue, обратитесь к документации конструктора, принимающего соответствующий тип Qt.

Порядок сортировки

Порядок сортировки в CBOR определён в RFC 7049 {https://tools.ietf.org/html/rfc7049#section-3.9}{раздел 3.9}, который обсуждает сортировку ключей в карте при соблюдении канонического кодирования. Согласно спецификации, «сортировка выполняется по байтам представления данных ключа» и приводит к тому, что:

• «Если у двух ключей разная длина, короче один сортируется раньше»;
• «Если у двух ключей одинаковая длина, тот, у которого значение меньше (по байтовому) лексикографическому порядку, сортируется раньше».

Это приводит к неожиданной сортировке QCborValues, где результат этой функции отличается от того, что было бы получено позже при сравнении содержащихся элементов. Например, QCborValue, содержащий строку «zzz», сортируется раньше QCborValue со строкой «foobar», даже если при сравнении как QStrings или QByteArrays «zzz» сортируется после «foobar» (лексикографический порядок).

Спецификация не чётко указывает, какой порядок сортировки должен быть выполнен для значений разных типов (в ней говорится, что сортировка не должна учитывать «разделение на 3/5 битов для основных типов»). QCborValue предполагает, что типы также должны сортироваться. Числовые значения перечисления QCborValue::Type находятся в этом порядке, за исключением расширенных типов, которые сравниваются как их эквиваленты с метками.

Примечание: Порядок сортировки предварительный и может быть изменён. Приложения не должны полагаться на порядок, возвращаемый этой функцией, на данный момент.

См. также QCborArray::compare(), QCborMap::compare() и operator==().

[static] QCborValue QCborValue::fromCbor(QCborStreamReader &reader)

Декодирует один элемент из потока CBOR в reader и возвращает эквивалентное представление. Эта функция рекурсивна: если элемент является картой или массивом, она будет декодировать все элементы, найденные в этой карте или массиве, пока не завершится внешний объект.

Эта функция не должна использоваться для корневого элемента QCborStreamReader. Например, следующий код демонстрирует, как пропустить тег подписи CBOR в начале файла:

    if (reader.isTag() && reader.toTag() == QCborKnownTags::Signature)
        reader.next();

    QCborValue contents = QCborValue::fromCbor(reader);

Возвращаемое значение может быть частично завершённым и неотличимым от допустимого QCborValue, даже если декодирование завершилось неудачно. Чтобы определить, произошла ли ошибка, проверьте, указывает ли reader.lastError() на условие ошибки. Эта функция останавливает декодирование сразу после первой ошибки.

См. также toCbor(), toDiagnosticNotation(), toVariant() и toJsonValue().

[static] QCborValue QCborValue::fromCbor(const QByteArray &ba, QCborParserError *error = nullptr)

Это перегруженный метод.

Декодирует один элемент из потока CBOR, найденного в массиве байтов ba, и возвращает эквивалентное представление. Эта функция рекурсивна: если элемент является картой или массивом, она будет декодировать все элементы, найденные в этой карте или массиве, пока не завершится внешний объект.

Эта функция сохраняет состояние ошибки, если оно есть, в объекте, на который указывает error, вместе со смещением, где произошла ошибка. Если ошибка не произошла, она сохраняет NoError в состоянии ошибки и количество израсходованных байтов (то есть, сохраняет смещение для первого неиспользованного байта). Использование этой информации позволяет проанализировать дальнейшие данные, которые могут существовать в том же массиве байтов.

Возвращаемое значение может быть частично завершённым и неотличимым от допустимого QCborValue, даже если декодирование завершилось неудачно. Чтобы определить, была ли ошибка, проверьте, была ли ошибка сохранена в error. Эта функция останавливает декодирование сразу после первой ошибки.

См. также toCbor(), toDiagnosticNotation(), toVariant() и toJsonValue().

[static] QCborValue QCborValue::fromJsonValue(const QJsonValue &v)

Преобразует значение JSON, содержащееся в v, в соответствующее значение CBOR и возвращает его. При преобразовании из JSON в CBOR нет потери данных, так как набор типов CBOR богаче, чем набор типов JSON. Кроме того, значения, преобразованные в CBOR с помощью этой функции, могут быть преобразованы обратно в JSON с помощью toJsonValue() без потери данных.

В следующей таблице перечислены соответствия типов JSON типам CBOR:

QJsonValue также может быть неопределённым, указывая на то, что предыдущая операция не была завершена (например, при поиске ключа, отсутствующего в объекте). Неопределённые значения не являются типами JSON и не могут появляться в массивах и объектах JSON, но эта функция возвращает неопределённое значение QCborValue, если соответствующее QJsonValue неопределённо.

См. также toJsonValue(), fromVariant(), QCborArray::fromJsonArray() и QCborMap::fromJsonObject().

[static] QCborValue QCborValue::fromVariant(const QVariant &variant)

Преобразует QVariant variant в QCborValue и возвращает его.

QVariants могут содержать большой список различных метатипов, многие из которых не имеют соответствующего представления в CBOR. Это включает все пользовательские метатипы. При подготовке передачи данных с использованием CBOR рекомендуется тщательно кодировать каждое значение, чтобы предотвратить потерю представления.

В следующей таблице приведены преобразования, которые выполняет эта функция:

Для других типов эта функция вернёт Null, если QVariant сам по себе равен null, а в противном случае попытается преобразовать в строку с помощью QVariant::toString(). Если преобразование в строку не удалось, функция вернёт Неопределённый.

Обратите внимание, что преобразования через QVariant::toString() могут быть изменены в любое время. QCborValue может быть расширен в будущем для поддержки большего количества типов, что приведёт к изменению работы этой функции при преобразованиях.

См. также toVariant(), fromJsonValue(), QCborArray::toVariantList() и QCborMap::toVariantMap().

bool QCborValue::isArray() const

Возвращает true, если этот QCborValue имеет тип массив. Значение массива можно получить с помощью toArray().

См. также type() и toArray().

bool QCborValue::isBool() const

Возвращает true, если этот QCborValue является булевым значением. Значение можно получить с помощью toBool().

См. также type(), toBool(), isTrue() и isFalse().

bool QCborValue::isByteArray() const

Возвращает true, если этот QCborValue имеет тип массива байтов. Значение массива байтов можно получить с помощью toByteArray().

См. также type() и toByteArray().

bool QCborValue::isContainer() const

Эта вспомогательная функция возвращает true, если QCborValue является либо массивом, либо словарем.

См. также isArray() и isMap().

bool QCborValue::isDateTime() const

Возвращает true, если этот QCborValue имеет тип дата/время. Значение можно получить с помощью toDateTime(). Дата/время — это расширенные типы, которые используют метку DateTime.

Кроме того, при декодировании из потока CBOR, QCborValue будет интерпретировать метки со значением UnixTime_t и преобразовывать их в эквивалентную дату/время.

См. также type() и toDateTime().

bool QCborValue::isDouble() const

Возвращает true, если этот QCborValue имеет тип с плавающей запятой. Значение можно получить с помощью toDouble().

См. также type() и toDouble().

bool QCborValue::isFalse() const

Возвращает true, если этот QCborValue является булевым значением false. Эта функция существует, потому что внутренне булевые значения CBOR хранятся как два отдельных типа, один для true и один для false.

См. также type(), isBool(), isTrue() и toBool().

bool QCborValue::isInteger() const

Возвращает true, если этот QCborValue имеет тип целое число. Целочисленное значение можно получить с помощью toInteger().

См. также type() и toInteger().

bool QCborValue::isInvalid() const

Возвращает true, если этот QCborValue не имеет ни одного допустимого типа. Недействительные QCborValues отличаются от тех, которые имеют неопределённые значения, и обычно представляют ошибку декодирования.

См. также isUndefined() и isNull().

bool QCborValue::isMap() const

Возвращает true, если этот QCborValue имеет тип словарь. Значение словаря можно получить с помощью toMap().

См. также type() и toMap().

bool QCborValue::isNull() const

Возвращает true, если этот QCborValue имеет тип null.

CBOR null значения используются для указания необязательных значений, которые не были предоставлены. Они отличаются от неопределённых значений, поскольку null значения обычно не являются результатом более ранней ошибки или проблемы.

Значения null отличаются от неопределённых значений и от недействительных объектов QCborValue. API не будет создавать недействительные QCborValues, но они могут существовать в результате ошибки разбора.

См. также type(), isUndefined() и isInvalid().

bool QCborValue::isRegularExpression() const

Возвращает true, если этот QCborValue содержит шаблон регулярного выражения. Шаблон можно получить с помощью toRegularExpression().

См. также type() и toRegularExpression().

bool QCborValue::isSimpleType() const

Возвращает true, если этот QCborValue является одним из простых типов CBOR. Сам тип можно получить позже, используя type(), даже для типов, для которых нет перечисления в API. Их также можно проверить с помощью перегрузки isSimpleType(QCborSimpleType).

См. также QCborSimpleType, isSimpleType(QCborSimpleType), и toSimpleType().

bool QCborValue::isSimpleType(QCborSimpleType st) const

Это перегруженный метод.

Возвращает true, если этот QCborValue является простым типом и toSimpleType() вернёт st, в противном случае возвращает false. Этот метод может использоваться для проверки любого простого типа CBOR, даже тех, для которых в API нет перечисления. Например, для простого типа со значением 12, можно написать:

    value.isSimpleType(QCborSimpleType(12));

См. также QCborValue::QCborValue(QCborSimpleType), isSimpleType(), isFalse(), isTrue(), isNull, isUndefined(), и toSimpleType().

bool QCborValue::isString() const

Возвращает true, если этот QCborValue является строкой. Значение строки можно получить с помощью toString().

См. также type() и toString().

bool QCborValue::isTag() const

Возвращает true, если этот QCborValue является тегом. Значение тега можно получить с помощью tag(), а значение, помеченное тегом, с помощью taggedValue().

Этот метод также возвращает true для расширенных типов, которые распознаются API. Для кода, обрабатывающего расширенные типы непосредственно перед обновлением Qt API для их поддержки, можно воссоздать пару тег + помеченное значение, используя taggedValue().

См. также type(), tag(), taggedValue(), и taggedValue().

bool QCborValue::isTrue() const

Возвращает true, если этот QCborValue является булевым значением true. Этот метод существует, потому что в CBOR булевы значения хранятся как два отдельных типа, один для false, а другой для true.

См. также type(), isBool(), isFalse(), и toBool().

bool QCborValue::isUndefined() const

Возвращает true, если этот QCborValue является типом undefined.

Значения undefined CBOR используются для обозначения отсутствия информации, обычно в результате предыдущей операции, которая не была завершена должным образом. Они также используются API QCborArray и QCborMap для указания того, что искомый элемент не найден.

Значения undefined отличаются от значений null.

Объекты QCborValue с undefined значениями также отличаются от недействительных объектов QCborValue. API не создаёт недействительные QCborValue, но они могут существовать в результате ошибки парсинга.

См. также type(), isNull(), и isInvalid().

bool QCborValue::isUrl() const

Возвращает true, если этот QCborValue является URL-адресом. Значение URL можно получить с помощью toUrl().

См. также type() и toUrl().

bool QCborValue::isUuid() const

Возвращает true, если этот QCborValue содержит UUID. Значение можно получить с помощью toUuid().

См. также type() и toUuid().

void QCborValue::swap(QCborValue &other)

Меняет содержимое этого объекта QCborValue и other.

QCborTag QCborValue::tag(QCborTag defaultValue = QCborTag(-1)) const

Возвращает тег этого расширенного объекта QCborValue, если он является типом тега, иначе defaultValue.

CBOR представляет расширенные типы, связывая число (тег) с сохранённым представлением. Этот метод возвращает это число. Для получения представления используйте taggedValue().

См. также isTag(), taggedValue(), isDateTime(), isUrl(), isRegularExpression(), и isUuid().

QCborValue QCborValue::taggedValue(const QCborValue &defaultValue = QCborValue()) const

Возвращает значение, помеченное тегом, этого расширенного объекта QCborValue, если он является типом тега, иначе defaultValue.

CBOR представляет расширенные типы, связывая число (тег) с сохранённым представлением. Этот метод возвращает это представление. Для получения тега используйте tag().

См. также isTag(), tag(), isDateTime(), isUrl(), isRegularExpression(), и isUuid().

bool QCborValue::toBool(bool defaultValue = false) const

Возвращает булево значение, хранящееся в этом QCborValue, если оно является булевым типом. В противном случае возвращает defaultValue.

См. также isBool(), isTrue(), и isFalse().

QByteArray QCborValue::toByteArray(const QByteArray &defaultValue = {}) const

Возвращает массив байтов, хранящийся в этом QCborValue, если он является массивом байтов. В противном случае возвращает defaultValue.

Обратите внимание, что этот метод не выполняет преобразование из других типов в QByteArray.

См. также isByteArray(), isString(), и toString().

QByteArray QCborValue::toCbor(QCborValue::EncodingOptions opt = NoTransformation)

Кодирует этот объект QCborValue в его представление CBOR, используя указанные в opt опции, и возвращает массив байтов, содержащий это представление.

Этот метод не завершится ошибкой, за исключением случаев, когда этот QCborValue или любой из содержащихся элементов, если это массив или словарь, являются недействительными. Недействительные типы обычно не создаются API, но могут возникнуть из-за ошибок декодирования.

По умолчанию этот метод не выполняет преобразования значений в QCborValue, записывая все значения с плавающей точкой напрямую как значения двойной точности (double) типов. Если задана опция UseFloat, она будет использовать одинарную точность (float) для любых значений с плавающей точкой, для которых нет потери точности при использовании этого представления. Это включает бесконечности и NaN значения.

Аналогично, если задана опция UseFloat16, этот метод попытается использовать значения с плавающей точкой полуточной точности (qfloat16) если преобразование в это значение не приведёт к потере точности. Это всегда верно для бесконечностей и NaN значений.

Если задана опция UseIntegers, она будет использовать целые числа для любых значений с плавающей точкой, которые содержат фактическое целое число.

См. также fromCbor(), fromVariant(), и fromJsonValue().

void QCborValue::toCbor(QCborStreamWriter &writer, QCborValue::EncodingOptions opt = NoTransformation)

Это перегруженный метод.

Кодирует этот объект QCborValue в его представление CBOR, используя указанные в opt опции, для указанного в writer записывающего устройства. Одно и то же записывающее устройство можно использовать для нескольких QCborValue, например, для кодирования разных элементов в более крупном массиве.

Этот метод не завершится ошибкой, за исключением случаев, когда этот QCborValue или любой из содержащихся элементов, если это массив или словарь, являются недействительными. Недействительные типы обычно не создаются API, но могут возникнуть из-за ошибок декодирования.

По умолчанию этот метод не выполняет преобразования значений в QCborValue, записывая все значения с плавающей точкой напрямую как значения двойной точности (binary64) типов. Если задана опция UseFloat, она будет использовать одинарную точность (binary32) для любых значений с плавающей точкой, для которых нет потери точности при использовании этого представления. Это включает бесконечности и NaN значения.

Аналогично, если задана опция UseFloat16, этот метод попытается использовать значения с плавающей точкой полуточной точности (binary16) если преобразование в это значение не приведёт к потере точности. Это всегда верно для бесконечностей и NaN значений.

Если задана опция UseIntegers, она будет использовать целые числа для любых значений с плавающей точкой, которые содержат фактическое целое число.

См. также fromCbor(), fromVariant(), и fromJsonValue().

QDateTime QCborValue::toDateTime(const QDateTime &defaultValue = {}) const

Возвращает значение даты/времени, хранящееся в этом QCborValue, если оно имеет тип расширенной даты/времени. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QDateTime.

См. также isDateTime(), isTag() и taggedValue().

QString QCborValue::toDiagnosticNotation(QCborValue::DiagnosticNotationOptions opts = Compact) const

Создаёт диагностическое представление этого объекта CBOR и возвращает его. Параметр opts управляет диалектом записи. Диагностическое представление полезно при отладке, чтобы помочь разработчику понять, какое значение хранится в QCborValue или в потоке CBOR. По этой причине API Qt не поддерживает разбор диагностического представления обратно в формат в памяти или поток CBOR, хотя представление уникально и его можно было бы реализовать.

Диагностическое представление CBOR определяется в разделе 6 RFC 7049. Это текстовое представление потока CBOR, очень похожее на JSON, но оно поддерживает типы CBOR, которых нет в JSON. Расширенный формат, разрешённый флагом ExtendedFormat, в настоящее время находится на стадии обсуждения в некоторых черновиках IETF, и его формат может измениться.

Эта функция создаёт эквивалентное представление потока, которое создало бы toCbor() без каких-либо параметров преобразования, указанных там. Это также подразумевает, что эта функция может не создать представление потока, использовавшегося для создания объекта, если он был создан с помощью fromCbor(), так как эта функция может применить преобразования. Для высокоточного представления потока без преобразований см. пример cbordump.

См. также toCbor() и QJsonDocument::toJson().

double QCborValue::toDouble(double defaultValue = 0) const

Возвращает значение с плавающей запятой, хранящееся в этом QCborValue, если оно имеет тип Double. Если оно имеет тип Integer, эта функция возвращает целочисленное значение, преобразованное в double. В противном случае возвращает defaultValue.

См. также isDouble(), isInteger() и toInteger().

qint64 QCborValue::toInteger(qint64 defaultValue = 0) const

Возвращает целое значение, хранящееся в этом QCborValue, если оно имеет целочисленный тип. Если оно имеет тип Double, эта функция возвращает значение с плавающей запятой, преобразованное в целое число. В противном случае возвращает defaultValue.

См. также isInteger(), isDouble() и toDouble().

QJsonValue QCborValue::toJsonValue() const

Преобразует этот объект QCborValue в эквивалентное представление в JSON и возвращает его как QJsonValue.

Обратите внимание, что CBOR содержит более богатый и широкий набор типов, чем JSON, поэтому при этом преобразовании может потеряться некоторая информация. В следующей таблице сравниваются типы CBOR и JSON, а также указывается, может ли произойти потеря информации или нет.

Сведения о преобразовании ключей карты CBOR в строку см. в QCborMap::toJsonObject().

Если этот QCborValue содержит неопределённое значение, эта функция также вернёт неопределённое QJsonValue. Обратите внимание, что JSON не поддерживает неопределённые значения, а неопределённые QJsonValue являются расширением спецификации. Они не могут храниться в QJsonArray или QJsonObject, но могут возвращаться функциями для указания ошибки. Во всех остальных случаях они такие же, как null.

Особо обрабатываемые теги и расширенные типы

Некоторые теги обрабатываются особым образом и изменяют преобразование помеченного значения из CBOR в JSON. В следующей таблице перечислены эти особые случаи:

См. также fromJsonValue(), toVariant(), QCborArray::toJsonArray() и QCborMap::toJsonObject().

QRegularExpression QCborValue::toRegularExpression(const QRegularExpression &defaultValue = {}) const

Возвращает значение регулярного выражения, хранящееся в этом QCborValue, если оно имеет тип расширенного шаблона регулярного выражения. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QRegularExpression.

См. также isRegularExpression(), isTag() и taggedValue().

QCborSimpleType QCborValue::toSimpleType(QCborSimpleType defaultValue = QCborSimpleType::Undefined) const

Возвращает тип простого значения, которому принадлежит этот QCborValue, если это простой тип. Если это не простой тип, возвращает defaultValue.

Следующие типы являются простыми типами, и эта функция вернёт указанные значения:

См. также type(), isSimpleType(), isBool(), isTrue(), isFalse(), isTrue(), isNull() и isUndefined().

QString QCborValue::toString(const QString &defaultValue = {}) const

Возвращает строковое значение, хранящееся в этом QCborValue, если оно имеет строковый тип. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QString.

См. также isString(), isByteArray() и toByteArray().

QUrl QCborValue::toUrl(const QUrl &defaultValue = {}) const

Возвращает значение URL, хранящееся в этом QCborValue, если оно имеет тип расширенного URL. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QUrl.

См. также isUrl(), isTag() и taggedValue().

QUuid QCborValue::toUuid(const QUuid &defaultValue = {}) const

Возвращает значение UUID, хранящееся в этом QCborValue, если оно имеет тип расширенного UUID. В противном случае возвращает defaultValue.

Обратите внимание, что эта функция не выполняет преобразование из других типов в QUuid.

См. также isUuid(), isTag() и taggedValue().

QVariant QCborValue::toVariant() const

Преобразует это значение в родной тип Qt и возвращает соответствующий QVariant.

В следующей таблице показано отображение между типами QCborValue и метатипами Qt.

Обратите внимание, что значения в картах и массивах CBOR также преобразуются рекурсивно с помощью этой функции и помещаются в QVariantMap и QVariantList соответственно. Вы не найдете QCborMap и QCborArray внутри QVariants.

QVariantMaps имеют строковые ключи, в отличие от CBOR, поэтому преобразование QCborMap в QVariantMap предполагает «строковое представление» значений ключей. Подробнее см. QCborMap::toJsonObject().

См. также fromVariant(), toJsonValue(), QCborArray::toVariantList() и QCborMap::toVariantMap().

QCborValue::Type QCborValue::type() const

Возвращает тип этого QCborValue. Тип также может быть получен позже с помощью одной из функций «isXxx».

См. также isInteger(), isByteArray(), isString(), isArray(), isMap(), isTag(), isFalse(), isTrue(), isBool(), isNull(), isUndefined(), isDouble(), isDateTime(), isUrl(), isRegularExpression() и isUuid().

bool QCborValue::operator!=(const QCborValue &other) const

Сравнивает это значение и other и возвращает true, если содержимое отличается, и false в противном случае. Если каждый QCborValue содержит массив или карту, сравнение рекурсивно выполняется для элементов, содержащихся в них.

Дополнительную информацию о равенстве CBOR в Qt см. в QCborValue::compare().

См. также compare(), QCborValue::operator==(), QCborMap::operator==(), operator==() и operator<().

bool QCborValue::operator<(const QCborValue &other) const

Сравнивает это значение и other и возвращает true, если это значение должно быть отсортировано перед other, и false в противном случае. Если каждый QCborValue содержит массив или карту, сравнение рекурсивно выполняется для элементов, содержащихся в них.

Дополнительную информацию об порядке сортировки CBOR см. в QCborValue::compare().

См. также compare(), QCborValue::operator==(), QCborMap::operator==(), operator==() и operator!=().

bool QCborValue::operator==(const QCborValue &other) const

Сравнивает это значение и other и возвращает true, если они содержат одинаковое содержимое, и false в противном случае. Если каждый QCborValue содержит массив или карту, сравнение рекурсивно выполняется для элементов, содержащихся в них.

Дополнительную информацию о равенстве CBOR в Qt см. в compare().

См. также compare(), QCborValue::operator==(), QCborMap::operator==(), operator!=() и operator<().

const QCborValue QCborValue::operator[](const QString &key) const

Если этот QCborValue является QCborMap, ищет элементы со значением, ключ которого совпадает с key. Если в карте нет ключа, соответствующего key, или если этот QCborValue не является картой, возвращает значение undefined.

Эта функция эквивалентна:

    value.toMap().value(key);

См. также operator[](qint64), QCborMap::operator[], QCborMap::value() и QCborMap::find().

const QCborValue QCborValue::operator[](QLatin1String key) const

Это перегруженная функция.

Если этот QCborValue является QCborMap, ищет элементы со значением, ключ которого совпадает с key. Если в карте нет ключа, соответствующего key, или если этот QCborValue не является картой, возвращает значение undefined.

Эта функция эквивалентна:

    value.toMap().value(key);

См. также operator[](qint64), QCborMap::operator[], QCborMap::value() и QCborMap::find().

const QCborValue QCborValue::operator[](qint64 key) const

Это перегруженная функция.

Если этот QCborValue является QCborMap, ищет элементы со значением, ключ которого совпадает с key. Если это QCborArray, возвращает элемент с индексом key. Если соответствующего значения в массиве или карте нет, или если этот QCborValue не является массивом или картой, возвращает значение undefined.

См. также operator[], QCborMap::operator[], QCborMap::value(), QCborMap::find(), QCborArray::operator[] и QCborArray::at().

QCborValueRef QCborValue::operator[](qint64 key)

Это перегруженная функция.

Возвращает QCborValueRef, который можно использовать для чтения или изменения записи в этом объекте как в карте, так и в массиве, с заданным key. Когда этот QCborValue является QCborMap или, для 0 <= key < 0x10000, QCborArray, эта функция эквивалентна соответствующему оператору [] для этой карты или массива.

Прежде чем вернуть ссылку: если этот QCborValue был массивом, но ключ вне диапазона, массив сначала преобразуется в карту (так что map[i] является array[i] для каждого индекса, i, с допустимым array[i]); в противном случае, если это не карта, она будет перезаписана пустой картой.

См. также operator[], QCborMap::operator[], QCborMap::value(), QCborMap::find(), QCborArray::operator[] и QCborArray::at().

QCborValueRef QCborValue::operator[](QLatin1String key)

Это перегруженная функция.

Возвращает QCborValueRef, который можно использовать для чтения или изменения записи в этом объекте, рассматриваемом как словарь, с заданным ключом. Когда этот QCborValue является QCborMap, эта функция эквивалентна соответствующему оператору [] для этого словаря.

Перед возвратом ссылки: если этот QCborValue был массивом, он сначала преобразуется в словарь (так что map[i] является array[i] для каждого индекса, i, с допустимыми array[i]); в противном случае, если это не словарь, он будет перезаписан пустым словарем.

См. также operator[](qint64), QCborMap::operator[], QCborMap::value() и QCborMap::find().

QCborValueRef QCborValue::operator[](const QString &key)

Возвращает QCborValueRef, который можно использовать для чтения или изменения записи в этом объекте, рассматриваемом как словарь, с заданным ключом. Когда этот QCborValue является QCborMap, эта функция эквивалентна соответствующему оператору [] для этого словаря.

Перед возвратом ссылки: если этот QCborValue был массивом, он сначала преобразуется в словарь (так что map[i] является array[i] для каждого индекса, i, с допустимыми array[i]); в противном случае, если это не словарь, он будет перезаписан пустым словарем.

См. также operator[](qint64), QCborMap::operator[], QCborMap::value() и QCborMap::find().