Класс 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, которое связано с числом, являющимся его тегом. Дополнительную информацию о тегах в API, а также полный официальный список см. в QCborKnownTags. Такие комбинации образуют расширенные типы.

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

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

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

Неопределённые и нулевые значения

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

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

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

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

Эти значения вполне допустимы и могут появляться в потоках CBOR, в отличие от содержимого JSON и QJsonValueundefined. Но, как и 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. Это тип, который вы получаете при использовании одного из изменяющих API в этих классах. В отличие от 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, объединённых по оператору OR.

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

enum QCborValue::EncodingOptionflags QCborValue::EncodingOptions

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

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

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

См. также 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 для расширенного типа, представленного значением тега tag, со значением тегирования 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(QStringView 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 в C++, единственное возможное значение которого — 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 can also be undefined, indicating a previous operation that failed to complete (for example, searching for a key not present in an object). Undefined values are not JSON types and may not appear in JSON arrays and objects, but this function does return the QCborValue undefined value if the corresponding QJsonValue is undefined.

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

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

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

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

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

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

Обратите внимание, что преобразования через 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 является булевым значением с ложным значением. Эта функция существует, потому что внутренне булевы значения CBOR хранятся как два отдельных типа, один для true, и один для false.

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

bool QCborValue::isInteger() const

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

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

bool QCborValue::isInvalid() const

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

См. также 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.

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

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

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

См. также 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 precision (double) . Если указан параметр UseFloat, он будет использовать single precision (float) для чисел с плавающей точкой, для которых нет потери точности при использовании этого представления. Это включает бесконечности и NaN.

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

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

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

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

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

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

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

По умолчанию эта функция не выполняет преобразования значений в QCborValue, записывая все числа с плавающей точкой непосредственно в формате double precision (binary64) . Если указан параметр UseFloat, он будет использовать single precision (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 не поддерживает неопределённые значения, и неопределённые QJsonValues являются расширением спецификации. Они не могут храниться в 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, сохранённые внутри QVariant.

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 не является словарем, возвращает неопределённое значение.

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

    value.toMap().value(key);

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

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

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

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

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

    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 не является массивом или словарем, возвращает неопределённое значение.

См. также 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, который можно использовать для чтения или изменения записи в этом объекте, как в словаре, с заданным key. Когда этот 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, который можно использовать для чтения или изменения записи в этом объекте, как в словаре, с заданным key. Когда этот QCborValue является QCborMap, эта функция эквивалентна соответствующему оператору [] для этого словаря.

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

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