Класс QCborValue

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

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

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

Открытые типы

Открытые функции

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

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

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

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

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

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

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

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

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

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

Эти значения полностью допустимы и могут появляться в потоках CBOR, в отличие от содержимого JSON и QJsonValue неопределённости. Но, как и неопределённость QJsonValue, она возвращается методом QCborArray::value() при выходе за пределы диапазона или QCborMap::operator[] при отсутствии ключа в контейнере. Невозможно отличить такой случай от значения 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.

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

перечисление QCborValue::DiagnosticNotationOptionфлаги QCborValue::DiagnosticNotationOptions

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

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

Тип DiagnosticNotationOptions — это typedef для QFlags<DiagnosticNotationOption>. Он хранит сочетание значений DiagnosticNotationOption.

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

перечисление QCborValue::EncodingOptionфлаги QCborValue::EncodingOptions

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

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

Тип EncodingOptions — это typedef для QFlags<EncodingOption>. Он хранит сочетание значений EncodingOption.

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

перечисление QCborValue::Type

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

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

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

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

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

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

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

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

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

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

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

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

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

QCborValue::QCborValue()

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

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

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

Значения Undefined отличаются от значений Null.

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

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

QCborValue::QCborValue(QCborValue::Type t_)

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

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

QCborValue::QCborValue(std::nullptr_t)

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

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

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

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(qint64 i)

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

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

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

QCborValue::QCborValue(double d)

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

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

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

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(const QByteArray &ba)

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

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

QCborValue::QCborValue(const QString &s)

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

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

QCborValue::QCborValue(QLatin1String s)

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

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

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

QCborValue::QCborValue(const char *s)

Создаёт экземпляр QCborValue по умолчанию.

QCborValue::QCborValue(const QDateTime &dt)

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

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

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

QCborValue::QCborValue(const QUrl &url)

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

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

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

QCborValue::QCborValue(const QRegularExpression &rx)

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

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

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

QCborValue::QCborValue(const QUuid &uuid)

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

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

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

QCborValue::QCborValue(const void *)

Инициализирует экземпляр QCborValue по умолчанию.

QCborValue::QCborValue(const QCborValue &other)

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

QCborValue::QCborValue(QCborValue &&other)

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

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

QCborValue::~QCborValue()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    QCborValue contents = QCborValue::fromCbor(reader);

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

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

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

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

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

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

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

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

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

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

В следующей таблице показано соответствие типов JSON типам CBOR:

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

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

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

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

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

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

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

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

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

bool QCborValue::isArray() const

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

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

bool QCborValue::isBool() const

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

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

bool QCborValue::isByteArray() const

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

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

bool QCborValue::isContainer() const

Эта вспомогательная функция возвращает true, если QCborValue является либо массивом, либо 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 является булевым значением 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 имеет тип map. Значение map можно получить, используя toMap().

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

bool QCborValue::isNull() const

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

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

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

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

bool QCborValue::isUndefined() const

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

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

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

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

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

bool QCborValue::isUrl() const

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

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

bool QCborValue::isUuid() const

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

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

void QCborValue::swap(QCborValue &other)

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

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

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

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

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

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

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

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

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

QCborArray QCborValue::toArray(const QCborArray &defaultValue) const

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

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

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

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. Один и тот же объект 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, если оно имеет тип Integer. Если оно имеет тип 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().

QCborMap QCborValue::toMap(const QCborMap &defaultValue) const

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

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

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

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!=().

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

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

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

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

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

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. Если это массив, возвращает элемент с индексом key. Если соответствующее значение не найдено в массиве или словаре, или если этот объект QCborValue не является массивом или словарем, возвращает неопределенное значение.

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