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

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++ Стандартной библиотеки std::optional, когда он не используется. В отличие от C++-типа, CBOR null имеет просто тип «Null», и определить, какой конкретный тип он заменяет, невозможно.

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

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

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

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

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

QCborValue::QCborValue(std::nullptr_t)

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

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

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

QCborValue::QCborValue(QCborValue::Type t_)

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

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

QCborValue::QCborValue()

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

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

Неопределённые значения представлены неопределённым простым типом Undefined simple type. По этой причине QCborValue с неопределёнными значениями также будут возвращать true для isSimpleType() и isSimpleType(QCborSimpleType::Undefined).

Неопределённые значения отличаются от нулевых значений.

Объекты QCborValue с неопределёнными значениями также отличаются от некорректных объектов 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 {https://tools.ietf.org/html/rfc7049#section-3.9}{раздел 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 является нулевым значением.

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

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

Значения undefined в CBOR используются для обозначения отсутствующей информации, обычно в результате предыдущей операции, которая не завершилась должным образом. Они также используются 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) 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. Один и тот же объект writer может использоваться несколькими QCborValue, например, для кодирования различных элементов в более крупном массиве.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QJsonValue QCborValue::toJsonValue() const

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

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

Дополнительную информацию о преобразовании ключей карты CBOR в строку см. в QCborMap::toJsonObject().

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

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

    value.toMap().value(key);

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

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

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

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

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

    value.toMap().value(key);

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

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

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

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

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

QCborValueRef QCborValue::operator[](qint64 key)

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

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

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

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

QCborValueRef QCborValue::operator[](QLatin1String key)

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

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