Класс 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());

Значения 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++'s 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 simple type. Поэтому 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 undefined, если соответствующее значение 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 является массивом или map.

См. также 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 отличаются от значений undefined, и они обычно представляют ошибку декодирования.

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

bool QCborValue::isMap() const

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

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

bool QCborValue::isNull() const

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

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

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

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

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

Перед возвратом ссылки: если этот 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, эта функция эквивалентна соответствующему operator[] для этой карты.

Перед возвратом ссылки: если этот 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, эта функция эквивалентна соответствующему operator[] для этой карты.

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

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