Класс QCborValue

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

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

Примечание: Все функции в этом классе являются повторно входящими.

Публичные типы

Публичные функции

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

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

Этот класс может использоваться для хранения одного из многих типов, доступных в 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());

Значения Undefined и null

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

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

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

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

Такие значения полностью допустимы и могут появляться в CBOR-потоках, в отличие от содержимого JSON и undefined-бита QJsonValue. Но, как и Undefined в QJsonValue, оно возвращается значением() или чтением-только оператором [] для невалидных запросов (индекс вне диапазона для 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.

См. также 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 для расширенного типа, представленного значением тега 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, единственное возможное значение которого 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. По этой причине булевые QCborValue будут возвращать 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 simple type. Из-за этого QCborValue с undefined значениями также вернут true для isSimpleType() и isSimpleType(QCborSimpleType::Undefined).

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

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

См. также 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 раздел 3.9, который описывает сортировку ключей в словаре при использовании канонического кодирования. Согласно спецификации, "сортировка выполняется по байтам представления данных ключей" и приводит к следствиям:

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

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

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

Если QVariant::isNull() возвращает true, возвращается или вставляется нулевое QCborValue в список или объект, независимо от типа, который несет QVariant. Обратите внимание на изменение поведения в Qt 6.0, затрагивающее QVariant::isNull(), которое также влияет на эту функцию.

Для других типов, не перечисленных выше, будет предпринята попытка преобразования в строку, обычно, но не всегда, вызывая QVariant::toString(). Если преобразование не удаётся, значение заменяется неопределённым значением CBOR. Обратите внимание, что QVariant::toString() также приводит к потерям данных для большинства типов.

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

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

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 не имеет какого-либо допустимого типа. Недействительные QCborValue отличаются от неопределённых значений, и они обычно представляют ошибку декодирования.

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

bool QCborValue::isMap() const

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

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

bool QCborValue::isNull() const

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

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

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

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

Объекты QCborValue с неопределёнными значениями также отличаются от невалидных объектов 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) const

Кодирует этот объект 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) const

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

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

Этот метод не будет завершаться с ошибкой, кроме случаев, если этот 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 содержит значение undefined, эта функция также вернёт undefined QJsonValue. Обратите внимание, что JSON не поддерживает значения undefined, а undefined 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.

QVariantMap имеют строковые ключи, в отличие от 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, которая может быть использована для чтения или изменения записи в этой карте с заданным ключом. Когда этот 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().